Recompensas

Las recompensas separan el catálogo de las asignaciones individuales:

Una recompensa es la definición del beneficio: qué es, cuántas veces se canjea, cuándo expira. Se identifica con un slug estable.
Un derecho (entitlement) es esa recompensa ya asignada a un pase concreto, con su propio vencimiento y sus canjes restantes.

Esta función debe estar habilitada en tu cuenta. Consultar y administrar el catálogo siempre funciona; asignar y canjear requieren la función activa. Si recibes 403 REWARDS_DISABLED, escríbenos a dev@alaramx.com.

El objeto recompensa

string

Identificador estable y legible, por ejemplo cafe_gratis. Es inmutable.

string

Nombre visible del beneficio.

string

gift, discount o custom.

string

Descripción del beneficio.

string

active o archived.

integer

Versión actual. Cada edición publica una versión nueva; los derechos ya asignados conservan la versión con la que se crearon.

boolean

Si un mismo pase puede recibir la recompensa más de una vez.

integer

Cuántos canjes permite cada derecho asignado.

integer | null

Cuántas veces puede asignarse en total. null significa sin límite.

object

Política de vencimiento.

Show propiedades

string

none (no expira), relative_window (expira X tiempo después de asignarse) o fixed_end (expira en una fecha fija).

integer

Segundos de vigencia. Presente solo con relative_window.

string

Fecha límite en RFC 3339. Presente solo con fixed_end.

string

RFC 3339.

string

RFC 3339.

El objeto derecho

string

Identificador (UUID) del derecho.

string

Identificador de la familia de recompensa.

string

Versión concreta de la recompensa asignada.

string

slug de la recompensa.

string

Nombre en el momento de la asignación.

string

gift, discount o custom.

string

Pase al que pertenece.

string

available, redeemed o expired.

integer

Canjes disponibles.

string | null

Cuándo expira, RFC 3339.

string | null

time_elapsed o replaced.

string

manual (asignado por API o desde el Dashboard) o automatic (asignado por una regla de activación).

string

RFC 3339.

string

RFC 3339.

Crear una recompensa

POST /v1/rewards

string

required

Nombre del beneficio. Máximo 200 caracteres.

string

required

gift, discount o custom.

string

Identificador estable. Debe cumplir el patrón minusculas_y_numeros (segmentos alfanuméricos separados por guion bajo), máximo 80 caracteres. Si lo omites, se genera a partir del name.

string

Descripción. Máximo 2 000 caracteres.

boolean

Permite que un mismo pase reciba la recompensa más de una vez.

integer

Canjes por derecho asignado. Debe ser al menos 1; enviar 0 equivale a 1.

integer

Tope total de asignaciones. Omítelo para que sea ilimitado.

object

required

Política de vencimiento.

Show propiedades

string

required

none, relative_window o fixed_end.

integer

Obligatorio si y solo si kind es relative_window. Debe ser mayor que 0.

string

Obligatorio si y solo si kind es fixed_end. RFC 3339.

Devuelve 201 Created con la recompensa.

curl -X POST "https://api.alaramx.com/v1/rewards" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Café gratis",
    "slug": "cafe_gratis",
    "kind": "gift",
    "description": "Un café del tamaño que elijas, por cuenta de la casa.",
    "redemption_allowance": 1,
    "repeat_assignment": true,
    "expiration": {
      "kind": "relative_window",
      "window_seconds": 2592000
    }
  }'

{
  "slug": "cafe_gratis",
  "name": "Café gratis",
  "kind": "gift",
  "description": "Un café del tamaño que elijas, por cuenta de la casa.",
  "status": "active",
  "version": 1,
  "repeat_assignment": true,
  "redemption_allowance": 1,
  "expiration": {
    "kind": "relative_window",
    "window_seconds": 2592000
  },
  "created_at": "2026-07-24T16:00:00Z",
  "updated_at": "2026-07-24T16:00:00Z"
}

Listar el catálogo

GET /v1/rewards

boolean

default:"false"

Incluye también las recompensas archivadas.

Devuelve 200 OK con un objeto { "rewards": [ ... ] }. Este listado no está paginado.

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

Consultar una recompensa

GET /v1/rewards/{slug}

Devuelve 200 OK con la recompensa, o 404 RESOURCE_NOT_FOUND.

Editar una recompensa

PUT /v1/rewards/{slug}

Publica una versión nueva. Los derechos ya asignados conservan las condiciones con las que se crearon; solo las asignaciones futuras usan la versión nueva. Acepta los mismos campos que la creación, salvo slug, que es inmutable. Devuelve 200 OK con la recompensa y su version incrementada.

Archivar, restaurar y eliminar

POST /v1/rewards/{slug}/archive

Archiva la recompensa: deja de poder asignarse, pero los derechos ya otorgados siguen siendo válidos y canjeables. Devuelve 204 No Content.

POST /v1/rewards/{slug}/restore

Restaura una recompensa archivada publicando una versión nueva. Acepta el mismo cuerpo que la edición. Devuelve 200 OK.

DELETE /v1/rewards/{slug}

Elimina la recompensa del catálogo. Devuelve 204 No Content.

Archivar o eliminar devuelve 409 RESOURCE_CONFLICT si una regla de activación todavía referencia el slug, o si ya existen derechos asignados. Actualiza primero la regla.

Asignar una recompensa a un pase

