Notificaciones

Envía mensajes push a los pases instalados en el wallet del portador. Puedes enviarlos de inmediato a un pase concreto o programarlos hacia el futuro para una lista de pases, una audiencia guardada o toda tu base.

Las notificaciones llegan únicamente a pases instalados (status: "active"). Un pase emitido pero nunca instalado no puede recibir push.

Enviar a un pase de inmediato

POST /v1/notifications/passes/{passID}

Envía un push en el momento a un solo pase.

string

required

El pass_id del destinatario.

string

required

Texto de la notificación.

Devuelve 200 OK con cuerpo vacío.

curl -X POST "https://api.alaramx.com/v1/notifications/passes/cliente-001" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Tu café de cortesía te espera hoy." }'

Errores

HTTP	`code`	Causa
`409`	`PASS_NOT_ACTIVE`	El pase no está instalado en un wallet.
`404`	`RESOURCE_NOT_FOUND`	El pase no existe.
`400`	`INVALID_INPUT`	Falta el mensaje o viene vacío.

El objeto notificación

string

Identificador (UUID) de la notificación.

string

Texto enviado.

string

Estado actual. Consulta la tabla de estados más abajo.

string

Fecha y hora programadas, en zona America/Mexico_City.

string | null

Audiencia destinataria, si se usó una.

boolean

true si va dirigida a todos tus pases.

string | null

Momento en que se calculó la lista final de destinatarios.

string | null

Momento en que terminó el envío.

integer

Destinatarios calculados.

integer

Envíos aceptados.

integer

Envíos fallidos.

integer

Envíos cancelados.

integer

Destinatarios omitidos, por ejemplo pases que ya no estaban instalados.

Estados

`status`	Significado
`creating`	Se está registrando la notificación.
`creationFailed`	No se pudo registrar.
`validating`	Se están resolviendo los destinatarios.
`scheduled`	Lista y esperando su hora.
`sending`	En proceso de envío.
`successful`	Se envió a todos los destinatarios.
`completedWithErrors`	Terminó, pero algunos envíos fallaron.
`failed`	El envío falló por completo.
`cancelled`	Se canceló antes de enviarse.

Programar una notificación

POST /v1/notifications

string

required

Texto de la notificación.

string

required

Cuándo enviarla. Acepta RFC 3339 (2026-08-01T18:00:00Z) o los formatos locales 2026-08-01T18:00:00 y 2026-08-01T18:00, que se interpretan en zona America/Mexico_City.Debe estar al menos 2 minutos en el futuro.

array

Lista explícita de pass_id.

string

UUID de una audiencia guardada en el Dashboard.

boolean

Envía a todos los pases de tu cuenta.

Debes indicar exactamente uno de recipients, audience_id o target_all_passes. Ninguno devuelve NOTIFICATION_RECIPIENTS_OR_AUDIENCE_REQUIRED; más de uno devuelve NOTIFICATION_TARGETING_CONFLICT.

Devuelve 201 Created con la notificación.

curl -X POST "https://api.alaramx.com/v1/notifications" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Este sábado: 2x1 en toda la tienda.",
    "timestamp": "2026-08-01T10:00:00Z",
    "recipients": ["cliente-001", "cliente-002"]
  }'

curl -X POST "https://api.alaramx.com/v1/notifications" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Beneficio exclusivo para nivel Oro.",
    "timestamp": "2026-08-01T10:00:00Z",
    "audience_id": "3f2b1c0d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
  }'

curl -X POST "https://api.alaramx.com/v1/notifications" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Nuevo horario: abrimos hasta las 10 pm.",
    "timestamp": "2026-08-01T10:00:00Z",
    "target_all_passes": true
  }'

{
  "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "message": "Este sábado: 2x1 en toda la tienda.",
  "status": "scheduled",
  "scheduled_at": "2026-08-01T04:00:00-06:00",
  "target_all_passes": false,
  "completed_at": null,
  "total_recipients": 2,
  "accepted_recipients": 0,
  "failed_recipients": 0,
  "cancelled_recipients": 0,
  "skipped_recipients": 0
}

Cuando usas audience_id o target_all_passes, la lista de destinatarios se calcula en el momento del envío, no al programar. Una audiencia que crezca entre ambos instantes incluirá a los pases nuevos.

Consultar una notificación

GET /v1/notifications/{id}

string

required

UUID de la notificación. Un valor que no sea UUID devuelve 400 INVALID_INPUT.

Devuelve 200 OK con la notificación y sus contadores de envío.

curl "https://api.alaramx.com/v1/notifications/5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Listar notificaciones

GET /v1/notifications

integer

default:"100"

Máximo 100. Nota que aquí el valor por omisión es 100, no 25.

integer

default:"0"

string

Busca en el identificador y en el texto del mensaje.

string

Repetible. Cualquiera de los estados de la tabla anterior.

string

UUID de audiencia. Un valor inválido devuelve 400.

string

default:"scheduled_at"

id, scheduled_at, created_at o updated_at.

string

default:"desc"

asc o desc.

string

RFC 3339, inclusivo.

string

RFC 3339, exclusivo.

Devuelve 200 OK con un arreglo de notificaciones, más X-Total-Count y X-Has-More.

curl "https://api.alaramx.com/v1/notifications?status=scheduled&sort_dir=asc" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Cancelar una notificación programada

POST /v1/notifications/{id}/cancel

Cancela una notificación que aún no se ha enviado.

string

required

UUID de la notificación.

Devuelve 204 No Content.

curl -X POST "https://api.alaramx.com/v1/notifications/5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f/cancel" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Buenas prácticas

Sé oportuno, no insistente

Un push de más es la razón más común por la que alguien desinstala un pase.

Segmenta

Una audiencia relevante rinde más que un envío a toda la base.

Revisa los contadores

skipped_recipients alto suele indicar muchos pases desinstalados.

Cuida el horario

Recuerda que scheduled_at se interpreta en horario del centro de México.

Consulta también la guía de buenas prácticas de notificaciones del Dashboard.

Empezar

Referencia

Webhooks

Notificaciones

Notificaciones

Enviar a un pase de inmediato

Errores

El objeto notificación

Estados

Programar una notificación

Consultar una notificación

Listar notificaciones

Cancelar una notificación programada

Buenas prácticas

Sé oportuno, no insistente

Segmenta

Revisa los contadores

Cuida el horario

​Notificaciones

​Enviar a un pase de inmediato

​Errores

​El objeto notificación

​Estados

​Programar una notificación

​Consultar una notificación

​Listar notificaciones

​Cancelar una notificación programada

​Buenas prácticas

Sé oportuno, no insistente

Segmenta

Revisa los contadores

Cuida el horario

Notificaciones

Enviar a un pase de inmediato

Errores

El objeto notificación

Estados

Programar una notificación

Consultar una notificación

Listar notificaciones

Cancelar una notificación programada

Buenas prácticas