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:
Prevenção contra fraude por captura de ecrã e repetição
Quando um operador lê o código de barras do cupão:
-
1
O scanner envia um pedido para
POST /api/v1/scanscontendoscannedBarcodeValuee a chave secreta do scannerx-scanner-key. -
2
O servidor confirma que o estado do passe é
ACTIVEe que a data/hora atual é anterior aexpirationDate. -
3
Se for válido, a base de dados transita atomicamente o estado do passe para
VOIDED, atribuivoidReason: "SCANNED_AT_CHECKOUT"e regista a transação de leitura. -
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_VOIDEDe a mensagem de erroPASS_VOIDED_AFTER_SCAN. -
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
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
Resposta HTTP (200 OK)
{
"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 emrequest 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=ouX-Wallet-Experience-Pin) entregue por SMS ou recibo de compra. -
Correlação CRM e e-commerce (
externalId): Envie umexternalId(ex.:order_88412_cpn) emPOST /api/v1/passesou/api/v1/passes/upsert-by-external-idpara 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
limitToOneActivePerPasspara 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 modeanula o passe imediatamente após uma leitura válida, enquantoINVALIDATE_AFTER_SCAN scan modedefine o estado comoINACTIVE/REDEEMED. Verifique sempre qual oScanModeadequado aos seus requisitos contabilísticos e de apresentação na carteira.
Saiba mais na nossa Visão geral de Cupões e Vales.
