Reglas de activación

Una regla de activación automatiza a Alara: define una condición y una o más acciones. Cuando la condición se cumple para un pase, Alara ejecuta las acciones sobre ese pase sin que tú tengas que intervenir. Ejemplos típicos:

Si alguien no ha venido en 30 días, envíale un push con una promoción.
Si visita 5 días seguidos, asígnale una recompensa.
Tres días antes del vencimiento de su membresía, recuérdaselo.
Al completar 10 sellos, otórgale un café gratis y reinicia el contador.

Una regla se ejecuta como máximo una vez por cada combinación de regla, pase y ocasión. No recibirás acciones duplicadas por el mismo hecho.

El objeto regla

string

Identificador (UUID) de la regla.

string

Nombre descriptivo.

string

Tipo de condición.

object

Configuración de la condición, según el tipo.

array

Acciones a ejecutar.

Show propiedades

string

Tipo de acción.

object

Configuración de la acción.

boolean

Si la regla está activa.

string

Fecha de creación.

string

Última modificación.

En este recurso, created_at y updated_at usan el formato 2026-07-24 14:41:58.842 +0000 UTC, no RFC 3339.

Tipos de condición

scan_inactivity — no ha escaneado en N días

Se dispara cuando un pase lleva cierto número de días sin registrar escaneos.

integer

required

Días de inactividad. Mínimo 1.

string

required

A qué lectores aplica: any (cualquiera), per_reader (se evalúa por lector de forma independiente) o specific (un lector concreto).

string

Identificador del lector. Obligatorio si reader_scope es specific; prohibido en los otros casos.

{
  "inactive_days": 30,
  "reader_scope": "any"
}

scan_consecutive — ha escaneado N días seguidos

Se dispara cuando un pase acumula una racha de días consecutivos con escaneo.

integer

required

Días consecutivos requeridos. Mínimo 1.

string

required

any, per_reader o specific.

string

Obligatorio solo con reader_scope: "specific".

{
  "consecutive_days": 5,
  "reader_scope": "specific",
  "reader": "sucursal-centro-01"
}

date_field — en la fecha de un campo del pase

Se dispara según una fecha guardada en un campo del pase, por ejemplo un cumpleaños o el vencimiento de una membresía.

string

required

Nombre del campo del pase que contiene la fecha.

string

required

Cada cuánto se repite: daily, weekly, monthly, yearly u once.

{
  "field_name": "cumpleanos",
  "recurrence": "yearly"
}

datetime_field — a X minutos de una fecha y hora

Se dispara con un desfase respecto a una fecha y hora guardada en el pase. Útil para recordatorios previos a una cita o reservación.

string

required

Campo del pase que contiene la fecha y hora.

integer

required

Minutos de desfase. Debe ser un entero mayor o igual a 0.

{
  "field_name": "proxima_cita",
  "offset_minutes": 60
}

stamp_threshold — al alcanzar N sellos

Se dispara cuando el contador de sellos de un pase alcanza cierto valor.

integer | string

required

Número de sellos (entero mayor o igual a 1), o la cadena literal "card_full" para dispararse cuando la tarjeta se completa según su plantilla.

{ "threshold": "card_full" }

Tipos de acción

Una regla admite como máximo una acción de cada tipo. Repetir un action_name devuelve 400 RULE_ACTION_DUPLICATE_TYPE.

push_notification — enviar una notificación

string

required

Texto del push. No puede estar vacío.

{
  "action_name": "push_notification",
  "config": { "message": "¡Te extrañamos! Tienes 15% de descuento esta semana." }
}

set_field — escribir campos del pase

array

required

Lista no vacía de campos a escribir.

Show propiedades de cada elemento

string

required

visible (se muestra en el pase) o hidden (uso interno).

string

required

Nombre del campo.

any

required

Valor a escribir. Los campos visible se guardan como texto.

{
  "action_name": "set_field",
  "config": {
    "fields": [
      { "target": "visible", "field": "nivel",         "value": "Oro" },
      { "target": "hidden",  "field": "ultimo_ascenso", "value": "2026-07-24" }
    ]
  }
}

