Aller au contenu principal
Sur cette page▾

Une boutique ou un ERP sur mesure est un cas où il n’existe pas de plug-in prêt à l’emploi : votre développeur connecte donc lui-même le configurateur au panier. La règle qui sous-tend tout ici tient en une phrase : un prix envoyé par le navigateur ne doit jamais devenir un prix de panier. Votre serveur le vérifie d’abord auprès de CutOptim.

CutOptim n’encaisse aucun paiement et n’héberge aucune boutique ; le panier, le paiement et le règlement restent chez vous. Il n’y a pas encore de SDK. La référence de l’API du configurateur liste chaque route, chaque code d’erreur et chaque limite, avec un document OpenAPI 3.1 ; cette page, la page des commandes et le code de référence guident l’intégration pas à pas.

Deux clés

  • La clé publiable (publishable key) figure dans votre page pour l’intégration. Elle ne peut faire que ce que fait un acheteur, et uniquement depuis les domaines que vous avez listés pour elle.
  • La clé secrète (secret key) est destinée à votre serveur et n’est jamais placée dans une page. Elle est envoyée sous la forme Authorization: Bearer <key> au service, par défaut https://cfg.cutoptim.com. Envoyez toujours Content-Type: application/json sur un POST.

Étape 1 : vérifier le devis avant le panier

Quand le client commande, votre page reçoit un événement cutoptim:order avec un jeton de devis. Envoyez le jeton à votre serveur, et depuis celui-ci :

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

La réponse est 200 avec {"valid": true, "redeemed": false, "claims": {...}} ou {"valid": false, "reason": "..."}. Un refus reste un 200 : lisez donc valid. Traitez un délai dépassé, un 401, un 500 ou un corps illisible comme non vérifié et refusez la ligne. Comparez ensuite les revendications à votre ligne de panier : le tenant est le vôtre, la devise est celle du panier, l’expiration est dans le futur, et le hachage du devis est égal au hachage du devis que votre page a affiché. Le code de référence inclut la fonction qui calcule ce hachage.

Un contrôle local de la forme du jeton, du tenant et de l’expiration coûte moins cher mais ne peut pas prouver la signature, car la clé de signature n’est pas communiquée. Utilisez-le seulement comme pré-contrôle.

Étape 2 : contrôler la commande

Vérifier le devis montre que la promesse de prix est authentique. Cela ne montre pas de quelle commande parle le navigateur. Avant de stocker ou d’exécuter à partir d’un identifiant de commande, récupérez-la sur votre serveur avec GET /cfg/v1/orders/{id} et votre clé secrète. Elle renvoie le hachage du plan, le hachage du devis, le statut, la devise et les trois totaux en unités mineures, et aucune donnée personnelle. Comparez-les à ce que vous avez vérifié.

Étape 3 : recevoir le webhook

Configurez un webhook comme décrit sur la page des commandes. Votre récepteur :

  1. lit le corps brut avant de l’analyser ;
  2. lit l’en-tête CutOptim-Signature, t=<unix seconds>,v1=<hex> (il peut y avoir deux valeurs v1 pendant la rotation d’un secret) ;
  3. recalcule HMAC-SHA256(secret, "<t>.<raw body>"), compare en temps constant, et refuse un horodatage éloigné de plus de cinq minutes environ ;
  4. réserve l’identifiant d’événement issu de CutOptim-Event-Id avant tout traitement, et ignore un identifiant déjà traité ;
  5. ignore les types d’événements qu’il ne connaît pas et répond 2xx, afin que l’expéditeur ne réessaie pas inutilement.

Vous obtenez le secret du récepteur avec POST /cfg/v1/admin/webhooks/{id}/secret et votre clé secrète. Gardez les secrets dans votre environnement, jamais dans une page, un dépôt ou un journal.

Code de référence

Deux petits exemples sans dépendances illustrent les trois étapes. C’est du code à lire et à copier, pas un service hébergé :

Leurs secrets sont des valeurs fictives. Le stockage de doublons en mémoire dans les exemples est un substitut : en production, conservez les identifiants d’événements traités dans votre base de données et réservez un identifiant dans la même transaction que celle qui enregistre la commande.

Les mêmes étapes, avec les requêtes et les réponses exactes, figurent dans la référence : Boutique sur mesure ou ERP.

Rotation des clés

Une clé ou un secret de webhook peut être renouvelé avec un chevauchement, de sorte que l’ancien continue de fonctionner pendant une durée définie le temps que vous déployiez le nouveau. Pendant une rotation de webhook, une livraison porte deux signatures v1 pendant sept jours ; en accepter une seule vous permet de basculer sans interruption. Les boutons de console pour la rotation avec chevauchement ne sont pas encore construits ; la console peut créer et révoquer des clés.

Autres façons de recevoir des commandes

Pour WooCommerce, utilisez le plug-in. Si vous n’avez besoin que de plans de coupe dans votre propre logiciel, sans écran client intégré, c’est l’Engine API.

FAQ

Ai-je besoin d’un plug-in pour utiliser le configurateur avec ma propre boutique ?
Non. Le configurateur s’intègre avec un script et un élément, et votre serveur fait trois choses : vérifier le devis avant le panier, contrôler la commande à laquelle il appartient, et vérifier le webhook signé. Cette page les décrit et renvoie à du code de référence en Node et PHP. WooCommerce dispose d’un plug-in prêt à l’emploi ; aucune autre plateforme n’en a.
Comment mon serveur vérifie-t-il un prix ?
Il envoie le jeton de devis à POST /cfg/v1/quote/verify sur le service du configurateur avec votre clé secrète. La réponse indique si le devis est valide ou non, et s’il a déjà été consommé. Il compare ensuite les revendications du jeton à sa propre ligne de panier : tenant, devise, expiration et hachage du devis. Une vérification purement locale ne peut pas prouver la signature ; ne fixez donc jamais un prix sur cette seule base.
Vérifier un devis le consomme-t-il ?
Non. La vérification est en lecture seule. Seule la passation de la commande consomme le devis, une seule fois. Un devis valide peut revenir comme déjà consommé ; vérifiez donc les deux champs.
Comment savoir qu’un identifiant de commande venu du navigateur est bien la commande que j’ai vérifiée ?
Recherchez-la sur votre serveur : GET /cfg/v1/orders/{id} avec la clé secrète renvoie le hachage du plan, le hachage du devis, le statut et les totaux de cette commande, jamais de données personnelles. Comparez-les au devis vérifié. Sans cela, un devis vérifié bon marché pourrait être envoyé avec l’identifiant d’une autre commande.
Existe-t-il un SDK ou un document OpenAPI ?
Il n’y a ni SDK ni adaptateur hébergé, mais il existe une référence d’API : chaque route, chaque code d’erreur et chaque limite, avec un document OpenAPI 3.1 à l’adresse /configurator/openapi.json qu’un générateur de client peut lire. Les fichiers de référence sont de petits exemples sans dépendances en Node et PHP, que vous lisez et copiez. Python, Java et C# ne sont pas couverts ; la signature est un simple HMAC-SHA256, n’importe quel langage peut donc la calculer.
Quels événements du configurateur puis-je recevoir ?
order.created et order.status_changed. Les autres noms d’événements acceptés par la configuration, comme les événements de devis ou de projet, ne sont jamais envoyés. La livraison est au moins une fois ; conservez donc une trace des identifiants d’événements déjà traités.

Mis à jour: 19 octobre 2026