Escaneos

Un escaneo representa la validación de un pase: en la entrada de un evento, en el punto de venta o en un lector NFC. Además de quedar en el historial, los escaneos alimentan las reglas de activación.

Registrar un escaneo

POST /v1/scans

Registra una lectura y devuelve el veredicto de Alara.

Cuerpo

string

required

El identificador del pase que se escaneó.

string

required

Identificador del lector o punto de escaneo. Lo recibirás de vuelta como scanner_id.

object

Metadatos libres del escaneo: sucursal, ticket, monto, lo que necesites. Se devuelve como metadata.

string

Veredicto que tú impones, si tu sistema ya decidió. Acepta "true" o "false" (también "1" / "0"). Si lo omites, Alara evalúa el escaneo.

string

Motivo del rechazo. Solo se registra cuando status indica fallo.

Parámetros de consulta

boolean

default:"false"

Si es true, la respuesta incluye el pase escaneado. Evita una segunda petición cuando necesitas mostrar datos del portador en el momento.

Respuesta

Devuelve 200 OK.

string

Identificador del escaneo.

string

El reader_id que enviaste.

string

Nombre del lector, si está registrado en tu cuenta.

string

Identificador del pase.

string

Momento del escaneo, RFC 3339.

object

Los metadatos que enviaste en meta.

string

El veredicto: succeeded o failed.

string

Código del motivo cuando status es failed. Cadena vacía cuando fue exitoso.

object

Presente solo con ?pass_info=true.

Show propiedades

string

Identificador del pase.

object

Campos visibles del pase.

string

Plantilla del pase.

string

Estado del pase.

string

none, balance o stamps.

integer | null

Saldo actual.

Un escaneo rechazado también responde 200 OK. El veredicto vive en el campo status del cuerpo, no en el código HTTP. Revisa siempre status antes de dar acceso o entregar un beneficio.

curl -X POST "https://api.alaramx.com/v1/scans?pass_info=true" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pass_id": "cliente-001",
    "reader_id": "sucursal-centro-01",
    "meta": {
      "ticket": "A-4471",
      "monto": 189.50
    }
  }'

{
  "id": "7c1f9a20-4b3d-4e5f-8a90-1b2c3d4e5f60",
  "scanner_id": "sucursal-centro-01",
  "scanner_name": "Sucursal Centro",
  "pass_id": "cliente-001",
  "created_at": "2026-07-24T14:41:58Z",
  "metadata": { "ticket": "A-4471", "monto": 189.50 },
  "status": "succeeded",
  "reason": "",
  "pass": {
    "id": "cliente-001",
    "visible": { "nombre": "Ada Lovelace", "puntos": "42" },
    "template_id": "lealtad_oro",
    "status": "active",
    "loyalty_type": "balance",
    "balance": 42
  }
}

{
  "id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
  "scanner_id": "sucursal-centro-01",
  "pass_id": "cliente-001",
  "created_at": "2026-07-24T14:52:03Z",
  "metadata": {},
  "status": "failed",
  "reason": "DOUBLE_SCAN"
}

Motivos de rechazo

`reason`	Qué significa
`DOUBLE_SCAN`	El pase se escaneó de nuevo dentro del periodo de espera configurado para ese lector.
`PASS_SUSPENDED`	El pase está desactivado o eliminado.

Listar escaneos

GET /v1/scans

Parámetros

integer

default:"25"

Máximo 100.

integer

default:"0"

string

Busca en el identificador del escaneo, el del pase, el del lector y el nombre del lector.

string

Repetible. Valores: processing, succeeded, failed.

string

Repetible. Filtra por uno o varios lectores.

string

default:"created_at"

id, name o created_at.

string

default:"desc"

asc o desc.

string

RFC 3339, inclusivo.

string

RFC 3339, exclusivo.

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

En este listado, created_at viene con el formato 2026-07-24 14:41:58.842 +0000 UTC, no en RFC 3339. Consulta Convenciones.

curl "https://api.alaramx.com/v1/scans?status=succeeded&scanner_id=sucursal-centro-01&created_from=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer $ALARA_API_KEY"

[
  {
    "id": "7c1f9a20-4b3d-4e5f-8a90-1b2c3d4e5f60",
    "scanner_id": "sucursal-centro-01",
    "scanner_name": "Sucursal Centro",
    "pass_id": "cliente-001",
    "created_at": "2026-07-24 14:41:58.842 +0000 UTC",
    "metadata": { "ticket": "A-4471" },
    "status": "succeeded",
    "reason": ""
  }
]

Consultar un escaneo

GET /v1/scans/{id}

string

required

Identificador del escaneo.

Devuelve 200 OK con el escaneo, o 404 RESOURCE_NOT_FOUND.

curl "https://api.alaramx.com/v1/scans/7c1f9a20-4b3d-4e5f-8a90-1b2c3d4e5f60" \
  -H "Authorization: Bearer $ALARA_API_KEY"

En tiempo real

Si prefieres reaccionar a los escaneos en lugar de consultarlos, suscríbete al evento scan.created y Alara notificará a tu servidor cada vez que se registre uno.

Empezar

Referencia

Webhooks

Escaneos

Escaneos

Registrar un escaneo

Cuerpo

Parámetros de consulta

Respuesta

Motivos de rechazo

Listar escaneos

Parámetros

Consultar un escaneo

En tiempo real

​Escaneos

​Registrar un escaneo

​Cuerpo

​Parámetros de consulta

​Respuesta

​Motivos de rechazo

​Listar escaneos

​Parámetros

​Consultar un escaneo

​En tiempo real

Escaneos

Registrar un escaneo

Cuerpo

Parámetros de consulta

Respuesta

Motivos de rechazo

Listar escaneos

Parámetros

Consultar un escaneo

En tiempo real