Skip to main content

​
API de Alara

La API de Alara te permite hacer desde tu propio sistema todo lo que harías desde el Dashboard: emitir pases digitales, registrar escaneos, mover saldos de lealtad, programar notificaciones push, administrar recompensas y recibir eventos en tiempo real mediante webhooks. Es una API REST sobre HTTPS. Todas las peticiones y respuestas usan JSON.

Autenticación

Cómo firmar tus peticiones con tu API key.

Conceptos

Pases, plantillas, escaneos, recompensas y cómo se relacionan.

Referencia

Todos los endpoints con sus parámetros y respuestas.

Webhooks

Recibe eventos en tu servidor cuando algo cambia.

​
URL base

Todos los endpoints públicos viven bajo el prefijo de versión /v1.
Los ejemplos de esta documentación usan esa URL directamente, así que puedes copiarlos y pegarlos tal cual. Solo necesitas definir ALARA_API_KEY con tu API key.
La versión se indica únicamente en la ruta. No existen versiones por encabezado ni por fecha, y /v1 es la única versión pública actualmente disponible.

​
Tu primera petición

1

Guarda tu API key

Exporta tu API key como variable de entorno para no dejarla escrita en tu código. Hecho esto, los ejemplos de esta documentación funcionan copiándolos tal cual.
2

Consulta los campos de tu plantilla

Antes de emitir un pase necesitas saber qué campos acepta tu plantilla.
3

Emite un pase

Usa esos campos como llaves del objeto visible.
La respuesta incluye el download_url que puedes compartir con la persona para que instale su pase.
4

Registra un escaneo

Cuando el pase se use en un punto de venta o acceso, registra el evento.

​
Qué puedes hacer

Algunas funciones —tarjetas físicas, recompensas y webhooks— deben estar habilitadas en tu cuenta. Si recibes un error 403, escríbenos a dev@alaramx.com para activarlas.

​
Lo que debes saber antes de empezar

Cada cuenta tiene una sola API key y un solo ambiente. Si necesitas probar sin afectar tu operación, pídenos una cuenta de prueba aparte.
La API no aplica actualmente un límite de tasa (rate limit) ni devuelve respuestas 429. Aun así, te recomendamos espaciar tus cargas masivas y reintentar con retroceso exponencial ante errores 5xx.
La API no lee el encabezado Idempotency-Key. Para crear pases, el propio pass_id cumple esa función: reintentar una creación con el mismo pass_id devuelve 409 RESOURCE_CONFLICT en lugar de duplicar el pase.
Crear un pase y enviar notificaciones son procesos en segundo plano. La API te responde con el estado inicial (202 Accepted o un status intermedio) y tú consultas el recurso o escuchas un webhook para conocer el desenlace.