Contrat de la Gateway caisse — v0 (provisoire, pour le simulateur)

Projet Site Maison Crosnier · 21 juillet 2026

La Gateway est l'interface unique entre le site et la caisse. Le site ne parle jamais directement à la caisse : il passe par la Gateway, qui expose d'abord un simulateur, puis l'API réelle de la caisse, sans réécriture côté site (ADR-019). Ce contrat définit les opérations et les formats de données. Les parties dépendant de l'API réelle (non encore connue) sont marquées [provisoire] ; les parties que le site maîtrise entièrement sont [stable].

Format retenu : REST / JSON (neutre, exploitable directement pour le développement). Les identifiants, dates IS 8601 avec fuseau, montants en euros.

1. Sens Caisse → Site — alimentation du catalogue (lecture)

1.1 `GET /catalogue` — structure du catalogue [provisoire]

Renvoie les familles (avec leur politique de commande) et les produits.

{
  "familles": [
    { "id": "pain",         "libelle": "Pain",         "politiqueCommande": { "type": "veille", "heureLimite": "10:00", "retraitAuPlusTot": "J+1" } },
    { "id": "viennoiserie", "libelle": "Viennoiserie", "politiqueCommande": { "type": "veille", "heureLimite": "12:00", "retraitAuPlusTot": "J+1", "retraitAvant": "09:00" } },
    { "id": "patisserie",   "libelle": "Pâtisserie",   "politiqueCommande": { "type": "delai", "delaiMinutes": 180, "retraitAuPlusTot": "J+0" } },
    { "id": "snacking",     "libelle": "Snacking",     "politiqueCommande": { "type": "delai", "delaiMinutes": 180, "retraitAuPlusTot": "J+0" } }
  ],
  "produits": [
    {
      "id": "caisse-ref-123",
      "familleId": "pain",
      "libelle": "Baguette tradition",
      "prix": 1.30,
      "declinaisons": [],
      "options": [],
      "actif": true
    }
  ]
}

Notes :

La politique de commande (heures limites) est ici fournie par la caisse — décision « probablement caisse » (§8). Si l'API réelle ne l'expose pas, ce bloc bascule en configuration côté site, sans changer le reste du contrat.
La modélisation fine (déclinaison, option, formule, groupe de choix) est volontairement laissée minimale : elle sera alignée sur l'API réelle (§4 du doc de synthèse). Le simulateur peut se contenter de produit + famille + prix + quelques déclinaisons pour tester le tunnel.
Le champ prix est le prix de référence caisse. Les promotions sont appliquées côté site (ADR-020) et ne transitent pas par la Gateway.
Pas de champ de stock : la caisse n'expose aucun stock (pas de gestion de stock automatique).

1.2 Rafraîchissement

La lecture du catalogue est déclenchée manuellement par l'admin (ADR-014) puis mise en cache côté site. La Gateway n'a pas besoin de mécanisme de push temps réel en V1.

2. Sens Site → Caisse — transmission en production (écriture)

2.1 `POST /commandes` — transmettre une commande payée [stable]

Envoyée une fois la commande validée et payée. C'est le format que le site maîtrise entièrement.

{
  "commandeId": "site-8f3a…",              // idempotence : rejouer le même id ne crée pas de doublon
  "pointDeRetraitId": "boutique-1",
  "creneau": { "debut": "2026-07-22T08:30:00+02:00", "dureeMinutes": 30 },
  "client": { "nom": "…", "email": "…", "telephone": "…" },
  "lignes": [
    { "produitId": "caisse-ref-123", "declinaisonId": null, "options": [], "quantite": 2, "prixUnitaire": 1.30 }
  ],
  "montantTotal": 2.60,
  "paiement": { "statut": "paye", "prestataire": "payplug", "reference": "pp_xxx" },
  "creeLe": "2026-07-21T16:05:00+02:00"
}

Réponse : { "accepte": true, "referenceCaisse": "…" } ou { "accepte": false, "raison": "…" }.

2.2 `POST /commandes/{commandeId}/annulation` — informer d'une annulation [stable]

Utilisé lorsqu'une commande annulée selon le barème (§9) doit être signalée à la production. Corps : { "motif": "annulation_client" }.

2.3 Avoir utilisable en boutique [baseline : AUCUNE intégration caisse]

Décision retenue (ADR-021) : on part du principe que la caisse ne remonte rien au site. L'usage physique d'un avoir passe donc par une édition auto-décrémentante côté site, sans aucun échange Gateway :

le site génère un justificatif présentable (code en code-barres / QR / code) ;
au moment de l'édition, le site décrémente le solde (par défaut la totalité → edite_boutique) et affiche l'avertissement « en éditant cet avoir vous n'y aurez plus accès depuis le site » ;
la boutique honore le justificatif par son propre moyen ; le contrôle anti-réutilisation est côté boutique (code unique marqué « utilisé »).

Aucune opération Gateway n'est requise pour cela → pas de dépendance à la caisse.

Évolutions optionnelles (uniquement si la caisse sait dialoguer, non nécessaires en V1) :

Caisse gère les bons : POST /avoirs (Site → Caisse) à la création.
Caisse valide en temps réel : GET /avoirs/{code} + POST /avoirs/{code}/imputation (Caisse → Site) à l'encaissement.

Le format du code (EAN-13, QR, alphanumérique) reste à aligner sur ce que la boutique/caisse sait scanner.

3. Ce que la Gateway NE fait PAS en V1

Pas de lecture de stock (pas de gestion de stock automatique).
Pas de remontée de statut de production (« commande prête » n'existe pas — §11).
Pas de paiement : le paiement se fait côté site via PayPlug, pas via la caisse.
Pas de gestion des promotions (côté site).

4. Le simulateur (cible de développement)

Le simulateur expose exactement les mêmes opérations que l'API réelle visée, pour permettre la bascule sans réécriture. Il doit :

servir un jeu de données catalogue + familles/délais factices (plusieurs familles, quelques produits par famille) ;
accepter et journaliser les POST /commandes (vérifier le tunnel de bout en bout) ;
permettre de rejouer les cas limites : heure limite dépassée, panier mixte (pain + pâtisserie), produit actif:false, créneau hors horaires ;
idéalement, permettre de figer « l'heure courante » pour tester les cutoffs de façon déterministe.

5. Coutures à verrouiller avec l'API réelle (questions d'intégration)

Clé d'identification produit : format et stabilité de produitId (base de l'appariement caisse ↔︎ fiche site enrichie).
Délais par famille : la caisse les expose-t-elle ? Sinon, configuration côté site.
Sens de transmission des commandes : le site pousse (POST) vers la caisse, ou la caisse tire (pull/polling) les commandes ? — à confirmer selon l'API.
Structure fine du catalogue : déclinaison / option / formule / groupe de choix, à aligner sur l'API réelle.
Gestion des erreurs : idempotence, rejeu, délais/retries, comportement si la caisse est indisponible au moment du POST.
Avoir en boutique : réglé sans couture par l'édition auto-décrémentante (ADR-021). Seul reste à caler le format du code scannable (EAN-13 / QR / alphanumérique) selon ce que la boutique sait lire. Les scénarios A/B (caisse maître ou validante) ne sont que des évolutions optionnelles.