POST /v1/passes/{id}/rewards/assign

string

required

El pass_id del pase.

string

required

slug de la recompensa a asignar.

Devuelve 201 Created con el derecho creado.

curl -X POST "https://api.alaramx.com/v1/passes/cliente-001/rewards/assign" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "cafe_gratis" }'

{
  "id": "d4c3b2a1-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
  "family_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "definition_id": "9f8e7d6c-5b4a-4392-8180-7a6b5c4d3e2f",
  "reward_slug": "cafe_gratis",
  "reward_name": "Café gratis",
  "reward_kind": "gift",
  "pass_id": "cliente-001",
  "status": "available",
  "remaining_redemptions": 1,
  "expiration_timestamp": "2026-08-23T16:05:00Z",
  "assignment_source_type": "manual",
  "created_at": "2026-07-24T16:05:00Z",
  "updated_at": "2026-07-24T16:05:00Z"
}

Errores

HTTP	`code`	Causa
`409`	`REWARD_NOT_ASSIGNABLE`	La recompensa está archivada, o el pase ya la tiene y `repeat_assignment` es `false`.
`409`	`REWARD_ASSIGNMENT_LIMIT_REACHED`	Se agotó el `assignment_limit`.
`409`	`REWARD_FIXED_END_PASSED`	La fecha fija de expiración ya pasó.
`404`	`RESOURCE_NOT_FOUND`	El pase o el `slug` no existen.
`403`	`REWARDS_DISABLED`	La función no está habilitada.

Listar los derechos de un pase

GET /v1/passes/{id}/rewards

boolean

default:"false"

Por omisión devuelve solo los derechos canjeables. Con true incluye también los canjeados y expirados.

Devuelve 200 OK con un objeto { "entitlements": [ ... ] }.

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

Este es el endpoint que consulta tu punto de venta al escanear un pase, para mostrarle al cajero qué beneficios puede aplicar en ese momento.

Canjear un derecho

POST /v1/passes/{id}/rewards/{entitlement_id}/redeem

string

required

El pass_id del pase.

string

required

UUID del derecho.

integer

default:"1"

Cuántos canjes descontar.

string

Dónde se canjeó, por ejemplo la sucursal o la caja.

string

Nota libre sobre el canje.

Devuelve 200 OK con el registro del canje y el derecho actualizado.

curl -X POST "https://api.alaramx.com/v1/passes/cliente-001/rewards/d4c3b2a1-9f8e-4d7c-8b6a-5f4e3d2c1b0a/redeem" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "context": "sucursal-centro-01",
    "note": "Ticket A-4471"
  }'

{
  "redemption": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "entitlement_id": "d4c3b2a1-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
    "amount": 1,
    "context": "sucursal-centro-01",
    "note": "Ticket A-4471",
    "created_at": "2026-07-24T18:20:00Z"
  },
  "entitlement": {
    "id": "d4c3b2a1-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
    "reward_slug": "cafe_gratis",
    "reward_name": "Café gratis",
    "reward_kind": "gift",
    "pass_id": "cliente-001",
    "status": "redeemed",
    "remaining_redemptions": 0,
    "assignment_source_type": "manual",
    "created_at": "2026-07-24T16:05:00Z",
    "updated_at": "2026-07-24T18:20:00Z"
  }
}

El canje es irreversible. No existe un endpoint para deshacerlo. Confirma con la persona antes de registrarlo.

Errores

HTTP	`code`	Causa
`409`	`REWARD_NOT_REDEEMABLE`	El derecho ya está canjeado o expiró.
`409`	`REWARD_INSUFFICIENT_REDEMPTIONS`	El `amount` supera los canjes restantes.
`404`	`RESOURCE_NOT_FOUND`	El pase o el derecho no existen.

Conteo de derechos

GET /v1/rewards/entitlement-counts

Resumen agregado de todos los derechos de tu cuenta.

curl "https://api.alaramx.com/v1/rewards/entitlement-counts" \
  -H "Authorization: Bearer $ALARA_API_KEY"

{
  "total": 4820,
  "redeemable": 1207,
  "redeemed": 3401,
  "expired": 212
}

Asignación automática

Para otorgar recompensas sin intervención manual, usa la acción assign_reward de una regla de activación. Los derechos así creados llegan con assignment_source_type: "automatic".

Empezar

Referencia

Webhooks

Recompensas

Recompensas

El objeto recompensa

El objeto derecho

Crear una recompensa

Listar el catálogo

Consultar una recompensa

Editar una recompensa

Archivar, restaurar y eliminar

Asignar una recompensa a un pase

Errores

Listar los derechos de un pase

Canjear un derecho

Errores

Conteo de derechos

Asignación automática

​Recompensas

​El objeto recompensa

​El objeto derecho

​Crear una recompensa

​Listar el catálogo

​Consultar una recompensa

​Editar una recompensa

​Archivar, restaurar y eliminar

​Asignar una recompensa a un pase

​Errores

​Listar los derechos de un pase

​Canjear un derecho

​Errores

​Conteo de derechos

​Asignación automática

Recompensas

El objeto recompensa

El objeto derecho

Crear una recompensa

Listar el catálogo

Consultar una recompensa

Editar una recompensa

Archivar, restaurar y eliminar

Asignar una recompensa a un pase

Errores

Listar los derechos de un pase

Canjear un derecho

Errores

Conteo de derechos

Asignación automática