Coupons

Un coupon est un droit nominatif ou anonyme à utiliser lors d’un prochain achat : « 5 € offerts dès 30 € », « -20 % sur le rayon frais », « un café offert ». Remizo gère l’émission, la vérification, la consommation et l’expiration.

Modèles de coupons

Un modèle définit :

• le format du code : EAN-13 (lisible par toutes les douchettes), QR code, ou code court à saisir ;
• la validité par défaut : fixe (du 1er au 31 décembre) ou glissante (30 jours à partir de l’émission, avec délai de départ éventuel) ;
• le design pour le rendu image ou PDF, avec des variables ({{customer.firstName}}, valeur faciale, date d’expiration, code-barres).

L’éditeur de modèles du studio affiche un aperçu PNG ou PDF à chaque modification.

Émettre un coupon

Deux façons :

1. Par une offre : l’action « émettre un coupon » (coupon_issue) crée un coupon au commit du ticket, rattaché au client identifié (ou anonyme, imprimé sur le ticket). L’offre peut indiquer l’offre que le coupon débloquera (linkedOfferId).
2. Par une campagne : génération en masse (par lots de 10 000), ou import d’une liste de codes existants.

Rendu (option par offre)

Par défaut, le coupon est un code seul. En option, il peut être rendu en image PNG ou en PDF depuis son modèle. Le rendu se fait en arrière-plan pour ne pas ralentir la caisse :

• le moteur renvoie immédiatement le code et un lien sécurisé ;
• ce lien répond « en cours » (202) tant que le rendu n’est pas prêt, puis sert le fichier ;
• après expiration ou annulation du coupon, il répond 410 ;
• le lien est valable 90 jours par défaut (coupons.renderLinkTtlDays).

Utiliser un coupon

Le code est présenté en caisse (scanné, saisi, ou poussé par l’application). Deux usages possibles dans les offres :

• déclencheur coupon : l’offre ne s’évalue que si le coupon est présenté, et le consomme si elle s’applique ;
• critère « coupon présenté » : condition supplémentaire, sans consommation.

Le moteur vérifie l’état, la validité et, si demandé, que le coupon appartient bien au client identifié. Les codes refusés sont renvoyés avec leur raison : inconnu, expiré, pas encore valide, déjà utilisé, réservé sur un autre ticket, annulé, n’appartient pas au client, aucune offre correspondante.

Cycle de vie

disponible ──évaluation──▶ réservé ──commit──▶ utilisé
   │  ▲                       │
   │  └──annulation du ticket─┘
   ├──▶ expiré ──prolongation──▶ disponible
   └──▶ annulé

• Un coupon est réservé dès l’évaluation d’un ticket en attente, pour qu’il ne puisse pas servir deux fois en même temps.
• Il passe utilisé au commit, ou redevient disponible si le ticket est annulé.
• La tâche planifiée coupons.expire fait passer les coupons échus à expiré ; une prolongation les rend de nouveau disponibles.
• Chaque changement d’état est enregistré dans l’historique du coupon (jamais effacé).

Hors ticket

L’API permet aussi de vérifier un code (POST /v1/coupons/check) et de le consommer hors ticket (POST /v1/coupons/redeem), par exemple pour un service en magasin.

Exemples : émission, code promo.