Documentación de uso

Guía rápida para integrar el envío de notificaciones. La referencia completa e interactiva de la API está en Swagger ↗ (se genera automáticamente desde el código).

Cómo funciona

Hay un único punto de entrada: POST /api/v1/send. La plantilla —identificada por su token— fija el canal, el remitente, el render del asunto/cuerpo, la caducidad y los reintentos. No eliges el canal en la petición: lo determina el token.

Autenticación

Cada petición de envío se autentica con el token de la plantilla, en la cabecera Authorization: Bearer <token> (o como query ?token=<token>). El token se muestra una sola vez al crear la plantilla o al rotar su token desde la pestaña Plantillas.

Cuerpo de la petición

{
  "to":      ["destinatario1", "destinatario2"],
  "vars":    { "nombre": "Ana" },
  "subject": "(opcional)",
  "body":    "(opcional)"
}

• to: lista de destinatarios. El canal de la plantilla los interpreta: email → dirección de correo; telegram → chat_id; sms → número de móvil.
• vars: valores para el render de la plantilla (p. ej. {{.nombre}} en el cuerpo).
• subject / body: solo se aceptan si la plantilla tiene activado «Permitir override»; en caso contrario se ignoran.

Respuestas

• 1 destinatario → entrega síncrona: 200 si se envió, 202 si quedó reintentándose.
• Varios → se encola y responde 202 con batch_id y message_ids; el worker los procesa con reintentos y caducidad.

Ejemplos (curl)

Email — el destinatario es una dirección de correo:

curl -X POST http://localhost:8610/api/v1/send \
  -H "Authorization: Bearer <token-de-plantilla>" \
  -H "Content-Type: application/json" \
  -d '{"to":["dest@dominio.com"],"vars":{"nombre":"Ana"}}'

Telegram — el destinatario es un chat_id:

curl -X POST http://localhost:8610/api/v1/send \
  -H "Authorization: Bearer <token-de-plantilla>" \
  -H "Content-Type: application/json" \
  -d '{"to":["123456789"],"vars":{"nombre":"Ana"}}'

SMS — el destinatario es un número de móvil:

curl -X POST http://localhost:8610/api/v1/send \
  -H "Authorization: Bearer <token-de-plantilla>" \
  -H "Content-Type: application/json" \
  -d '{"to":["+34600111222"],"vars":{"codigo":"482913"}}'

El token también puede ir como query (útil para pruebas):

curl -X POST "http://localhost:8610/api/v1/send?token=<token-de-plantilla>" \
  -H "Content-Type: application/json" \
  -d '{"to":["dest@dominio.com"]}'

Consultar estado y actividad

Los siguientes endpoints requieren sesión de administración (la misma de este panel):

• GET /api/v1/messages/{id} — estado de un mensaje.
• GET /api/v1/batches/{id} — estado de un lote.
• GET /api/v1/templates/{id}/events — log de entregas (filtros: limit, outcome, recipient).
• GET /api/v1/templates/{id}/stats — resumen agregado.

En la pestaña Plantillas, el botón Actividad de cada plantilla muestra estos datos de forma visual.