Skip to content
Guida del Centro assistenza
3 min di letturaVerificato 2026-11-16

Coupon e buoni sconto

Lancia promozioni monouso o a tempo con convalida tramite scansione e scadenza dopo il riscatto.

In questa guida

Panoramica

I coupon e i buoni sconto digitali vivono accanto alle carte di pagamento nella schermata di blocco dello smartphone del cliente, generando tassi di riscatto nettamente superiori rispetto ai codici sconto via e-mail o ai buoni cartacei. Passinstance offre protezione crittografica, verifica antifrode monouso e annullamento in tempo reale della tessera al momento del riscatto in cassa.

Architettura backend e mappatura del tipo di pass

Nel backend di Passinstance, i programmi coupon si mappano sulle primitive ufficiali dedicate ai coupon di Apple Wallet e Google Wallet:

  • Tipo di pass (pass type): coupon (utilizza il layout coupon nativo di Apple con un badge visivo di sconto ben visibile).
  • Modello demo a catalogo: promotional-coupon (disponibile durante l'onboarding).
  • Modalità di validazione predefinita: VOIDED_AFTER_SCAN scan mode.
  • Vincoli di dominio principali:

- limitToOneActivePerPass: true: Limita gli smart link di download a un solo dispositivo, impedendo la condivisione del link di sconto in gruppi pubblici. - expirationDate: Timestamp W3C ISO 8601 che attiva automaticamente le notifiche native di scadenza sulla schermata di blocco. - addSecurityAnimation: true: Visualizza un bordo olografico dinamico attorno ai codici a barre 2D per impedire l'utilizzo fraudolento di screenshot statici.

Riscatto ed esecuzione antifrode

Il flusso di riscatto in cassa garantisce una rigorosa integrità monouso attraverso transazioni atomiche su database in Pass Mechanics Engine:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RISCATTO E ANNULLAMENTO COUPON
ATTORI DI SISTEMA COINVOLTI
P1 Pass Wallet cliente
P2 Scanner / Terminale POS
P3 Passinstance Core API
FASE 1 RICHIESTA / AZIONE Presenta QR codice
›
(PI-CPN-849201)
FASE 2 RICHIESTA / AZIONE POST/api/v1/scans
›
Header: x-scanner-key
›
Body: {scannedBarcodeVal}
FASE 3 RICHIESTA / AZIONE Verifica status === ACTIVE
FASE 4 RICHIESTA / AZIONE Controlla expirationDate >= now()
FASE 5 RICHIESTA / AZIONE Aggiornamento atomico:
›
status = VOIDED,
›
oidedAt = now()
FASE 6 RISPOSTA 200 OK
FASE 7 RICHIESTA / AZIONE Push APNs & PATCH Google
›
{ decision: "SUCCESS",
›
(Aggiornamento silenzioso)
FASE 8 RISPOSTA Tessera oscurata e annullata = status: "ACCEPTED" }

Prevenzione delle frodi da screenshot e replay

Quando l'operatore di cassa scansiona il codice a barre del coupon:

  1. 1
    Lo scanner invia una richiesta a POST /api/v1/scans contenente scannedBarcodeValue e la chiave segreta x-scanner-key.
  2. 2
    Il server verifica che lo stato del pass sia ACTIVE e che il timestamp corrente preceda expirationDate.
  3. 3
    Se valido, il database porta atomicamente lo stato del pass a VOIDED, assegna voidReason: "SCANNED_AT_CHECKOUT" e registra la transazione di scansione.
  4. 4
    Se un operatore o un utente malintenzionato scansiona nuovamente lo stesso codice a barre, il motore di validazione rifiuta immediatamente la transazione con codice decisione ALREADY_VOIDED e messaggio di errore PASS_VOIDED_AFTER_SCAN.
  5. 5
    Contestualmente, Passinstance accoda una notifica push in background verso Apple APNs e Google Wallet. La tessera sullo smartphone del cliente si oscura immediatamente mostrando l'etichetta "Redeemed" (o stato riscattato), impedendone il riutilizzo a un'altra cassa.

DTO concreti di richiesta e risposta della scansione

Sistemi POS, terminali scanner e casse e-commerce interagiscono con l'endpoint di validazione nel seguente formato:

Richiesta HTTP

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

Risposta 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"
    }
  }
}

Misure di sicurezza per la distribuzione delle campagne

Nella distribuzione di coupon tramite pagine PassFlow pubbliche, creazione via API o campagne SMS:

  • Scadenza del download (enableDownloadUntil): Imposti data e ora rigorose ("YYYY-MM-DD HH:mm" o timestamp ISO su request payload / configurazione del modello) oltre le quali i link di download non ancora riscattati restituiscono HTTP 410 Gone.
  • Protezione con PIN di accesso: Protegga i link promozionali ad alto valore con un PIN di accesso (?pin= oppure X-Wallet-Experience-Pin) consegnato via SMS o ricevuta d'acquisto.
  • Correlazione CRM ed e-commerce (externalId): Passi un externalId (es. order_88412_cpn) su POST /api/v1/passes o /api/v1/passes/upsert-by-external-id così da riconciliare con precisione i riscatti dei buoni monouso nel sistema ordini.
  • Associazione del link a un solo dispositivo: Abiliti limitToOneActivePerPass in modo che il link serializzato di ogni cliente si blocchi sul primo dispositivo registrato anziché circolare nei gruppi pubblici.

Importante: VOIDED_AFTER_SCAN scan mode annulla immediatamente il pass dopo una scansione valida, mentre INVALIDATE_AFTER_SCAN scan mode imposta lo stato su INACTIVE / REDEEMED. Verifichi sempre quale ScanMode corrisponde alle proprie esigenze contabili e di visualizzazione nel Wallet.

Approfondisca nella Panoramica Coupon e buoni sconto.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.