set_loyalty — fijar el saldo de lealtad

Fija el contador a un valor absoluto. A diferencia de POST /v1/passes/{id}/loyalty, que suma un delta, esta acción establece el valor: es la forma habitual de reiniciar una tarjeta de sellos completada.

integer

required

Nuevo valor. Debe ser mayor o igual a 0.

{
  "action_name": "set_loyalty",
  "config": { "value": 0 }
}

assign_reward — otorgar una recompensa

string

required

slug de una recompensa activa de tu catálogo. Un slug desconocido devuelve 400 ACTION_ASSIGN_REWARD_SLUG_UNKNOWN.

{
  "action_name": "assign_reward",
  "config": { "slug": "cafe_gratis" }
}

Crear una regla

POST /v1/trigger-rules

string

required

Nombre descriptivo de la regla.

string

required

Uno de los tipos de condición.

object

required

Configuración de la condición.

array

required

Al menos una acción.

boolean

Si la regla queda activa al crearse.

Devuelve 201 Created con un mensaje de confirmación. No devuelve el objeto de la regla: consúltalo con GET /v1/trigger-rules si necesitas su id.

curl -X POST "https://api.alaramx.com/v1/trigger-rules" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tarjeta completa: café gratis",
    "type": "stamp_threshold",
    "config": { "threshold": "card_full" },
    "actions": [
      {
        "action_name": "assign_reward",
        "config": { "slug": "cafe_gratis" }
      },
      {
        "action_name": "push_notification",
        "config": { "message": "¡Completaste tu tarjeta! Tu café va por nuestra cuenta." }
      },
      {
        "action_name": "set_loyalty",
        "config": { "value": 0 }
      }
    ],
    "enabled": true
  }'

curl -X POST "https://api.alaramx.com/v1/trigger-rules" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sin visitas en 30 días",
    "type": "scan_inactivity",
    "config": { "inactive_days": 30, "reader_scope": "any" },
    "actions": [
      {
        "action_name": "push_notification",
        "config": { "message": "¡Te extrañamos! 15% de descuento esta semana." }
      }
    ],
    "enabled": true
  }'

{ "message": "Trigger rule created successfully" }

Listar reglas

GET /v1/trigger-rules

Devuelve 200 OK con un arreglo de reglas. Este listado no está paginado.

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

Consultar una regla

GET /v1/trigger-rules/{rule_id}

string

required

UUID de la regla. Un valor que no sea UUID devuelve 400 INVALID_RULE_ID.

Devuelve 200 OK con la regla.

Actualizar una regla

PUT /v1/trigger-rules/{rule_id}

Todos los campos son opcionales, pero config y actions se reemplazan por completo, no se fusionan: si envías actions, la nueva lista sustituye a la anterior.

string

Nuevo nombre.

object

Nueva configuración, reemplaza la anterior.

array

Nuevas acciones, reemplazan las anteriores.

boolean

Activa o desactiva la regla. Si lo omites, no cambia.

Devuelve 200 OK con un mensaje de confirmación.

curl -X PUT "https://api.alaramx.com/v1/trigger-rules/8f7e6d5c-4b3a-4291-8807-6f5e4d3c2b1a" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Eliminar una regla

DELETE /v1/trigger-rules/{rule_id}

Devuelve 204 No Content.

Empezar

Referencia

Webhooks

Reglas de activación

Reglas de activación

El objeto regla

Tipos de condición

Tipos de acción

Crear una regla

Listar reglas

Consultar una regla

Actualizar una regla

Eliminar una regla

​Reglas de activación

​El objeto regla

​Tipos de condición

​Tipos de acción

​Crear una regla

​Listar reglas

​Consultar una regla

​Actualizar una regla

​Eliminar una regla

Reglas de activación

El objeto regla

Tipos de condición

Tipos de acción

Crear una regla

Listar reglas

Consultar una regla

Actualizar una regla

Eliminar una regla