Skip to content
Guía del Centro de ayuda · Canjes y transaccionesFase de incorporación 2
4 min de lecturaVerificado 2026-11-16

Puntos de fidelidad y sellos

Suma sellos al escanear, reinicia tarjetas completadas, asigna puntos por visita y evalúa subidas de nivel.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Selector «Añadir una mecánica de pase» (Zoom)

Elige entre 6 mecánicas integradas: Pase de sellos, Canje de sellos, Valor almacenado, Puntos y niveles, Validación una vez al día o Extender vencimiento.

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-Key o campo idempotencyKey). 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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
ACUMULACIÓN DE FIDELIZACIÓN, ASCENSO DE NIVEL Y CANJE DE RECOMPENSA
ACTORES DEL SISTEMA
P1 Escáner / Terminal POS
P2 Loyalty & Stamp Engine / Mechanics
P3 Tier Progression Engine y Wallet Push
PASO 1 SOLICITUD / ACCIÓN POST/api/v1/scans
PASO 2 SOLICITUD / ACCIÓN Ejecutar ScanAction / Mechanic:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
PASO 3 SOLICITUD / ACCIÓN Comprobar umbrales de nivel
PASO 4 SOLICITUD / ACCIÓN Hidratar recursos/colores de nivel
PASO 5 RESPUESTA Persistir saldo y libro mayor
PASO 6 RESPUESTA 200 OK (resultingValue)
PASO 7 SOLICITUD / ACCIÓN Emitir eventos POINTS_UPDATED
›
8. Push APNs y Google Wallet
›
y TIER_CHANGED
›
(Tira e insignia actualizadas)

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):

EndpointAutenticación / GuardiaFinalidad principal
POST /api/v1/scans/pass/:passId/usex-scanner-keyMutación de sellos, puntos o saldo iniciada desde el escáner mediante request payload.
POST /api/v1/passes/:id/useJWT del espacio de trabajo / API KeyEjecución de sellos o puntos sobre un pase iniciada desde CRM backend o webhook.
POST /api/v1/mechanics/redeemClave 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/stateClave de escáner o JWTDevuelve el saldo actual de sellos/puntos junto con indicadores de capacidad allowedActions.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerClave de escáner o JWTLista el historial de transacciones de la mecánica (?limit=50, máx. 500).
GET /api/v1/balance-changesJWT del espacio de trabajo / API KeyConsulta 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:

POST /api/v1/scans/pass/pass_loy_884120/use
Encabezados
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Campo (request payload)TipoValidación / Notas
actionenumeración (opcional, por defecto INCREMENT)Uno de 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (opcional)Verifica la mecánica de destino vinculada a este pase.
amountcadena decimal (opcional)Debe coincidir con /^\d+(\.\d{1,6})?$/ (por ejemplo, "2" o "12.90").
deviceId / operatorId / locationstrings (opcionales)Se registran en el libro mayor de auditoría para conciliación de turnos.
idempotencyKeystring (opcional)Debe coincidir con el encabezado Idempotency-Key si se proporcionan ambos.

Respuesta (200 OK — IPassUseResponse):

JSON
{
  "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

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):

JSON
{
  "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. 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. 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. 3
    Alerta de celebración en pantalla de bloqueo: Dispara una notificación changeMessage en Apple Wallet (por ejemplo, "¡Enhorabuena! Has alcanzado el nivel Gold") y emite el disparador de flujo de trabajo TIER_CHANGED para 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.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.