Skip to content
Guia da Central de Ajuda
4 min de leituraVerificado 2026-11-16

Cupões e vales promocionais

Lance ofertas de utilização única ou por tempo limitado com validação por leitura e expiração após resgate.

Neste guia

Visão geral

Os cupões e vales em carteira digital convivem com os cartões de pagamento no ecrã bloqueado do smartphone do cliente, gerando taxas de resgate significativamente mais elevadas do que códigos de desconto por e-mail ou vales em papel. A Passinstance oferece proteção criptográfica, verificação antifraude de utilização única e anulação do cartão em tempo real no momento do resgate ao balcão.

Arquitetura no backend e mapeamento de tipos de passe

No backend da Passinstance, os programas de cupões são mapeados para as primitivas oficiais de cupão da Apple Wallet e Google Wallet:

  • Tipo de Passe (pass type): coupon (utiliza o layout nativo de cupão da Apple com um selo visual de desconto em destaque).
  • Modelo Demo de Catálogo: promotional-coupon (disponível durante a integração).
  • Modo de Validação Predefinido: VOIDED_AFTER_SCAN scan mode.
  • Principais Restrições de Domínio:

- limitToOneActivePerPass: true: Restringe as ligações inteligentes de download a um único dispositivo, impedindo a partilha da ligação de desconto em grupos. - expirationDate: Carimbo temporal ISO 8601 W3C que despoleta automaticamente notificações nativas de expiração no ecrã bloqueado. - addSecurityAnimation: true: Apresenta uma moldura holográfica dinâmica à volta dos códigos de barras 2D para evitar a utilização fraudulenta de capturas de ecrã estáticas.

Resgate e execução antifraude

O fluxo de resgate ao balcão garante integridade estrita de utilização única através de transações atómicas na base de dados em Pass Mechanics Engine:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
RESGATE E ANULAÇÃO DE CUPÃO
ATORES DE SISTEMA PARTICIPANTES
P1 Passe na Carteira Cliente
P2 Scanner / Terminal POS
P3 API Principal Passinstance
ETAPA 1 PEDIDO / AÇÃO Apresentar QR Code
›
(PI-CPN-849201)
ETAPA 2 PEDIDO / AÇÃO POST/api/v1/scans
›
Header: x-scanner-key
›
Body: {scannedBarcodeVal}
ETAPA 3 PEDIDO / AÇÃO Verificar status === ACTIVE
ETAPA 4 PEDIDO / AÇÃO Verificar expirationDate >= now()
ETAPA 5 PEDIDO / AÇÃO Atualização Atómica:
›
status = VOIDED,
›
oidedAt = now()
ETAPA 6 RESPOSTA 200 OK
ETAPA 7 PEDIDO / AÇÃO Push APNs e Google PATCH
›
{ decision: "SUCCESS",
›
(Atualização silenciosa)
ETAPA 8 RESPOSTA Cartão Acinzentado e Anulado == status: "ACCEPTED" }

Prevenção contra fraude por captura de ecrã e repetição

Quando um operador lê o código de barras do cupão:

  1. 1
    O scanner envia um pedido para POST /api/v1/scans contendo scannedBarcodeValue e a chave secreta do scanner x-scanner-key.
  2. 2
    O servidor confirma que o estado do passe é ACTIVE e que a data/hora atual é anterior a expirationDate.
  3. 3
    Se for válido, a base de dados transita atomicamente o estado do passe para VOIDED, atribui voidReason: "SCANNED_AT_CHECKOUT" e regista a transação de leitura.
  4. 4
    Se um operador ou utilizador mal-intencionado ler novamente o mesmo código de barras do passe, o motor de validação rejeita a transação de imediato com o código de decisão ALREADY_VOIDED e a mensagem de erro PASS_VOIDED_AFTER_SCAN.
  5. 5
    Em simultâneo, a Passinstance coloca em fila uma notificação push em segundo plano para a Apple APNs e Google Wallet. O passe no telemóvel do cliente fica imediatamente acinzentado com a indicação visível "Resgatado", impedindo a reutilização noutra caixa.

DTOs concretos de pedido e resposta de leitura

Os sistemas de ponto de venda, terminais scanner e checkouts de e-commerce interagem com o endpoint de validação:

Pedido HTTP

POST /api/v1/scans
Cabeçalhos
x-scanner-key sk_live_counter_register_04
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-849201",
  "operatorId": "emp_sarah_m"
}

Resposta HTTP (200 OK)

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "passSnapshot": {
    "id": "pass_cpn_849201",
    "templateId": "tmpl_coupon_7712",
    "serialNumber": "PI-CPN-849201",
    "status": "VOIDED",
    "attributes": {
      "discount": "25% OFF",
      "terms": "Valid on purchases over €50"
    }
  }
}

Salvaguardas para distribuição de campanhas

Ao distribuir cupões através de páginas públicas PassFlow, criação via API ou campanhas por SMS:

  • Expiração do download (enableDownloadUntil): Defina uma data/hora estrita ("YYYY-MM-DD HH:mm" ou carimbo temporal ISO em request payload / configuração do modelo) após a qual as ligações de download não reclamadas devolvem HTTP 410 Gone.
  • Proteção por PIN de acesso: Proteja ligações promocionais de elevado valor com um PIN de acesso (?pin= ou X-Wallet-Experience-Pin) entregue por SMS ou recibo de compra.
  • Correlação CRM e e-commerce (externalId): Envie um externalId (ex.: order_88412_cpn) em POST /api/v1/passes ou /api/v1/passes/upsert-by-external-id para que os resgates de vales de utilização única possam ser reconciliados diretamente no seu sistema de encomendas.
  • Vinculação da ligação a um único dispositivo: Ative limitToOneActivePerPass para que a ligação serializada de cada cliente fique bloqueada ao primeiro dispositivo registado, evitando a circulação em grupos públicos.

Importante: VOIDED_AFTER_SCAN scan mode anula o passe imediatamente após uma leitura válida, enquanto INVALIDATE_AFTER_SCAN scan mode define o estado como INACTIVE / REDEEMED. Verifique sempre qual o ScanMode adequado aos seus requisitos contabilísticos e de apresentação na carteira.

Saiba mais na nossa Visão geral de Cupões e Vales.

Documentação de produto e API relacionada

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.