Panoramica
Coupon promozionali e voucher monouso richiedono una validazione atomica rigorosa affinché un pass non possa mai essere riscattato due volte presso casse diverse o condiviso tramite screenshot statici. Associando un modello di coupon a una ScannerConfiguration impostata su VOIDED_AFTER_SCAN scan mode, Passinstance convalida il codice a barre, porta il pass allo stato VOIDED, blocca i tentativi di riutilizzo e attiva immediatamente un aggiornamento silenzioso del Wallet per oscurare (rendere grigio) il pass sul dispositivo del cliente.
Importante: Includa sempre una chiave di idempotenza quando si inviano riscatti dai terminali POS (header
x-idempotency-keysuPOST /api/v1/scansoppureidempotencyKeyinrequest payloadsuPOST /v1/pos/redeem). Se un terminale riprova dopo un timeout di rete, Passinstance restituisce la ricevuta di accettazione originale invece di generare un falso erroreALREADY_VOIDEDal cassiere.
Architettura del riscatto monouso
Prima scansione: riscatto atomico (POST /api/v1/scans)
Quando un cassiere scansiona un coupon attivo alla cassa, lo scanner invia il payload del codice a barre a POST /api/v1/scans autenticato con x-scanner-key:
Richiesta 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
}
}
Risposta HTTP (200 OK — Accettato e annullato)
{
"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"
}
}
Rifiuto delle scansioni duplicate (ALREADY_VOIDED)
Se il cliente prova a scansionare nuovamente lo stesso pass presso un'altra cassa — oppure se una seconda persona presenta uno screenshot inoltrato del codice a barre — PassStatusRule rileva che il pass è già VOIDED e interrompe immediatamente l'esecuzione:
{
"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 silenziosa al Wallet e oscuramento visivo
Subito dopo il commit della transizione di stato VOIDED:
-
1
Apple Wallet (
.pkpass): Passinstance firma un bundle del pass aggiornato con"voided": trueinpass.jsone il Pass Type Certificate del modello (bundleId= ApplepassTypeIdentifier), poi invia una notifica push silenziosa APNs. iOS desatura automaticamente (rende grigio) il fronte del pass e invalida il codice a barre in Apple Wallet. -
2
Google Wallet: Passinstance richiama la REST API di Google Wallet per aggiornare lo stato
statedell'oggetto pass aCOMPLETED/EXPIRED, rimuovendolo dai suggerimenti attivi sulla schermata di blocco e mostrando un banner di stato riscattato.
Gli amministratori e i worker backend possono anche annullare manualmente singoli coupon o batch al di fuori di un flusso di scansione tramite POST /api/v1/passes/voiding/:id/void (request payload) o POST /api/v1/passes/voiding/batch-void (request payload) indicando un VoidingReason tipizzato.
Riscatto da terminale POS retail (POST /v1/pos/redeem)
I sistemi point-of-sale retail integrati eseguono riscatti diretti di voucher monouso tramite POS Redemption API (POST /v1/pos/redeem e POST /v1/pos/scan — esclusi dal prefisso globale /api/v1):
Campo (request payload) | Tipo | Descrizione |
|---|---|---|
idempotencyKey | string (obbligatorio, max 255) | Chiave di idempotenza univoca (consigliata: tenantId:terminalId:clientTxRef). |
passRef | string (obbligatorio, max 500) | Valore del codice a barre scansionato, token di download, serialNumber oppure externalId / passPublicId. |
operation | PosOperation (obbligatorio) | Enum Passinstance database: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID o CUSTOM. Utilizzi VOID o DISCOUNT per coupon monouso. |
terminalId | string (UUID opzionale) | UUID del POS terminal registrato (deve corrispondere al terminale della credenziale se vincolato). |
externalTerminalRef | string (opzionale) | Codice esterno della cassa se non si utilizza l'UUID del terminale Passinstance. |
amount / currency | number / string | Importo opzionale di sconto o transazione e codice valuta ISO-4217 (es. EUR). |
clientTxRef | string (opzionale) | Riferimento scontrino POS o transazione carrello per la riconciliazione di audit. |
metadata | object (opzionale) | Contesto opaco di carrello, cassiere o punto vendita registrato in PosTransaction. |
Dopo il commit di POST /v1/pos/redeem, la risposta include walletPropagation (PosWalletPropagationStatus: QUEUED o SKIPPED) a conferma dell'accodamento degli aggiornamenti push verso Apple Wallet e Google Wallet.
Per le best practice di progettazione delle campagne, consulti Coupon e voucher e Modalità di scansione e regole di validazione.
