Descripción general
Los cupones promocionales y vales de un solo uso requieren una validación atómica estricta para que un pase nunca pueda canjearse dos veces en cajas distintas ni compartirse mediante capturas de pantalla estáticas. Al combinar una plantilla de cupón con una ScannerConfiguration configurada en VOIDED_AFTER_SCAN scan mode, Passinstance valida el código de barras, pasa el pase al estado VOIDED, bloquea los intentos de repetición y envía de inmediato una actualización silenciosa para atenuar el pase en el dispositivo del cliente.
Importante: Incluya siempre una clave de idempotencia al enviar canjes desde terminales POS (encabezado
x-idempotency-keyenPOST /api/v1/scans, oidempotencyKeyenrequest payloadenPOST /v1/pos/redeem). Si un terminal reintenta la solicitud por un tiempo de espera de red agotado, Passinstance devuelve el recibo de aceptación original en lugar de devolver un falso errorALREADY_VOIDEDal cajero.
Arquitectura de canje de un solo uso
Primer escaneo: canje atómico (POST /api/v1/scans)
Cuando un cajero escanea un cupón activo en caja, el escáner envía la carga útil del código de barras a POST /api/v1/scans autenticado mediante x-scanner-key:
Solicitud HTTP
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-774109",
"scannerConfigurationId": "scfg_coupon_checkout",
"operatorId": "cashier_12",
"terminalId": "reg_berlin_01",
"validationData": {
"receiptNumber": "RCPT-2026-88412",
"basketTotal": 64.00
}
}
Respuesta HTTP (200 OK — Aceptado y anulado)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "DefaultAcceptanceRule", "passed": true }
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED",
"expirationDate": "2026-12-31T23:59:59.000Z",
"attributes": {
"offerTitle": "25% Off Winter Collection",
"promoCode": "WINTER25"
}
},
"display": {
"title": "Coupon Redeemed",
"subtitle": "Apply 25% discount — Pass is now voided",
"color": "success"
}
}
Rechazo de escaneos duplicados (ALREADY_VOIDED)
Si el cliente intenta escanear el mismo pase de nuevo en otra caja —o si una segunda persona presenta una captura de pantalla reenviada del código de barras—, PassStatusRule detecta que el pase ya está en estado VOIDED y detiene inmediatamente la ejecución:
{
"decision": "ALREADY_VOIDED",
"status": "REJECTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{
"rule": "PassStatusRule",
"passed": false,
"reasonCode": "PASS_VOIDED_AFTER_SCAN"
}
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED"
},
"display": {
"title": "Already Redeemed",
"subtitle": "This voucher was already used and is void.",
"color": "error"
}
}
Actualización silenciosa en Wallet y atenuación visual
Inmediatamente después de confirmar la transición al estado VOIDED:
-
1
Apple Wallet (
.pkpass): Passinstance firma un paquete de pase actualizado con"voided": trueenpass.jsonusando el Certificado Pass Type de la plantilla (bundleId=passTypeIdentifierde Apple) y envía una notificación push silenciosa vía APNs. iOS desatura (atenúa en gris) automáticamente la apariencia del pase e invalida el código de barras en Apple Wallet. -
2
Google Wallet: Passinstance invoca la API REST de Google Wallet para actualizar el campo
statedel objeto del pase aCOMPLETED/EXPIRED, eliminándolo de las sugerencias activas en pantalla de bloqueo y mostrando un banner de estado canjeado.
Los administradores y workers backend también pueden anular manualmente cupones individuales o lotes fuera del flujo de escaneo mediante POST /api/v1/passes/voiding/:id/void (request payload) o POST /api/v1/passes/voiding/batch-void (request payload) con un valor tipado de VoidingReason.
Canje en terminal POS de retail (POST /v1/pos/redeem)
Los sistemas integrados de punto de venta (POS) en retail ejecutan canjes directos de vales de un solo uso mediante POS Redemption API (POST /v1/pos/redeem y POST /v1/pos/scan — excluidos del prefijo global /api/v1):
Campo (request payload) | Tipo | Descripción |
|---|---|---|
idempotencyKey | string (obligatorio, máx. 255) | Clave única de idempotencia (recomendado: tenantId:terminalId:clientTxRef). |
passRef | string (obligatorio, máx. 500) | Valor de código de barras escaneado, token de descarga, serialNumber, o externalId / passPublicId. |
operation | PosOperation (obligatorio) | Enumeración de Passinstance database: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID o CUSTOM. Use VOID o DISCOUNT para cupones de un solo uso. |
terminalId | string (UUID opcional) | UUID del POS terminal registrado (debe coincidir con el terminal de la credencial si está vinculado). |
externalTerminalRef | string (opcional) | Código externo de caja registradora si no se utiliza el UUID de terminal de Passinstance. |
amount / currency | number / string | Importe opcional del descuento o de la transacción y código de moneda ISO-4217 (por ejemplo, EUR). |
clientTxRef | string (opcional) | Referencia del recibo o cesta del POS para conciliación de auditoría. |
metadata | object (opcional) | Contexto opaco de cesta, cajero o tienda registrado en PosTransaction. |
Tras confirmar POST /v1/pos/redeem, la respuesta incluye walletPropagation (PosWalletPropagationStatus: QUEUED o SKIPPED) confirmando la propagación de notificaciones push hacia Apple Wallet y Google Wallet.
Para conocer buenas prácticas en el diseño de campañas, consulte Cupones y vales y Modos de escaneo y reglas de validación.
