Centro de soporte
Guía completa de la plataforma para administradores, secretaría, tesorería, maestros y familias: qué hace cada parte, cómo configurarla y cómo conectarla con otros programas mediante la API y los webhooks.
Cómo usar esta guía. Busca con Ctrl+F (Cmd+F en Mac) o salta con el índice. Las funciones disponibles dependen del plan de tu comunidad: en Administración → Módulos ves lo que incluye. Si algo no coincide con tu pantalla, escríbenos desde la pestaña Soporte de la plataforma o a contact@keshercloud.com.
1. Empezar
Qué es KesherCloud
Una plataforma de gestión para sinagogas y comunidades judías, en español e inglés. Cada comunidad tiene su propia instalación independiente (su base de datos, sus copias y su dirección), alojada y mantenida por nosotros. Los datos son de la comunidad: puede exportarlos completos cuando quiera.
Primer acceso
- Nosotros creamos tu instalación y el primer administrador. La contraseña la eliges tú (mínimo 12 caracteres; una frase larga es mejor): nadie más la ve.
- Al iniciar sesión, activa la verificación en dos pasos: añade la clave que aparece a una aplicación de códigos (Google Authenticator, Aegis, 1Password…) y escribe el código de 6 cifras. Es obligatoria para todas las cuentas del personal.
- Elige tu idioma con el botón ES / EN de la barra superior. La elección se recuerda.
- Crea las cuentas de tu equipo en Administración → Usuarios y asígnales un rol (sección 2).
Si pierdes el teléfono o la contraseña
Escríbenos desde otra cuenta de administración o a contact@keshercloud.com indicando el usuario afectado. Restablecemos el acceso con una contraseña provisional y quitamos el segundo factor; el cambio queda registrado en la auditoría de tu comunidad (ver sección 15). Antes de hacerlo verificamos que la petición viene de un administrador de la comunidad.
El menú principal
- Comunidad: familias, yortzait, eventos, honores, asientos, campañas, cuotas, escuela, cementerio, espacios y reservas, correo, avisos de duelo, contabilidad y datos de la comunidad.
- Administración: usuarios, roles, apariencia, módulos, auditoría, correo, pagos y sistema (copias).
- Soporte: tickets con nuestro equipo.
- Ayuda: breve ayuda de cada pantalla.
- Mi cuenta: tu contraseña, tu segundo factor y tu idioma.
2. Roles y permisos
Un rol es un conjunto de permisos. Cada persona del equipo recibe uno o más. La plataforma sigue el principio de mínimo privilegio: cada cargo ve solo lo que necesita.
| Rol | Puede | No puede |
|---|---|---|
| Administrador | Todo: usuarios, roles, apariencia, módulos, auditoría, pagos, correo, exportar los datos | — |
| Secretaría | Altas y cambios de familias, eventos, honores, asientos, espacios, reservas, correo masivo, importar y exportar, datos de la comunidad; ver cuotas, escuela y cementerio | Modificar cuotas o pagos; configurar pagos en línea |
| Tesorería | Generar cuotas, registrar pagos, aplicar créditos, emitir recibos, donaciones, contabilidad, configurar pagos en línea | Correo masivo, borrar o importar, escuela, cementerio |
| Rabino(a) | Miembros, yortzait, eventos, correo a toda la comunidad, escuela, entierros y parcelas, reservas | Ver las cuentas, cuotas o pagos de las familias |
| Docente | Sus clases: alumnos, asistencia e informes | Cualquier otra parte |
| Gabay | Eventos, honores, asientos, yortzait, espacios, reservas y la ficha de las familias | Cuotas, pagos, correo masivo, borrar, escuela, cementerio |
| Miembro (portal) | Ver y cambiar solo lo suyo en el portal (sección 13) | Todo lo demás |
- Puedes editar los roles, crear los tuyos y marcar permiso por permiso en Administración → Roles. Los roles predefinidos se crean una sola vez: si los cambias, no se vuelven a pisar.
- Ningún rol salvo Administrador gestiona usuarios, roles, apariencia, auditoría ni el estado del sistema.
- El rol «Administrador» siempre existe y siempre tiene todos los permisos.
3. Familias y personas
Comunidad → Familias. Cada familia tiene tipo de membresía, estado, contacto y dirección, y sus personas (parentesco, nombre hebreo, nacimiento).
- Buscar por nombre y filtrar por estado.
- Importar desde un CSV (opción Importar familias): una fila por persona; columnas en español o inglés; vista previa que no guarda nada; las familias que ya existen se omiten; fechas día/mes/año o mes/día/año; hay una plantilla descargable.
- Exportar a CSV (permiso de gestión). Para llevarte todos los datos de la comunidad, mira la sección 16.
- Borrar una familia exige permiso de gestión y queda en la auditoría.
4. Calendario hebreo y yortzait
El calendario hebreo es propio de la plataforma e incluye las reglas de Heshvan y Kislev y de Adar I/II. En la ficha de cada persona fallecida:
- Se guarda la fecha de fallecimiento; la plataforma calcula la fecha hebrea y el próximo yortzait. Hay una opción para fallecimientos después de la puesta del sol.
- Comunidad → Yortzait lista los próximos 14 a 365 días y el panel de inicio los avisa.
- Las familias añaden y quitan los suyos desde el portal.
Nota. Hoy la plataforma muestra los yortzait en el panel; no envía todavía recordatorios automáticos por correo.
5. Eventos e inscripciones
Comunidad → Eventos. Calendario con fecha hebrea, aforo, precio, inscripción por familia o invitado, y lista de espera con ascenso automático cuando alguien cancela. Registra asistencia y pago.
- Un evento puede ligarse a un espacio: el aforo del evento no puede superar el del espacio y la plataforma avisa si el espacio ya está ocupado a esa hora.
- Desde la ficha del evento puedes escribir a los inscritos.
- Las familias se inscriben y cancelan desde el portal.
6. Correo a las familias
Comunidad → Correo. Envía a todas las familias, a un tipo de membresía o a los inscritos de un evento. Usa los campos {{familia}} y {{titular}} para personalizar. Cada envío queda registrado por destinatario.
Configurar el servidor de correo
Administración → Correo (solo el administrador). Elige el tipo:
- Resend (API por HTTPS): recomendado en el alojamiento gestionado. Solo necesitas la clave de API y la dirección del remitente.
- Zoho Mail (API por HTTPS): con un Self Client de Zoho.
- Servidor SMTP: para quien tenga el suyo.
Importante. El proveedor de los servidores donde alojamos las comunidades bloquea el SMTP saliente (puertos 25, 465 y 587). Usa Resend o Zoho Mail por API, que salen por HTTPS.
Un dominio por sí solo no envía correo. Hace falta un servicio de envío y tres registros DNS en tu dominio:
| Registro | Para qué |
|---|---|
| SPF (TXT en la raíz) | Autoriza al servicio a enviar en nombre de tu dominio. Solo puede haber un SPF por dominio: si ya existe, se une al existente. |
| DKIM (normalmente 3 CNAME) | Firma cada mensaje. |
DMARC (TXT en _dmarc) | Qué hacer con lo que no pase SPF/DKIM. Empieza con v=DMARC1; p=none; rua=mailto:alguien@tu-dominio y endurece después. |
Usa Enviar prueba (llega solo a quien administra) y comprueba que va a la bandeja de entrada y no a spam. La clave se guarda cifrada y no se vuelve a mostrar. Sin servidor configurado el envío es simulado: se anota pero no sale nada.
7. Avisos de duelo (hodaot)
Comunicación → Avisos de duelo. Prepara el aviso de un fallecimiento y lo envía a los miembros.
- Nuevo aviso: elige el idioma del aviso (hebreo, español o inglés, independiente del idioma del panel), el sexo, el nombre, tratamiento, sigla de memoria, parentesco, fecha, hora, lugar y apellido de la familia.
- Proponer el texto: la plataforma rellena cada línea de la plantilla con el texto habitual del idioma, con el género y parentesco concordados y la fecha hebrea. Cada línea se puede corregir a mano: lo que ves es lo que sale.
- Guardar: obtienes la imagen del aviso (PNG, para compartir) y un PDF para imprimir.
- Enviar a los miembros: primero «Enviarme una prueba» y luego el envío a todas las familias activas con correo o a un tipo de familia. El correo lleva el texto y la imagen adjunta. Queda registrado como cualquier envío masivo.
Ver y editar avisos exige permisos de comunidad; enviar y borrar exige gestión de la comunidad.
8. Espacios y reservas (incluido el mikvé)
Comunidad → Espacios. Los espacios físicos (santuario, salón, biblioteca, aulas, cocina, mikvé…) con nombre, tipo, aforo y dirección. Los eventos y las clases se ligan a un espacio y la plataforma evita choques.
Reservas
En cada espacio, sección «Reservas de este espacio»:
- Acepta solicitudes de reserva (por defecto no).
- La secretaría debe aprobar cada solicitud (por defecto sí).
- Duración fija (p. ej. 60 minutos para el mikvé).
- Roles que pueden pedirlo desde el portal. Si marcas «Miembro (portal)», las familias verán y podrán reservar ese espacio; si no lo marcas, no les aparece. La comprobación se hace en el servidor.
La familia reserva desde el portal (Reservar espacios), ve el estado (pendiente, confirmada, rechazada con nota, cancelada) y puede cancelar las suyas.
La secretaría gestiona Culto y eventos → Reservas (permiso reservas.gestionar): confirma o rechaza con una nota, reserva en nombre de una familia o cancela una reserva confirmada. Una reserva confirmada ocupa el espacio; una pendiente no. Nunca se confirma una reserva que choque con otra o con un evento.
Avisos por correo: a la secretaría cuando entra una solicitud y a la familia cuando se resuelve. Por privacidad, el correo no lleva las notas de la familia y, en el mikvé, tampoco su nombre: eso solo se ve dentro del panel.
9. Honores, asientos y campañas
- Honores (gabbai): aliyot y otros kibudim por fecha y ocasión, con promesa. El panel «¿a quién le toca?» ordena por kohen, levi e israel (quien lleva más tiempo sin honor).
- Asientos de las Altas Fiestas: secciones con asientos numerados, asignación a familias o invitados, liberación y cobro a la cuenta de cada familia sin cobrar dos veces.
- Campañas y donaciones: campañas (donación, Shalaj Manot, Maot Jitim…) con meta y progreso; donaciones con «en memoria de» y opción anónima (el nombre solo lo ve quien edita); resumen anual imprimible por familia.
10. Cuotas, pagos y recibos
Comunidad → Cuotas.
- Fija el importe por tipo de membresía y genera la cuota anual para todas las familias (idempotente: no duplica).
- Crea cargos manuales y elige su concepto.
- Cada pago se aplica a un cargo concreto (membresía, asiento, matrícula…), no a «la deuda en general». Cada cargo está pendiente, parcial o pagado.
- Si un pago supera lo que falta, el sobrante queda como crédito a favor de la familia, que se aplica después a otro cargo.
- Anular un cargo devuelve lo aplicado como crédito.
- Estado de cuenta imprimible, saldos, vencidos y CSV.
Recibos
Un cargo pagado por completo tiene un enlace Recibo (para el personal y en Mi cuenta del portal). Es imprimible, lleva el nombre, dirección e identificación fiscal de la comunidad, el concepto, el importe y los pagos aplicados. Tiene un número propio y estable (R-AAAA-NNNN). Completa Comunidad → Datos de la comunidad (país, estado, EIN u otra identificación) para que salgan bien.
11. Pagos en línea
Administración → Pagos (permiso pagos.gestionar). Hay cuatro opciones:
- Stripe y PayPal: cuotas y donaciones.
- Donorbox: solo donaciones.
- Una pasarela simulada para pruebas y demostración.
Principios
- KesherCloud nunca ve datos de tarjeta: se paga en la página del proveedor.
- Cada comunidad usa su propia cuenta del proveedor: el dinero va directo a ella y nosotros no lo custodiamos.
- El importe sale siempre de los datos de la plataforma, nunca del navegador.
- Un proveedor activo por instalación.
Conectar Stripe (modo de pruebas primero)
- En Stripe, con el modo de pruebas activado, copia la clave secreta (
sk_test_…). - En Administración → Pagos pégala y guarda. Se almacena cifrada y nunca se vuelve a mostrar.
- En Stripe, Developers → Webhooks → Add endpoint, con la dirección que muestra la pantalla (
https://TU-INSTALACION/payments/webhook/stripe) y estos eventos:checkout.session.completed,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed,checkout.session.expiredycharge.refunded. Copia el secreto de firma (whsec_…) en el segundo campo. - Probar la conexión (debe decir modo de pruebas) y Activar los pagos.
- En el portal de una familia con saldo, pulsa Pagar ahora y usa la tarjeta de prueba
4242 4242 4242 4242(cualquier fecha futura y CVC). - El cobro aparece en Cuotas → Cobros en línea y el pago en la cuenta de la familia.
PayPal usa Client ID, Secret y Webhook ID. Las claves reales se activan cuando la comunidad lo decide junto con nosotros.
Cómo funciona un cobro
La familia pulsa Pagar (un cargo o todo lo pendiente) o Donar → la plataforma crea un cobro pendiente y la lleva a la página del proveedor → el proveedor avisa con un webhook firmado → la plataforma comprueba la firma, la hora (5 minutos), que no se haya procesado ya, que importe, moneda y modo coincidan, y solo entonces anota el pago, una sola vez.
Pagos parciales y reembolsos
- Pagos parciales en línea: opción en Pagos → Reglas de cobro, desactivada por defecto. El personal siempre puede registrar un pago parcial recibido por otra vía.
- Reembolsos: el aviso marca el cobro como reembolsado y avisa al personal. Los libros no se tocan solos: en Cuotas → Cobros en línea usa «Ajustar en los libros» para retirar el pago o la donación (queda en la auditoría).
12. Contabilidad
Principio: KesherCloud es el libro auxiliar de las familias (quién debe, quién pagó, quién donó). Tu programa contable (QuickBooks, Xero, Wave…) recibe un diario resumido. No hay sincronización en los dos sentidos: el programa contable nunca modifica familias, cargos ni pagos.
Comunidad → Tesorería → Contabilidad (permiso contabilidad.gestionar).
Moneda de la comunidad
En Contabilidad → Moneda eliges la moneda en la que tu comunidad gestiona cuotas, cargos, pagos, donaciones, precios y contabilidad: dólar, euro, libra, dólar canadiense o australiano, peso mexicano, argentino, chileno, colombiano o uruguayo, real, sol, guaraní, colón, quetzal, séquel israelí, franco suizo y otras. Todos los importes se muestran y se exportan en ella, también el CSV, la API y el webhook de contabilidad.
- Elígela antes de empezar. Cuando ya hay cargos, pagos o donaciones, no se puede cambiar (los importes guardados pasarían a significar otra cosa). Si necesitas cambiarla, escríbenos desde Soporte y lo hacemos contigo.
- Monedas sin decimales (peso chileno, guaraní): se guardan pesos enteros;
12.500se lee como doce mil quinientos. - Pagos en línea: Stripe cobra en todas estas monedas (si tu cuenta de Stripe las tiene activadas); PayPal solo en dólar, euro, libra, dólar canadiense y australiano, peso mexicano, real, séquel y franco suizo. La plataforma no deja activar una pasarela que no cobre en la moneda de tu comunidad.
Plan de cuentas
Escribe, tal como figura en tu programa contable, la cuenta (y una clase opcional) de:
- cada concepto de ingreso por cargos: cuotas de membresía, matrícula, asientos, parcelas y otros. Puedes añadir los tuyos («Alquiler del salón», «Kidush», «Mikvé»), renombrarlos y quitar los que no uses;
- cada campaña de donaciones;
- cada método de pago (cuenta de depósito): transferencia, cheque, efectivo, tarjeta, otro, y los tuyos («Zelle», «Venmo»…);
- cuentas por cobrar y gastos por comisiones.
Diario por periodo
Vista previa con totales y descarga en CSV. Cada movimiento es un asiento de dos líneas:
| Movimiento | Debe | Haber |
|---|---|---|
| Cargo a una familia | Cuentas por cobrar | Ingresos de su categoría |
| Anulación de un cargo | Ingresos de su categoría | Cuentas por cobrar |
| Pago de cuota | Cuenta de depósito (método) | Cuentas por cobrar |
| Donación | Cuenta de depósito (método) | Ingresos de su campaña |
| Comisión de una pasarela | Gastos por comisiones | Cuenta de depósito «tarjeta» |
Columnas del CSV: Date, Entry, Type, Name, Memo, Account, Class, Debit, Credit. Entry (charge-12, payment-5, donation-7, fee-3, charge-void-12) es el identificador estable del movimiento: no cambia nunca y sirve para no importarlo dos veces. Lo que no tenga cuenta asignada sale como UNMAPPED y la vista previa avisa de qué falta.
Límites conocidos: las fechas son UTC; un reembolso se corrige en la plataforma pero no sale como asiento aparte; no se concilian los depósitos agrupados del proveedor con el banco.
13. Portal de las familias
Cada familia entra con su cuenta (rol Miembro (portal)). El personal da o quita el acceso desde la ficha de la familia (contraseña provisional, que se muestra una vez). A estas cuentas no se les obliga a activar el segundo factor, aunque pueden hacerlo.
La familia ve y cambia solo lo suyo:
- Su ficha y su contacto.
- Yortzait: añadir y quitar los suyos.
- Eventos: inscribirse, ver el estado y cancelar.
- Mi cuenta: cargos, pagos y donaciones; pagar en línea y descargar el recibo de cada concepto pagado y su estado de donaciones.
- Reservar espacios (si su rol puede pedir alguno).
- Sus parcelas y los entierros de sus familiares (si hay cementerio).
14. Escuela religiosa y cementerio
Escuela
Comunidad → Escuela (permisos escuela.ver y escuela.editar). Clases por curso (nivel, maestro, horario, matrícula), alumnos tomados de las personas de las familias activas, asistencia por día (presente, ausente, justificado), informes por periodo con nota y comentario, cobro de matrículas a la cuenta de cada familia, y aviso de los próximos Bar/Bat Mitzvá (13 años hebreos desde la fecha de nacimiento). El docente pasa lista y escribe informes pero no ve nada más.
Cementerio
Comunidad → Cementerio (permisos cementerio.ver y cementerio.editar). Cementerios con secciones de parcelas (cuadrícula de colores: libre, reservada, ocupada), reserva a una familia con precio, entierros con fecha de fallecimiento y fecha hebrea (que pueden crear a la vez el yortzait), y cobro de parcelas a la cuenta sin cobrar dos veces. La familia ve en su portal sus parcelas y los entierros de sus familiares.
15. Seguridad, privacidad y auditoría
- Segundo factor obligatorio para el personal; contraseñas protegidas con Argon2id; bloqueo tras intentos fallidos.
- Todo viaja cifrado (HTTPS). Las claves de correo, de pagos y de segundo factor se guardan cifradas.
- Roles de mínimo privilegio y comprobación de permisos en el servidor.
- Auditoría (Administración → Auditoría): cada cambio importante queda anotado en una cadena a prueba de alteraciones y la plataforma comprueba su integridad.
- Accesos de nuestro equipo. Solo entramos en los datos de tu comunidad para el soporte que nos pides o por necesidad de seguridad o mantenimiento, y cada acceso queda registrado con su motivo en Administración → Auditoría → Accesos del equipo de KesherCloud. Si ves uno que no reconoces, escribe a security@keshercloud.com.
- Tus datos son tuyos. No los vendemos, no los usamos para publicidad ni para entrenar modelos de IA. Lee los Términos, la Política de privacidad y el Acuerdo de tratamiento de datos.
- Menores: los datos de menores los introduce la comunidad, que es responsable de contar con la autorización de padres o tutores.
16. Copias de seguridad, exportación y baja
- Copias diarias cifradas, con una segunda copia en otro lugar fuera del servidor. Restauración probada. Administración → Sistema muestra el estado de la última copia y de la copia externa, y la pantalla de inicio avisa si no están al día.
- Exportar todos mis datos: Administración → Sistema → «Exportar todos mis datos» (permiso exclusivo del administrador). Descarga un ZIP con un archivo CSV por tabla (familias, personas, cuotas, pagos, donaciones, contabilidad, eventos, escuela, reservas, cementerio, usuarios y auditoría), un
manifiesto.jsony unLEEME.txt. No incluye contraseñas, claves ni secretos. Cada descarga queda en la auditoría. El archivo contiene datos personales: guárdalo en un lugar seguro. - Baja: al terminar el contrato tienes 30 días para exportar tus datos. Después los borramos de los sistemas activos y, en 60 días más, de las copias de seguridad.
17. API y webhooks
La plataforma ofrece hoy estas interfaces para conectarla con otros programas:
| Interfaz | Para qué | Dirección |
|---|---|---|
| API de contabilidad (solo lectura) | Leer el diario contable en JSON | GET https://TU-INSTALACION/api/v1/accounting/… |
| Webhook saliente de contabilidad | Que KesherCloud te avise de cada asiento nuevo | Una dirección tuya, https://… |
| Webhooks de pagos (entrantes) | Que Stripe y PayPal avisen a KesherCloud | POST https://TU-INSTALACION/payments/webhook/{proveedor} |
TU-INSTALACION es la dirección de tu KesherCloud. La API y el webhook de contabilidad están en Comunidad → Tesorería → Contabilidad → Conexiones (permiso contabilidad.gestionar); según el plan de tu comunidad pueden o no estar incluidos.
Próximamente: una API pública y widgets incrustables para mostrar eventos, horarios y la fecha hebrea en la web de la comunidad. Todavía no está disponible; este documento solo describe lo que funciona hoy.
17.1 API de contabilidad
Claves. En Conexiones crea una clave (sk_…). Se muestra una sola vez, se guarda solo su huella y se puede revocar. Solo da lectura del diario (accounting:read). Una sesión de la plataforma no autoriza la API.
Autenticación. Envía la clave en la cabecera Authorization: Bearer sk_….
Límites. 120 peticiones por minuto por clave; los intentos con claves no válidas se frenan por dirección. Las respuestas no se guardan en caché (Cache-Control: no-store).
Comprobar la clave
curl -s https://TU-INSTALACION/api/v1/accounting/ping \
-H "Authorization: Bearer sk_TU_CLAVE"
{"ok": true, "version": "v1", "key": "QuickBooks", "scope": "accounting:read"}
Leer el diario
GET /api/v1/accounting/journal?from=AAAA-MM-DD&to=AAAA-MM-DD
| Parámetro | Obligatorio | Descripción |
|---|---|---|
from, to | Sí | Rango de fechas AAAA-MM-DD (from ≤ to) |
limit | No | De 1 a 2000. Por defecto 500 |
cursor | No | El next_cursor de la respuesta anterior (opaco) |
curl -s "https://TU-INSTALACION/api/v1/accounting/journal?from=2027-01-01&to=2027-01-31&limit=500" \
-H "Authorization: Bearer sk_TU_CLAVE"
{
"from": "2027-01-01",
"to": "2027-01-31",
"currency": "USD",
"entries": [
{
"entry": "payment-5",
"date": "2027-01-12",
"type": "payment",
"name": "Alfa",
"memo": "cheque",
"currency": "USD",
"complete": true,
"lines": [
{"account": "1010 Checking", "class": "", "debit_cents": 20000, "credit_cents": 0},
{"account": "1200 AR", "class": "", "debit_cents": 0, "credit_cents": 20000}
]
}
],
"next_cursor": null,
"unmapped": []
}
entryes el identificador estable: úsalo para no importar dos veces el mismo asiento.complete: falsesignifica que alguna línea tiene una cuenta sin asignar en el plan de cuentas.- Los importes (
debit_cents,credit_cents) van en la unidad menor de la moneda de tu comunidad: centavos para el dólar o el euro (20000= 200,00) y pesos enteros para el peso chileno o el guaraní (12500= 12.500 pesos). El campocurrencyde la respuesta y de cada asiento (código ISO, p. ej.USD,EUR,CLP) dice cuál es: no asumas dólares. - Los asientos vienen ordenados por fecha y
entry. Sinext_cursorno esnull, repite la petición concursor=para seguir. unmappedlista las cuentas que faltan por asignar.
Ejemplo en Python que recorre todas las páginas:
import requests
BASE = "https://TU-INSTALACION"
KEY = "sk_TU_CLAVE"
def asientos(desde, hasta):
cursor = None
while True:
params = {"from": desde, "to": hasta, "limit": 500}
if cursor:
params["cursor"] = cursor
r = requests.get(f"{BASE}/api/v1/accounting/journal", params=params,
headers={"Authorization": f"Bearer {KEY}"}, timeout=30)
r.raise_for_status()
datos = r.json()
yield from datos["entries"]
cursor = datos["next_cursor"]
if not cursor:
break
for a in asientos("2027-01-01", "2027-01-31"):
print(a["entry"], a["date"], a["complete"])
Errores
Todas las respuestas de error tienen la misma forma:
{"error": {"code": "unauthorized", "message": "Missing or invalid API key"}}
| HTTP | code | Causa |
|---|---|---|
| 400 | invalid_request | Faltan from/to, fechas no válidas, limit fuera de rango o cursor no válido |
| 401 | unauthorized | Clave ausente, incorrecta, revocada o con otro alcance |
| 429 | rate_limited | Demasiadas peticiones; espera lo que diga la cabecera Retry-After |
17.2 Webhook saliente de contabilidad
En lugar de consultar la API, puedes pedir que KesherCloud te avise de cada asiento.
Configuración (Conexiones):
- Escribe la dirección de tu receptor (
https://…; no se admitehttp://ni direcciones privadas o locales). - Guarda. Se muestra una sola vez el secreto de firma (
whsec_…): guárdalo; se almacena cifrado. - Elige desde qué fecha enviar («Enviar desde») y actívalo. Usa «Enviar aviso de prueba» para comprobar la conexión.
Qué se envía. Cada asiento una sola vez, en cuanto aparece en el diario y solo si está completo (todas sus cuentas asignadas), desde la fecha de activación. Un asiento ya enviado no se reenvía si después cambia: para eso están el CSV o la API.
Petición. POST con Content-Type: application/json, las cabeceras X-Event-Type (journal.entry o ping), User-Agent: KesherCloud-Webhook/1 y X-Signature (ver más abajo), y el cuerpo:
{
"id": "evt_payment-5",
"type": "journal.entry",
"created": 1799000000,
"data": {
"entry": "payment-5",
"date": "2027-01-12",
"type": "payment",
"name": "Alfa",
"memo": "cheque",
"currency": "USD",
"complete": true,
"lines": [
{"account": "1010 Checking", "class": "", "debit_cents": 20000, "credit_cents": 0},
{"account": "1200 AR", "class": "", "debit_cents": 0, "credit_cents": 20000}
]
}
}
idno cambia nunca para un mismo asiento: úsalo para no procesar dos veces (los reintentos lo repiten).typeesjournal.entry, opingen el aviso de prueba (condatavacío). La moneda va endata.currency.createdes la hora de envío en segundos Unix.
Firma. Cada petición lleva la cabecera X-Signature: t=<hora>,v1=<hex>, donde v1 = HMAC-SHA256(secreto, "<hora>.<cuerpo>"). Verifica siempre la firma con el cuerpo tal cual lo recibes (bytes sin reformatear) y rechaza las horas con más de 5 minutos de diferencia.
import hmac, hashlib, time
def firma_valida(secreto: str, cabecera: str, cuerpo: bytes) -> bool:
p = dict(x.split("=", 1) for x in cabecera.split(","))
if abs(time.time() - int(p["t"])) > 300:
return False
esperado = hmac.new(secreto.encode(), p["t"].encode() + b"." + cuerpo,
hashlib.sha256).hexdigest()
return hmac.compare_digest(esperado, p["v1"])
// Node.js (Express): usa express.raw({type: "application/json"}) para conservar el cuerpo original
const crypto = require("crypto");
function firmaValida(secreto, cabecera, cuerpo /* Buffer */) {
const p = Object.fromEntries(cabecera.split(",").map(x => x.split("=", 2)));
if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
const esperado = crypto.createHmac("sha256", secreto)
.update(`${p.t}.`).update(cuerpo).digest("hex");
const a = Buffer.from(esperado), b = Buffer.from(p.v1 || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Respuesta y reintentos. Responde con cualquier 2xx en menos de 10 segundos y procesa en segundo plano. No se siguen redirecciones. Si fallas, se reintenta con espera creciente: 1 min, 5 min, 30 min, 2 h, 12 h, 24 h y 24 h (8 intentos en total). Un asiento que agota los intentos queda como fallido; quitar y volver a crear el webhook reinicia las entregas. La pantalla muestra los contadores (enviados, pendientes, fallidos) y las últimas entregas con su último error.
Buenas prácticas: guarda el id de cada evento procesado; responde rápido; verifica la firma antes de hacer nada; no confíes en el orden de llegada; y no expongas el secreto.
Los webhooks entregan eventos nuevos. No hay emisión retroactiva: para el histórico usa la API con un rango de fechas o el CSV.
17.3 Webhooks de pagos (Stripe y PayPal)
Son avisos que el proveedor envía a KesherCloud, no al revés. Los configuras en el panel del proveedor con la dirección que te muestra Administración → Pagos: POST https://TU-INSTALACION/payments/webhook/stripe (o /paypal). Detalle de eventos y pasos en la sección 11. KesherCloud comprueba la firma HMAC-SHA256 (tolerancia de 5 minutos; admite varios secretos para rotarlos), procesa cada aviso una sola vez y rechaza avisos con otro importe, moneda o modo. Donorbox no usa webhooks: la plataforma consulta su API cada pocos minutos.
18. Apariencia, marca e idioma
- Apariencia (Administración → Apariencia): estilos listos de un clic (Clásico, Cálido, Moderno, Elegante, Fresco), paleta o color propio con comprobación de contraste (mínimo 4,5:1), tamaño y tipo de letra, esquinas y modo claro u oscuro por defecto (cada persona puede cambiarlo).
- Marca propia: sube el logotipo de la comunidad; aparece en la plataforma, los recibos y el estado de donaciones.
- Idioma: español e inglés en todo. Los avisos de duelo pueden salir además en hebreo.
19. Módulos y planes
Todas las instalaciones ejecutan el mismo programa; tu plan decide qué funciones están activadas. Subir de plan es activar funciones, sin reinstalar ni mover datos. En Administración → Módulos ves lo que incluye tu plan y puedes apagar lo que no vayas a usar: desaparece de los menús pero no se borra ningún dato, y puedes volver a activarlo.
20. Soporte técnico
- Pestaña Soporte de la plataforma: abre un ticket (permiso
soporte.usar) y seguimos la conversación ahí. Cada ticket tiene una referencia única del estiloKC-00012; cítala si nos escribes por correo. - Correo: contact@keshercloud.com. Para asuntos de privacidad, privacy@keshercloud.com; para vulnerabilidades o accesos que no reconoces, security@keshercloud.com.
- Estado de tu servidor: tu instalación nos envía cada pocos minutos un informe técnico (versión, disco, copias, errores) sin ningún dato de tu comunidad. Si algo falla, lo vemos y abrimos un ticket.
Al escribirnos, ayuda mucho: qué intentabas hacer, qué pasó, la pantalla (captura) y la hora aproximada. Nunca nos envíes contraseñas, claves de pago ni códigos de verificación; no los pedimos por correo.
21. Preguntas frecuentes
¿Dónde están mis datos? En tu instalación independiente, en servidores contratados por nosotros. Las copias van cifradas a un segundo lugar.
¿Puedo llevarme mis datos? Sí, en cualquier momento: Administración → Sistema → Exportar todos mis datos.
¿Se guardan los datos de tarjeta? No. Se paga en la página de Stripe, PayPal o Donorbox con la cuenta de tu comunidad.
¿Puede entrar vuestro equipo en mis datos? Solo para el soporte que pides o por seguridad, y cada acceso queda registrado y visible para ti.
Un correo no llega o va a spam. Revisa SPF, DKIM y DMARC del dominio (sección 6) y usa «Enviar prueba».
Un pago en línea no aparece. Mira Cuotas → Cobros en línea: si el cobro está pendiente, el proveedor aún no ha confirmado; si falla, comprueba que el webhook de Stripe tenga los cinco eventos y el secreto correcto.
Mi receptor del webhook recibe la misma petición varias veces. Es normal si no respondiste 2xx a tiempo: son reintentos. Usa el id del evento para ignorar los repetidos.
La API responde 401. Revisa que uses Authorization: Bearer sk_…, que la clave no esté revocada y que sea una clave de contabilidad.
Quiero cambiar de plan o dar de baja la comunidad. Escríbenos desde Soporte.
22. Glosario
| Término | Significado |
|---|---|
| Yortzait | Aniversario del fallecimiento según el calendario hebreo |
| Hodaa / Hodaot de avelut | Aviso(s) de duelo |
| Mikvé | Baño ritual |
| Kibudim / aliyot | Honores en la lectura de la Torá |
| Gabay / gabbai | Quien organiza los honores y el culto |
| Kohen, levi, israel | Las tres categorías tradicionales para los honores |
| Altas Fiestas | Rosh Hashaná y Yom Kipur |
| Bar/Bat Mitzvá | Mayoría de edad religiosa (13 años hebreos) |
| Shalaj Manot, Maot Jitim | Campañas de Purim y de Pésaj |
| Asiento (de diario) | Un movimiento contable con líneas de debe y haber |
| Webhook | Aviso automático que un programa envía a otro cuando ocurre algo |