Visão geral
Os cupões e vales promocionais de utilização única exigem validação atómica estrita para que um passe nunca possa ser resgatado duas vezes em caixas diferentes nem partilhado através de capturas de ecrã estáticas. Ao emparelhar um modelo de cupão com uma ScannerConfiguration definida para VOIDED_AFTER_SCAN scan mode, a Passinstance valida o código de barras, transita o passe para VOIDED, bloqueia tentativas de repetição e despoleta uma atualização silenciosa imediata na carteira para esbater (grey out) o passe no dispositivo do cliente.
Importante: Inclua sempre uma chave de idempotência ao submeter resgates a partir de terminais POS (cabeçalho
x-idempotency-keyemPOST /api/v1/scans, ouidempotencyKeyemrequest payloademPOST /v1/pos/redeem). Se um terminal repetir o pedido devido a um timeout de rede, a Passinstance devolve o comprovativo de aceitação original em vez de apresentar um falso erroALREADY_VOIDEDao operador de caixa.
Arquitetura de Resgate de Utilização Única
Primeira Leitura: Resgate Atómico (POST /api/v1/scans)
Quando um operador de caixa lê um cupão ativo no pagamento, o scanner submete o payload do código de barras para POST /api/v1/scans autenticado por x-scanner-key:
Pedido 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
}
}
Resposta HTTP (200 OK — Aceite e 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"
}
}
Rejeição de Leituras Duplicadas (ALREADY_VOIDED)
Se o cliente tentar ler novamente o mesmo passe noutra caixa — ou se uma segunda pessoa apresentar uma captura de ecrã reencaminhada do código de barras — a PassStatusRule deteta que o passe já se encontra em VOIDED e interrompe imediatamente a execução:
{
"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"
}
}
Push Silencioso para Carteira e Desaturação Visual
Imediatamente após confirmar a transição para o estado VOIDED:
-
1
Apple Wallet (
.pkpass): A Passinstance assina um pacote de passe atualizado com"voided": trueempass.jsone com o Pass Type Certificate do modelo (bundleId=passTypeIdentifierda Apple), enviando depois uma notificação push APNs silenciosa. O iOS dessatura (esbate a cinzento) automaticamente a face do passe e invalida o código de barras na Apple Wallet. -
2
Google Wallet: A Passinstance invoca a API REST da Google Wallet para atualizar o
statedo objeto de passe paraCOMPLETED/EXPIRED, removendo-o das sugestões ativas no ecrã bloqueado e apresentando uma faixa de estado resgatado.
Administradores e workers de backend também podem anular manualmente cupões individuais ou lotes fora de um fluxo de leitura através de POST /api/v1/passes/voiding/:id/void (request payload) ou POST /api/v1/passes/voiding/batch-void (request payload) com um VoidingReason tipado.
Resgate em Terminal POS de Retalho (POST /v1/pos/redeem)
Os sistemas integrados de ponto de venda de retalho executam resgates diretos de vales de utilização única através de POS Redemption API (POST /v1/pos/redeem e POST /v1/pos/scan — excluídos do prefixo global /api/v1):
Campo (request payload) | Tipo | Descrição |
|---|---|---|
idempotencyKey | string (obrigatório, máx. 255) | Chave de idempotência única (recomendado: tenantId:terminalId:clientTxRef). |
passRef | string (obrigatório, máx. 500) | Valor do código de barras lido, token de transferência, serialNumber, ou externalId / passPublicId. |
operation | PosOperation (obrigatório) | Enum Passinstance database: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID ou CUSTOM. Utilize VOID ou DISCOUNT para cupões de utilização única. |
terminalId | string (UUID opcional) | UUID do POS terminal registado (tem de corresponder ao terminal da credencial se vinculada). |
externalTerminalRef | string (opcional) | Código externo de caixa caso não utilize o UUID do terminal Passinstance. |
amount / currency | number / string | Montante opcional do desconto ou transação e código de moeda ISO-4217 (ex. EUR). |
clientTxRef | string (opcional) | Referência do talão POS ou transação do cesto para reconciliação de auditoria. |
metadata | object (opcional) | Contexto opaco do cesto, operador de caixa ou loja registado em PosTransaction. |
Após confirmar POST /v1/pos/redeem, a resposta inclui walletPropagation (PosWalletPropagationStatus: QUEUED ou SKIPPED) confirmando a propagação push para a Apple Wallet e Google Wallet.
Para boas práticas de conceção de campanhas, consulte Cupões e Vales e Modos de Leitura e Regras de Validação.
