Pases

El pase es el objeto central de Alara. Estos endpoints te permiten emitirlos, mantenerlos actualizados y mover su saldo de lealtad.

El objeto pase

string

El identificador que tú definiste al crear el pase.

object

Pares llave/valor mostrados en el pase. Las llaves están limitadas a los campos de la plantilla.

object

Datos libres asociados al pase, nunca visibles para el portador.

object | null

Personalización visual de este pase en particular.

Show propiedades

string

Color de fondo en hexadecimal, por ejemplo #1a2b3c.

string

URL pública de una imagen PNG.

string

URL pública de una imagen PNG.

string

Título mostrado en el pase.

string | null

El valor codificado en el código QR del pase. Sólo aplica en pases QR. Consulta con el equipo de soporte el uso de este campo ya que generalmente se utiliza para identificar el pase.

string

Estado del pase: creating, creation_failed, issued, active, removed o deactivated. Consulta Conceptos.

string | null

Presente solo cuando status es creation_failed. Indica por qué falló la emisión.

string

Enlace que compartes con la persona para que instale el pase en su wallet.

boolean

true cuando el pase fue desinstalado y está bloqueado para volver a instalarse.

string

none, balance o stamps.

integer | null

Saldo o número de sellos actual. Ausente en pases sin lealtad.

string

Fecha de creación, RFC 3339.

string

Última modificación, RFC 3339.

string | null

Presente solo si el pase fue eliminado.

Ejemplo

{
  "id": "cliente-001",
  "visible": {
    "nombre": "Ada Lovelace",
    "puntos": "42"
  },
  "hidden": {
    "crm_id": "9f3c1a"
  },
  "qr_value": "ALARA:cliente-001",
  "status": "active",
  "download_url": "https://.../download/8f2c…",
  "reinstall_blocked": false,
  "loyalty_type": "balance",
  "balance": 42,
  "created_at": "2026-07-01T08:30:00Z",
  "updated_at": "2026-07-24T14:41:59Z"
}

Crear un pase

POST /v1/passes

Emite un pase nuevo.

Cuerpo

string

required

El identificador que usarás para este pase en toda la API. Debe ser único dentro de tu cuenta.

string

Plantilla con la que se emite. Si lo omites, se usa la primera plantilla de tu cuenta.

object

Campos mostrados en el pase. Cada llave debe existir en la lista de campos aceptados de la plantilla; los campos marcados como locked (contadores de lealtad) no se pueden escribir aquí.

object

Datos libres asociados al pase.

object

Personalización visual. Debe traer al menos una propiedad.

Show propiedades

string

Hexadecimal, por ejemplo #1a2b3c.

string

URL pública de un PNG.

string

URL pública de un PNG.

string

Título del pase.

string

Opcional. Pista sobre la plataforma del portador para preparar el pase desde el inicio. Solo acepta ios o android; cualquier otro valor devuelve 400 INVALID_REQUEST.Si lo omites, el pase queda listo para ambas plataformas. Es un dato de apoyo al momento de emitir: no se guarda ni se devuelve en la respuesta.

Respuesta

La emisión es asíncrona. Alara espera hasta 10 segundos a que el pase quede emitido:

201 Created — el pase alcanzó el estado issued. La respuesta trae el pase completo.
202 Accepted — la emisión sigue en curso. La respuesta trae el pase con status: "creating"; consúltalo después o escucha el webhook pass.created.

curl -X POST "https://api.alaramx.com/v1/passes" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pass_id": "cliente-001",
    "pass_template_id": "lealtad_oro",
    "visible": {
      "nombre": "Ada Lovelace",
      "miembro_desde": "2026-07-24"
    },
    "hidden": {
      "crm_id": "9f3c1a"
    }
  }'

{
  "id": "cliente-001",
  "visible": {
    "nombre": "Ada Lovelace",
    "miembro_desde": "2026-07-24",
    "puntos": "0"
  },
  "hidden": { "crm_id": "9f3c1a" },
  "qr_value": "ALARA:cliente-001",
  "status": "issued",
  "download_url": "https://.../download/8f2c…",
  "reinstall_blocked": false,
  "loyalty_type": "balance",
  "balance": 0,
  "created_at": "2026-07-24T09:14:22Z",
  "updated_at": "2026-07-24T09:14:23Z"
}

Errores frecuentes

