Recevoir des commandes
Kult Lab lit et écrit chez vous par des commandes. Votre application expose une seule adresse,
déclarée au bonjour dans commandsUrl, et y répond avec un switch sur le type.
La requête
POST {commandsUrl}
Authorization: Bearer <clé de Kult Lab>
X-KultLab-Timestamp: 1793459000
X-KultLab-Signature: sha256=…
{ "commandId": "0b8e…", "type": "stock.set", "createdAt": "2026-10-30T14:02:11.482+00:00", "payload": { … } }
Vérifiez la signature avant tout : une
commande mal signée reçoit un 401 et ne fait rien.
La réponse
En cinq secondes, signée comme une requête, sous l'une de ces trois formes :
{ "ok": true, "result": { … } }
{ "ok": false, "error": "not_found", "message": "No such variant.", "details": { … } }
{ "ok": true, "status": "accepted" }
resultsuit la forme de la commande : une réponse qui ne la suit pas fait échouer la commande eninvalid_result, visible au journal.acceptedveut dire que la réponse viendra plus tard, surPOST /api/v1/channel/commands/{commandId}/result. Une page d'export ne peut pas l'utiliser.- Un type que vous ne connaissez pas reçoit
not_supported. Un champ inconnu dans une commande s'ignore.
Les refus
Une liste fermée, chacun traduit en français pour le commerçant :
error | Sens |
|---|---|
not_found | l'objet n'existe pas chez vous |
not_tracked | l'article existe mais son stock n'est pas suivi |
quantity_moved | la quantité a changé depuis la lecture de Kult Lab (stock.set) |
insufficient | le solde de points ne suffit pas |
email_taken | un autre client porte déjà cet e-mail |
not_supported | votre application ne fait pas cela |
busy | réessayez plus tard |
Une commande, une seule écriture
Le même commandId reçoit la même réponse, sans seconde écriture. Kult Lab renvoie une commande
restée sans réponse toutes les dix minutes : gardez la réponse de chaque commande qui écrit pendant
sept jours, celle d'un essai à blanc comprise, et rendez-la telle quelle si le même commandId
revient.
Sans adresse publique
Une application sans commandsUrl relève ses commandes par GET /api/v1/channel/commands et y
répond sur /commands/{commandId}/result. La relève fonctionne, mais les gestes du commerçant qui
attendent une réponse immédiate (la fiche d'un produit, les parcours d'export) restent lents, et les
vérifications ne vont pas au-delà de la connexion. Préférez une adresse publique.