Aperçu
Les coupons promotionnels et bons d'achat à usage unique exigent une validation strictement atomique afin qu'une carte ne puisse jamais être utilisée deux fois sur des caisses distinctes ni réemployée via une simple capture d'écran. En associant un modèle de coupon à une ScannerConfiguration paramétrée sur VOIDED_AFTER_SCAN scan mode, Passinstance valide le code-barres, fait passer le passe au statut VOIDED, bloque toute tentative de rejeu et déclenche immédiatement une mise à jour silencieuse qui grise la carte sur le téléphone du client.
Important : Transmettez systématiquement une clé d'idempotence lors de la validation depuis un terminal de caisse (en-tête
x-idempotency-keysurPOST /api/v1/scans, ou champidempotencyKeydansrequest payloadsurPOST /v1/pos/redeem). Si une caisse réessaie après un délai réseau dépassé, Passinstance renvoie le reçu d'acceptation initial au lieu d'afficher une fausse erreurALREADY_VOIDEDau vendeur.
Architecture d'encaissement à usage unique
Premier scan : encaissement atomique (POST /api/v1/scans)
Lorsqu'un caissier scanne un coupon actif lors du paiement, le lecteur soumet la charge utile du code-barres vers POST /api/v1/scans authentifié par x-scanner-key :
Requête 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
}
}
Réponse HTTP (200 OK — Accepté & invalidé)
{
"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"
}
}
Rejet d'un scan dupliqué (ALREADY_VOIDED)
Si le client tente de présenter à nouveau le même passe à une autre caisse — ou si une autre personne présente une capture d'écran transférée — PassStatusRule détecte que le passe est déjà au statut VOIDED et bloque immédiatement l'opération :
{
"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 silencieux Wallet & grisage visuel
Immédiatement après la validation de la transition vers VOIDED :
-
1
Apple Wallet (
.pkpass) : Passinstance signe une nouvelle archive avec"voided": truedanspass.jsongrâce au certificat Pass Type du modèle (bundleId=passTypeIdentifierApple), puis envoie une notification APNs silencieuse. iOS désature (grise) automatiquement l'apparence de la carte et désactive le code-barres dans Cartes. -
2
Google Wallet : Passinstance appelle l'API REST Google Wallet pour passer l'attribut
statede l'objet àCOMPLETED/EXPIRED, retirant la carte des suggestions actives et affichant un bandeau d'utilisation effectuée.
Les administrateurs et traitements serveur peuvent également invalider manuellement des coupons ou lots hors contexte de scan via POST /api/v1/passes/voiding/:id/void (request payload) ou POST /api/v1/passes/voiding/batch-void (request payload) avec un motif typé VoidingReason.
Validation depuis une caisse POS (POST /v1/pos/redeem)
Les systèmes de point de vente intégrés exécutent directement l'encaissement des bons à usage unique via POS Redemption API (POST /v1/pos/redeem et POST /v1/pos/scan — montés hors du préfixe global /api/v1) :
Champ (request payload) | Type | Description |
|---|---|---|
idempotencyKey | string (obligatoire, max 255) | Clé d'idempotence unique (recommandé : tenantId:terminalId:clientTxRef). |
passRef | string (obligatoire, max 500) | Valeur scannée, jeton de téléchargement, serialNumber, externalId ou passPublicId. |
operation | PosOperation (obligatoire) | Énumération Passinstance database : DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID ou CUSTOM. Utilisez VOID ou DISCOUNT pour un coupon à usage unique. |
terminalId | string (UUID optionnel) | UUID du POS terminal enregistré (doit correspondre au terminal lié à l'identifiant d'accès). |
externalTerminalRef | string (optionnel) | Code de caisse externe si vous n'utilisez pas l'UUID terminal Passinstance. |
amount / currency | number / string | Montant optionnel de la remise ou de la transaction et code devise ISO 4217 (ex. EUR). |
clientTxRef | string (optionnel) | Référence du ticket de caisse ou panier POS pour rapprochement d'audit. |
metadata | object (optionnel) | Contexte libre panier, caissier ou magasin consigné dans PosTransaction. |
Après validation de POST /v1/pos/redeem, la réponse inclut walletPropagation (PosWalletPropagationStatus : QUEUED ou SKIPPED) confirmant la mise en file des actualisations Apple Wallet et Google Wallet.
Pour concevoir vos campagnes promotionnelles, consultez Coupons & bons d'achat et Modes de scan & règles de validation.
