Saltar al contenido principal

Notificaciones

La API de Notificaciones gestiona las plantillas de comunicación, envía mensajes (correo electrónico, SMS y notificaciones push) a los clientes a través de diversos proveedores externos, y mantiene un registro histórico del estado de cada envío con posibilidad de reintento en caso de fallo.

Plantillas (Templates)​

Las plantillas definen el diseño y cuerpo del mensaje, permitiendo interpolación de variables.

Crear plantilla​

POST /api/v1/notifications/templates

Payload de entrada:

{
  "name": "welcome_email",
  "channel": "email",
  "subject": "¡Bienvenido a {{store_name}}!",
  "body": "Hola {{customer_name}}, gracias por registrarte en nuestra tienda."
}

Valores válidos:

  • channel: Puede ser email, sms o push.
  • subject: Opcional para canales que no lo requieran (ej. SMS).

Respuesta 201 Created:

{
  "data": {
    "id": "e5b8d2b2-c0ff-4e78-8540-02d2bf941fca",
    "tenant_id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "welcome_email",
    "channel": "email",
    "subject": "¡Bienvenido a {{store_name}}!",
    "body": "Hola {{customer_name}}, gracias por registrarte en nuestra tienda.",
    "is_active": true,
    "created_at": "2026-06-02T20:45:00Z",
    "updated_at": "2026-06-02T20:45:00Z"
  }
}

Listar plantillas​

GET /api/v1/notifications/templates

Retorna un listado de todas las plantillas del tenant actual.

Obtener plantilla​

GET /api/v1/notifications/templates/:id

Actualizar plantilla​

PUT /api/v1/notifications/templates/:id

Payload de entrada:

{
  "subject": "¡Bienvenido a nuestra gran tienda {{store_name}}!",
  "body": "Hola {{customer_name}}, estamos encantados de que te unas a nosotros."
}

Desactivar plantilla​

POST /api/v1/notifications/templates/:id/deactivate

Desactiva una plantilla para evitar que se use en futuros envíos.

Respuesta 200 OK

Envío de Notificaciones​

Enviar notificación basada en plantilla​

Interpolará las variables proporcionadas en la plantilla y enviará el mensaje utilizando el proveedor configurado para el canal (ej. SendGrid para Email, Twilio para SMS o FCM para Push).

POST /api/v1/notifications/send

Payload de entrada:

{
  "template_name": "welcome_email",
  "channel": "email",
  "recipient": "cliente@example.com",
  "data": {
    "store_name": "Mi Tienda OmniBuy",
    "customer_name": "Juan Pérez"
  },
  "metadata": {
    "source": "onboarding_flow"
  }
}

Respuesta 201 Created:

{
  "data": {
    "id": "e9c12345-f046-40d3-852f-423089c73ba3",
    "tenant_id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "template_id": "e5b8d2b2-c0ff-4e78-8540-02d2bf941fca",
    "channel": "email",
    "recipient": "cliente@example.com",
    "subject": "¡Bienvenido a Mi Tienda OmniBuy!",
    "body": "Hola Juan Pérez, gracias por registrarte en nuestra tienda.",
    "status": "sent",
    "provider": "sendgrid",
    "provider_message_id": "SG.xxxxxx",
    "metadata": {
      "source": "onboarding_flow"
    },
    "sent_at": "2026-06-02T20:45:02Z",
    "created_at": "2026-06-02T20:45:02Z",
    "updated_at": "2026-06-02T20:45:02Z"
  }
}

Enviar notificación directa (Sin plantilla)​

Envía un mensaje personalizado indicando directamente el asunto, cuerpo y el proveedor deseado.

POST /api/v1/notifications/send/direct

Payload de entrada:

{
  "channel": "email",
  "recipient": "soporte@example.com",
  "subject": "Alerta de Sistema",
  "body": "El espacio en disco está al 90%.",
  "provider": "sendgrid",
  "metadata": {
    "urgency": "high"
  }
}

Valores válidos para provider:

  • sendgrid (para Email)
  • twilio (para SMS)
  • firebase_fcm (para Push)

Registro de Envíos e Historial​

Listar notificaciones enviadas​

GET /api/v1/notifications

Permite auditar el estado de los envíos realizados en la plataforma.

Obtener detalles de una notificación​

GET /api/v1/notifications/:id

Muestra el detalle del estado de entrega (pending, sent, failed). Si el estado es failed, incluirá el campo error_message devuelto por el proveedor.

Reintentar notificación fallida​

POST /api/v1/notifications/:id/retry

Intenta volver a enviar una notificación que previamente falló.

Respuesta 200 OK: Retorna la notificación actualizada con su nuevo estado de envío.