Descripción general
Passinstance procesa el sellado de tarjetas, la acumulación de puntos de fidelización, las promociones automáticas de nivel y los canjes de recompensas mediante Loyalty & Stamp Engine, Pass Mechanics API y Tier Progression Engine. El personal y las integraciones backend pueden activar actualizaciones de fidelización mediante un escaneo estándar en mostrador (POST /api/v1/scans), ejecución directa de pase desde escáner (POST /api/v1/scans/pass/:passId/use), uso de pase autenticado por espacio de trabajo (POST /api/v1/passes/:id/use), canje en terminal POS (POST /v1/pos/redeem) o canje explícito de recompensa (POST /api/v1/mechanics/redeem).
Importante: Todas las mutaciones de saldo de fidelización y los canjes de recompensas se ejecutan en transacciones atómicas con cumplimiento estricto de idempotencia (encabezado
Idempotency-Keyo campoidempotencyKey). Tras cualquier cambio de sellos, puntos o nivel, Passinstance regenera automáticamente las imágenes de tira dinámicas (strip) y envía actualizaciones push silenciosas a Apple Wallet y Google Wallet.
Arquitectura y flujo de ejecución de mecánicas
Acciones de mecánica permitidas y endpoints de estado
request payload acepta una de siete acciones explícitas (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), en correspondencia con la taxonomía del libro mayor scan action (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):
| Endpoint | Autenticación / Guardia | Finalidad principal |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Mutación de sellos, puntos o saldo iniciada desde el escáner mediante request payload. |
POST /api/v1/passes/:id/use | JWT del espacio de trabajo / API Key | Ejecución de sellos o puntos sobre un pase iniciada desde CRM backend o webhook. |
POST /api/v1/mechanics/redeem | Clave de escáner o JWT (request payload) | Ejecuta el canje de una tarjeta de sellos completa o una recompensa (action: 'DECREMENT'). |
GET /api/v1/mechanics/:mechanicId/passes/:passId/state | Clave de escáner o JWT | Devuelve el saldo actual de sellos/puntos junto con indicadores de capacidad allowedActions. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Clave de escáner o JWT | Lista el historial de transacciones de la mecánica (?limit=50, máx. 500). |
GET /api/v1/balance-changes | JWT del espacio de trabajo / API Key | Consulta el historial de mutaciones de saldo prepago y fidelización en todo el inquilino. |
Endpoints para acumulación de fidelización y canje de recompensas
1. Ejecución directa de mecánica (POST /api/v1/scans/pass/:passId/use)
Cuando un escáner o terminal POS ya consultó el pase (GET /api/v1/scans/pass?barcode=...), puede ejecutar una adición de sellos, concesión de puntos o decremento directamente sobre el UUID :passId usando request payload:
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Campo (request payload) | Tipo | Validación / Notas |
|---|---|---|
action | enumeración (opcional, por defecto INCREMENT) | Uno de 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (opcional) | Verifica la mecánica de destino vinculada a este pase. |
amount | cadena decimal (opcional) | Debe coincidir con /^\d+(\.\d{1,6})?$/ (por ejemplo, "2" o "12.90"). |
deviceId / operatorId / location | strings (opcionales) | Se registran en el libro mayor de auditoría para conciliación de turnos. |
idempotencyKey | string (opcional) | Debe coincidir con el encabezado Idempotency-Key si se proporcionan ambos. |
Respuesta (200 OK — IPassUseResponse):
{
"success": true,
"data": {
"scanId": "scan_01hxyz8820ab",
"passId": "pass_loy_884120",
"action": "INCREMENT",
"success": true,
"resultingValue": "8"
},
"description": "Pass INCREMENT successfully",
"errors": [],
"statusCode": 200
}
2. Canje de una recompensa desbloqueada (POST /api/v1/mechanics/redeem)
Cuando un cliente reclama una recompensa obtenida en una tarjeta de sellos o gasta unidades acumuladas, invoque POST /api/v1/mechanics/redeem con request payload:
POST /api/v1/mechanics/redeem Encabezados: x-scanner-key: sk_live_cafe_counter_01 (o Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json
{
"passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"ruleId": "default",
"idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}
(Nota: Tanto passId como mechanicId —y el campo opcional idempotencyKey dentro del cuerpo JSON— deben ser UUID válidos; si se proporciona ruleId, debe ser exactamente "default".)
Respuesta (200 OK — IRedeemResponse):
{
"success": true,
"newBalance": 0,
"newBalanceDecimal": "0",
"reward": "default",
"message": "Reward redeemed successfully"
}
Ascensos automáticos de nivel (Tier Progression Engine)
Cada vez que un escaneo, POST /api/v1/scans/pass/:passId/use o POST /v1/pos/redeem (operation: "ADD_POINTS" o "ADD_STAMPS") modifica el saldo de puntos o visitas de un pase, Tier Progression Engine evalúa los umbrales de nivel configurados en la plantilla:
-
1
Evaluación de umbrales: Comprueba si el saldo actualizado alcanza un nivel superior (por ejemplo,
Bronze: 0–249,Silver: 250–499,Gold: 500+). -
2
Hidratación visual y de recursos: Reemplaza los colores de fondo específicos del nivel, las imágenes de tira/banner y los campos de etiqueta de nivel en el registro del pase.
-
3
Alerta de celebración en pantalla de bloqueo: Dispara una notificación
changeMessageen Apple Wallet (por ejemplo, "¡Enhorabuena! Has alcanzado el nivel Gold") y emite el disparador de flujo de trabajoTIER_CHANGEDpara que pueda automatizar ventajas de bienvenida.
Obtenga más información sobre cómo configurar programas de fidelización en Tarjetas de fidelización y sellos y cómo automatizar recompensas de nivel en Configuración de flujos de trabajo.
