Referencia de la API

Generada desde el contrato OpenAPI v1.0.0, la fuente de verdad de la API.

URL base: https://api.notify.com.mx/v1

Autenticación

Envía tu API key como token Bearer en el header Authorization. Tu cuenta se identifica por la key.

Authorization: Bearer $NOTIFY_API_KEY

Envío y consulta de mensajes

GET`/messages`

Listar mensajes

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`status`	query	`MessageStatus`	No
`channel`	query	`Channel`	No
`recipient`	query	`string`	No	Dirección del destinatario
`from`	query	`string (date-time)`	No
`to`	query	`string (date-time)`	No
`cursor`	query	`string`	No	Paginación por cursor
`limit`	query	`integer`	No

Respuestas

Código	Descripción	Tipo
`200`	Listado paginado	`MessageList`
`401`	API key ausente, inválida o revocada	`Error`

POST`/messages`

Enviar un mensaje

Acepta una petición de envío, la valida y la encola.

Si idempotency_key ya fue usada, devuelve el mensaje original sin generar un envío nuevo.
Si el destinatario tiene opt-out para ese canal, el mensaje queda en estado blocked.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`Idempotency-Key`	header	`string`	No	Evita envíos duplicados ante reintentos del cliente.

Cuerpo de la petición

SubmitMessageRequest

Respuestas

Código	Descripción	Tipo
`202`	Petición aceptada y encolada	`Message`
`400`	Petición malformada	`Error`
`401`	API key ausente, inválida o revocada	`Error`
`403`	Tenant suspendido	`Error`
`422`	Validación fallida (plantilla inexistente, variable obligatoria ausente)	`Error`
`429`	Límite de peticiones del tenant superado	`Error`

GET`/messages/{id}`

Consultar el estado de un mensaje

Devuelve el estado del mensaje y su historial completo de intentos de entrega.

Un mensaje perteneciente a otro tenant devuelve 404, nunca 403: un 403 confirmaría que ese identificador existe.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	`string (uuid)`	Sí

Respuestas

Código	Descripción	Tipo
`200`	Mensaje encontrado	`MessageDetail`
`401`	API key ausente, inválida o revocada	`Error`
`404`	Recurso inexistente o perteneciente a otro tenant	`Error`

GET`/health`

Health checkSin autenticación

Respuestas

Código	Descripción	Tipo
`200`	Servicio operativo	—

Plantillas multiidioma

GET`/templates`

Listar plantillas

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`channel`	query	`Channel`	No

Respuestas

Código	Descripción	Tipo
`200`	Listado de plantillas	`Template[]`

POST`/templates`

Crear una plantilla

Cuerpo de la petición

CreateTemplateRequest

Respuestas

Código	Descripción	Tipo
`201`	Plantilla creada	`Template`
`409`	Ya existe una plantilla con esa `key` en el tenant	—
`422`	Validación fallida (plantilla inexistente, variable obligatoria ausente)	`Error`

POST`/templates/{key}/versions`

Añadir una versión por idioma

Añade la variante de la plantilla para un locale.

Editar una versión activa genera una versión nueva; la anterior no se modifica, para que la auditoría pueda recuperar el texto exacto que se envió en el pasado.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`key`	path	`string`	Sí

Cuerpo de la petición

CreateTemplateVersionRequest

Respuestas

Código	Descripción	Tipo
`201`	Versión creada	`TemplateVersion`
`404`	Recurso inexistente o perteneciente a otro tenant	`Error`
`422`	Validación fallida (plantilla inexistente, variable obligatoria ausente)	`Error`

Esquemas

`Channel`

Canal de entrega. push se añadirá en v2.

Valores: email, sms, whatsapp

`MessageStatus`

accepted: aceptado y encolado
processing: un worker lo está procesando
sent: el proveedor lo aceptó
delivered: confirmada la entrega al destinatario
failed: agotó los reintentos
blocked: no se envió por opt-out registrado

sent y delivered son distintos a propósito: que un proveedor acepte un mensaje no prueba que haya llegado.

Valores: accepted, processing, sent, delivered, failed, blocked

`ErrorCategory`

Taxonomía normalizada. Nunca se expone el código crudo del proveedor.

Valores: transient_provider_error, rate_limited, invalid_recipient, blocked_by_provider, template_not_approved, authentication_error

`Recipient`

Nombre	Tipo	Obligatorio	Descripción
`address`	`string`	Sí	Correo electrónico, o teléfono que será normalizado a E.164.
`locale`	`string`	No	Idioma del destinatario. Si se omite o no existe versión para él, se aplica la cascada: locale → default_locale del tenant → es.
`external_id`	`string`	No	Identificador del destinatario en el sistema del cliente.

