Skip to content
Guia da Central de Ajuda · Resgates e transações
4 min de leituraVerificado 2026-11-16

Resgate de cupões e vales

Processe vales de uso único no ponto de venda, anule passes já usados automaticamente e evite duplicados.

Neste guia

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-key em POST /api/v1/scans, ou idempotencyKey em request payload em POST /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 erro ALREADY_VOIDED ao operador de caixa.

Arquitetura de Resgate de Utilização Única

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: RESGATE ATÓMICO DE CUPÕES E ANULAÇÃO NA CARTEIRA
ATORES DE SISTEMA PARTICIPANTES
P1 Dispositivo do Cliente
P2 Terminal Scanner / POS
P3 API Passinstance
ETAPA 1 PEDIDO / AÇÃO Apresenta Código Cupão
›
(PI-CPN-774109)
ETAPA 2 PEDIDO / AÇÃO POST/api/v1/scans
›
Header: x-scanner-key
›
Mode: VOIDED_AFTER_SCAN
ETAPA 3 PEDIDO / AÇÃO PassStatusRule (ACTIVE)
ETAPA 4 PEDIDO / AÇÃO ExpirationRule (< validUntil)
ETAPA 5 PEDIDO / AÇÃO Transação BD Atómica:
›
statusVOIDED
›
oidedAtnow()
ETAPA 6 RESPOSTA 200 OK
ETAPA 7 PEDIDO / AÇÃO Push APNs / Google
ETAPA 8 RESPOSTA Cartão Esbatido Carteira
›
(Apple voided: true .pkpass)
ETAPA 9 PEDIDO / AÇÃO Repetição / Captura Ecrã
ETAPA 10 PEDIDO / AÇÃO POST/api/v1/scans
ETAPA 11 RESPOSTA 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

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

POST /api/v1/scans
Cabeçalhos
x-scanner-key sk_live_pos_register_01
x-idempotency-key pos-tx-20261116-99481
Content-Type application/json
JSON
{
  "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)

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

JSON
{
  "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. 1
    Apple Wallet (.pkpass): A Passinstance assina um pacote de passe atualizado com "voided": true em pass.json e com o Pass Type Certificate do modelo (bundleId = passTypeIdentifier da 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. 2
    Google Wallet: A Passinstance invoca a API REST da Google Wallet para atualizar o state do objeto de passe para COMPLETED / 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)TipoDescrição
idempotencyKeystring (obrigatório, máx. 255)Chave de idempotência única (recomendado: tenantId:terminalId:clientTxRef).
passRefstring (obrigatório, máx. 500)Valor do código de barras lido, token de transferência, serialNumber, ou externalId / passPublicId.
operationPosOperation (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.
terminalIdstring (UUID opcional)UUID do POS terminal registado (tem de corresponder ao terminal da credencial se vinculada).
externalTerminalRefstring (opcional)Código externo de caixa caso não utilize o UUID do terminal Passinstance.
amount / currencynumber / stringMontante opcional do desconto ou transação e código de moeda ISO-4217 (ex. EUR).
clientTxRefstring (opcional)Referência do talão POS ou transação do cesto para reconciliação de auditoria.
metadataobject (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.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.