HTTP	`code`	Causa
`409`	`RESOURCE_CONFLICT`	Ya existe un pase activo con ese `pass_id`.
`403`	`UNAUTHORIZED`	La plantilla pertenece a otra cuenta.
`422`	`PASS_TEMPLATE_NOT_FOUND`	La plantilla no existe.
`422`	`PASS_TEMPLATE_DATA_INVALID`	Los datos no son válidos para esa plantilla.
`400`	`INVALID_INPUT`	Una llave de `visible` no existe en la plantilla o está bloqueada.
`502`	`PASS_PROVIDER_UNAVAILABLE`	El servicio de emisión no respondió.

Si reintentas una creación que quizá ya funcionó, un 409 RESOURCE_CONFLICT significa que el pase ya existe: consúltalo con GET /v1/passes/{id} en lugar de tratarlo como un fallo.

Listar pases

GET /v1/passes

Parámetros

integer

default:"25"

Máximo 100.

integer

default:"0"

string

Busca en el identificador del pase y en los valores de sus campos visibles.

string

Repetible. Valores: creating, creation_failed, issued, active, removed, deactivated.

string

default:"created_at"

id, name, created_at o updated_at.

string

default:"desc"

asc o desc.

string

RFC 3339, inclusivo.

string

RFC 3339, exclusivo.

string

RFC 3339, inclusivo.

string

RFC 3339, exclusivo.

boolean

default:"false"

Incluye también los pases eliminados.

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

curl "https://api.alaramx.com/v1/passes?status=active&limit=50&sort_dir=asc" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Consultar un pase

GET /v1/passes/{id}

string

required

El pass_id del pase.

boolean

default:"false"

Permite recuperar un pase eliminado.

Devuelve 200 OK con el pase, o 404 RESOURCE_NOT_FOUND.

curl "https://api.alaramx.com/v1/passes/cliente-001" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Actualizar un pase

PATCH /v1/passes/{id}

Actualización parcial: los campos que no envíes quedan intactos.

object

Se fusiona con los campos actuales. No puedes escribir campos bloqueados de lealtad.

object

Se fusiona con los datos ocultos actuales.

object | null

Envía un objeto para cambiar la apariencia, o null explícito para limpiarla. Si omites la llave, la apariencia no cambia.

Devuelve 204 No Content.

curl -X PATCH "https://api.alaramx.com/v1/passes/cliente-001" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visible": { "nivel": "Oro" } }'

Para mover puntos o sellos no uses este endpoint. Usa POST /v1/passes/{id}/loyalty: es la única vía que mantiene sincronizado el contador que ve el portador.

Eliminar un pase

DELETE /v1/passes/{id}

Eliminación lógica: el pase deja de estar disponible pero su historial se conserva. Devuelve 204 No Content.

curl -X DELETE "https://api.alaramx.com/v1/passes/cliente-001" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Este endpoint sigue disponible aunque la cuenta esté suspendida por facturación, ya que solo reduce el consumo.

Ajustar saldo de lealtad

POST /v1/passes/{id}/loyalty

Suma o resta puntos o sellos y actualiza el pase en el wallet del portador.

integer

required

Cantidad a sumar. Usa un valor negativo para restar.

string

Mensaje push opcional que acompaña al cambio.

Devuelve 202 Accepted con cuerpo vacío: la actualización se aplica de forma asíncrona.

curl -X POST "https://api.alaramx.com/v1/passes/cliente-001/loyalty" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_to_add": 5,
    "message": "¡Sumaste 5 puntos!"
  }'

curl -X POST "https://api.alaramx.com/v1/passes/cliente-001/loyalty" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_to_add": -50,
    "message": "Canjeaste 50 puntos por un café"
  }'

Errores

HTTP	`code`	Causa
`400`	`NO_LOYALTY_PROGRAM`	El pase no tiene programa de lealtad.
`404`	`RESOURCE_NOT_FOUND`	El pase no existe.

Para confirmar el saldo resultante, consulta el pase o escucha el webhook pass.balanceUpdate.

Empezar

Referencia

Webhooks

Pases

Pases

El objeto pase

Crear un pase

Cuerpo

Respuesta

Errores frecuentes

Listar pases

Parámetros

Consultar un pase

Actualizar un pase

Eliminar un pase

Ajustar saldo de lealtad

Errores

​Pases

​El objeto pase

​Crear un pase

​Cuerpo

​Respuesta

​Errores frecuentes

​Listar pases

​Parámetros

​Consultar un pase

​Actualizar un pase

​Eliminar un pase

​Ajustar saldo de lealtad

​Errores

Pases

El objeto pase

Crear un pase

Cuerpo

Respuesta

Errores frecuentes

Listar pases

Parámetros

Consultar un pase

Actualizar un pase

Eliminar un pase

Ajustar saldo de lealtad

Errores