`SubmitMessageRequest`

Nombre	Tipo	Obligatorio	Descripción
`channel`	`Channel`	Sí
`recipient`	`Recipient`	Sí
`template_key`	`string`	Sí	Clave estable de la plantilla.
`variables`	`object`	No	Variables del render. Se validan contra el `variables_schema` de la plantilla.
`idempotency_key`	`string`	No	Alternativa al header `Idempotency-Key`.

`Message`

Nombre	Tipo	Obligatorio	Descripción
`id`	`string (uuid)`	No
`status`	`MessageStatus`	No
`channel`	`Channel`	No
`recipient`	`Recipient`	No
`template_key`	`string`	No
`resolved_locale`	`string`	No	Idioma finalmente usado tras aplicar la cascada.
`created_at`	`string (date-time)`	No

`DeliveryAttempt`

Nombre	Tipo	Obligatorio	Descripción
`attempt_number`	`integer`	No
`provider`	`string`	No
`status`	`sent` \| `failed`	No
`error_category`	`ErrorCategory`	No
`error_detail`	`string`	No	Explicación legible. No es el mensaje crudo del proveedor.
`attempted_at`	`string (date-time)`	No

`MessageDetail`

Nombre	Tipo	Obligatorio	Descripción
`id`	`string (uuid)`	No
`status`	`MessageStatus`	No
`channel`	`Channel`	No
`recipient`	`Recipient`	No
`template_key`	`string`	No
`resolved_locale`	`string`	No	Idioma finalmente usado tras aplicar la cascada.
`created_at`	`string (date-time)`	No
`attempts`	`DeliveryAttempt[]`	No
`delivered_at`	`string (date-time) \| null`	No

`MessageList`

Nombre	Tipo	Obligatorio	Descripción
`data`	`Message[]`	No
`next_cursor`	`string \| null`	No

`CreateTemplateRequest`

Nombre	Tipo	Obligatorio	Descripción
`key`	`string`	Sí	Única por tenant. Es lo que el cliente referencia al enviar.
`channel`	`Channel`	Sí
`name`	`string`	Sí
`variables_schema`	`object`	No	JSON Schema de las variables que espera la plantilla.

`Template`

Nombre	Tipo	Obligatorio
`id`	`string (uuid)`	No
`key`	`string`	No
`channel`	`Channel`	No
`name`	`string`	No
`variables_schema`	`object`	No
`versions`	`TemplateVersion[]`	No

`CreateTemplateVersionRequest`

Nombre	Tipo	Obligatorio	Descripción
`locale`	`string`	Sí
`subject`	`string`	No	Solo para el canal email.
`body`	`string`	Sí	Contenido con marcadores de variables.
`provider_template_id`	`string`	No	Obligatorio en WhatsApp: identificador de la plantilla aprobada por Meta. WhatsApp no admite texto libre fuera de la ventana de sesión.

`TemplateVersion`

Nombre	Tipo	Obligatorio
`id`	`string (uuid)`	No
`locale`	`string`	No
`subject`	`string \| null`	No
`body`	`string`	No
`status`	`draft` \| `active` \| `archived`	No
`version`	`integer`	No

`Error`

Nombre	Tipo	Obligatorio	Descripción
`code`	`string`	Sí	Código estable y accionable.
`message`	`string`	Sí	Explicación legible de qué hacer.
`details`	`object`	No

Referencia de la API

Autenticación

Envío y consulta de mensajes

GET/messages

Parámetros

Respuestas

POST/messages

Parámetros

Cuerpo de la petición

Respuestas

GET/messages/{id}

Parámetros

Respuestas

GET/health

Respuestas

Plantillas multiidioma

GET/templates

Parámetros

Respuestas

POST/templates

Cuerpo de la petición

Respuestas

POST/templates/{key}/versions

Parámetros

Cuerpo de la petición

Respuestas

Esquemas

Channel

MessageStatus

ErrorCategory

Recipient

SubmitMessageRequest

Message

DeliveryAttempt

MessageDetail

MessageList

CreateTemplateRequest

Template

CreateTemplateVersionRequest

TemplateVersion

Error

GET`/messages`

POST`/messages`

GET`/messages/{id}`

GET`/health`

GET`/templates`

POST`/templates`

POST`/templates/{key}/versions`

`Channel`

`MessageStatus`

`ErrorCategory`

`Recipient`

`SubmitMessageRequest`

`Message`

`DeliveryAttempt`

`MessageDetail`

`MessageList`

`CreateTemplateRequest`

`Template`

`CreateTemplateVersionRequest`

`TemplateVersion`

`Error`