Notificaciones

Estos endpoints requieren una API key de Summit Notify. Crear una notificación la guarda en una cola; la entrega ocurre de forma asíncrona.

Endpoints

Método	Ruta	Éxito
POST	/api/v1/notifications	202 Accepted
GET	/api/v1/notifications/{id}	200 OK

Crear una notificación

POST /api/v1/notifications
Content-Type: application/json
Authorization: Bearer SUMMIT_NOTIFY_API_KEY

Campos del request

Campo	Tipo	Requerido	Descripción
channel	string	No	email por defecto; también admite whatsapp.
recipient	string	Sí	Correo para email o teléfono E.164 para WhatsApp.
cc	string[]	No	Copias visibles. Valores vacíos se eliminan.
bcc	string[]	No	Copias ocultas/CCO. Valores vacíos se eliminan.
from_name	string	No	Reemplaza el nombre de la cuenta para este envío. Se recortan espacios.
subject	string	Condicional	Obligatorio sin template_id.
body	string	Condicional	Obligatorio sin template_id.
body_type	string	No	text por defecto o html. Con plantilla, hereda su valor si se omite.
template_id	UUID string	No	Plantilla del mismo propietario. Tiene prioridad sobre subject y body.
variables	object string→string	No	Datos utilizados al renderizar la plantilla.
smtp_account_id	UUID string	No	Cuenta concreta; si se omite usa la predeterminada.
whatsapp_account_id	UUID string	No	Cuenta WhatsApp concreta; si se omite usa la predeterminada.
whatsapp	object	Para WhatsApp	Payload template, text, image, video, audio, document, location o reaction.

Reglas de destinatarios

• recipient siempre es obligatorio para email.
• Se admiten como máximo 50 direcciones sumando To, CC y BCC.
• Los duplicados se comparan sin distinguir mayúsculas/minúsculas.
• La primera aparición gana: recipient, después cc y finalmente bcc.
• Todas las direcciones deben cumplir trusted_domains de la cuenta.
• Si api_allowed_domains no está vacío, el host de Origin o Referer debe coincidir. La ausencia de ambos headers se rechaza.

Remitente efectivo

El nombre se resuelve en este orden:

1. from_name de la notificación;
2. from_name de la cuenta;
3. label de la cuenta.

La dirección remitente siempre proviene de from_address de la cuenta.

Los campos cc, bcc, from_name, subject, body, body_type y smtp_account_id pertenecen al canal email. Para WhatsApp utiliza whatsapp_account_id y whatsapp.

Ejemplo

curl -X POST https://notify.summitexplorerjd.ec/api/v1/notifications \
  -H "Authorization: Bearer $SUMMIT_NOTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.example.com" \
  -d '{
    "recipient": "destinatario@example.com",
    "cc": ["supervisor@example.com"],
    "bcc": ["auditoria@example.com"],
    "from_name": "Mi aplicación",
    "subject": "Bienvenido",
    "body": "Gracias por registrarte.",
    "body_type": "text",
    "smtp_account_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'

Respuesta 202

{
  "id": "8f2c1a10-4b3e-4a7a-9c3d-1e2f3a4b5c6d",
  "channel": "email",
  "status": "pending",
  "attempts": 0,
  "max_attempts": 5,
  "created_at": "2026-08-03T14:00:00Z",
  "updated_at": "2026-08-03T14:00:00Z"
}

La respuesta no devuelve destinatarios, contenido ni smtp_account_id.

Ejemplo WhatsApp con plantilla

{
  "channel": "whatsapp",
  "recipient": "+593999999999",
  "whatsapp_account_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "whatsapp": {
    "type": "template",
    "template_id": "c7a4e210-9d2b-4f6a-8e1c-3b5d7f9a0c2e",
    "values": {
      "parameter_1": "Ana"
    }
  }
}

Consulta Enviar notificaciones por WhatsApp para plantillas, mensajes libres, multimedia, ventana de servicio y fallback.

Errores de creación

Estado	Situación
400	JSON inválido, campo desconocido o body superior a 1 MiB.
400	Canal, body_type, dirección o UUID inválido.
400	Falta recipient, subject, body, cuenta predeterminada o plantilla.
400	Más de 50 destinatarios o dominio no confiable.
403	El caller no cumple api_allowed_domains.
409	La conversación WhatsApp pertenece a otro tenant o la ventana está cerrada sin fallback.
500	No se pudo persistir la notificación.

Crear desde una plantilla

{
  "recipient": "ana@example.com",
  "template_id": "c7a4e210-9d2b-4f6a-8e1c-3b5d7f9a0c2e",
  "variables": {
    "Nombre": "Ana"
  }
}

Si faltan variables, Go templates renderiza <no value>. Si template_id está presente, subject y body enviados directamente se ignoran.

Consultar una notificación

GET /api/v1/notifications/{id}
Authorization: Bearer SUMMIT_NOTIFY_API_KEY

La respuesta usa el mismo esquema de estado mostrado arriba. last_error aparece únicamente cuando no está vacío:

{
  "id": "8f2c1a10-4b3e-4a7a-9c3d-1e2f3a4b5c6d",
  "channel": "email",
  "status": "failed",
  "attempts": 5,
  "max_attempts": 5,
  "last_error": "mailer: send message: connection refused",
  "created_at": "2026-08-03T14:00:00Z",
  "updated_at": "2026-08-03T14:02:00Z"
}

Estado	Significado
pending	Espera un primer intento o reintento.
processing	Fue reclamada por un worker.
submitted	AWS aceptó inicialmente el mensaje WhatsApp y se esperan eventos del proveedor.
sent	El proveedor aceptó o marcó el mensaje como enviado.
failed	Se agotaron los intentos.

Los eventos WhatsApp delivered y read registran internamente sus fechas, pero mantienen status: "sent". La respuesta pública actual no expone delivered_at ni read_at.

Un UUID inválido devuelve 400; una notificación inexistente o ajena devuelve 404.