Flux e-commerce

Le site marchand utilise la même API native que la caisse. Les différences tiennent au canal et au moment de la validation.

Correspondances

Notion caisse	En e-commerce
storeCode	magasin « web » déclaré dans le workspace (par exemple WEB)
posId	identifiant du site ou de l’application (SHOP, APP-IOS)
ticketNumber	numéro de commande
channel	web, app ou marketplace
carte	web_account (compte client du site) ou email
externalRef	identifiant du panier

Parcours recommandé

1. Panier : à chaque modification, POST /v1/transactions/simulate. Le résultat sert à afficher les remises et les points à gagner. Rien n’est réservé.
2. Code promo saisi : ajoutez-le dans coupons[] (source: typed) et resimulez ; les codes refusés sont dans couponsRejected avec leur raison (expiré, déjà utilisé…), à afficher à l’internaute.
3. Validation de la commande (paiement accepté) : POST /v1/transactions/commit (évaluation et validation en un appel), avec un Idempotency-Key égal au numéro de commande. En cas de nouvelle tentative réseau, le même résultat est renvoyé.
4. Annulation / retour : POST /v1/transactions/{id}/cancel dans la fenêtre d’annulation, sinon refund.

Si le paiement est asynchrone (3-D Secure, virement), utilisez evaluate au passage en paiement puis commit à la confirmation : le coupon présenté reste réservé pendant ce temps et ne peut pas être utilisé ailleurs.

Frais et lignes non remisables

Marquez la livraison et les frais avec le drapeau fee, les cartes cadeaux avec gift_card : ils sont exclus du montant éligible. Exemple : ecommerce-panier.

Afficher les avantages sur le compte client

POST /v1/customers/lookup avec l’identifiant web_account et include: ["balances", "offers", "coupons"] renvoie les soldes, les offres disponibles (résumé marketing, nombre d’utilisations restantes) et les coupons du client.

Sécurité

La clé d’API ne doit jamais être exposée dans le navigateur ou l’application mobile : appelez le moteur depuis votre serveur (back-end du site). Restreignez la clé au magasin WEB et aux portées nécessaires.

Connecteurs prêts à l’emploi

Les connecteurs Shopify, PrestaShop et Magento sont prévus dans une version ultérieure. En attendant, l’intégration se fait par l’API ci-dessus.