Dire bonjour
Le bonjour dit à Kult Lab qui vous êtes, ce que vous savez faire et où vous joindre. Il est idempotent : appelez-le à chaque déploiement et une fois par jour.
La requête
POST /api/v1/channel/hello
{
"protocol": 1,
"app": { "name": "HomieSeeds", "version": "2026.10.30-e0c09b9", "platform": "sylius 2.2" },
"kind": "shop",
"url": "https://homieseeds.com",
"commandsUrl": "https://homieseeds.com/api/kult-lab/commands",
"capabilities": ["catalog.read", "stock.read", "stock.write", "orders.read", "orders.history", "customers.read"],
"facts": {
"customerPurchases": false,
"customerLoyaltyBalance": false,
"mirrorableFields": ["name", "price", "description", "image", "active"],
"deltaExport": true
}
}
| Champ | Obligatoire | Sens |
|---|---|---|
protocol | oui | 1 |
app.name, app.version | oui | la version s'affiche au commerçant et date les alertes (« depuis la version … ») |
app.platform | non | la technologie, pour le support |
kind | oui | shop, till ou other |
url | non | l'adresse publique de l'application |
commandsUrl | non | l'adresse qui reçoit les commandes. Absente, votre application relève ses commandes elle-même |
capabilities | oui | ce que vous savez faire, voir la vue d'ensemble |
facts | selon les capacités | des faits sur votre plateforme, lus par Kult Lab au lieu de les supposer |
Les faits exigés
Un fait devient obligatoire dès qu'une capacité qui en dépend est déclarée. S'il manque, la réponse
est un 422 qui le nomme.
| Capacité | Faits exigés | Sens |
|---|---|---|
catalog.read | mirrorableFields | les champs d'un produit que Kult Lab peut recopier chez lui |
deltaExport | true si catalog.export sait ne rendre que ce qui a changé depuis since | |
customers.read | customerPurchases | true seulement si vous renvoyez le client à chaque commande : sinon ses totaux viennent du journal des ventes |
customerLoyaltyBalance | true si le client porte un solde de points | |
loyalty.read | pointValueCents | ce que vaut un point, en centimes ; il doit égaler celui du programme du commerce |
Un bonjour est une déclaration complète
Ce que le bonjour ne dit pas n'existe plus : une capacité retirée est retirée tout de suite, une
commandsUrl absente fait passer l'application en relève des commandes. Une capacité ajoutée passe
seule par la vérification, sans arrêter les parties déjà actives.
Un champ inconnu, une capacité inconnue, un mauvais type, ou une partie déclarée sans celle sur
laquelle elle repose (le stock sans le catalogue, la fidélité sans les clients) donnent un 422 avec
le chemin du champ, et le bonjour refusé ne change rien.
La réponse
{
"status": "connected",
"protocol": { "min": 1, "max": 1 },
"time": "2026-10-30T14:02:11.482+00:00",
"clockSkewSeconds": 0,
"capabilities": ["catalog.read"],
"hubs": {
"catalog": { "state": "live", "capabilities": ["catalog.read"] },
"stock": { "state": "shadow", "capabilities": [], "pending": ["stock.write"] }
},
"failingChecks": [
{ "hub": "stock", "check": "stock.reading", "status": "waiting", "message": "…" }
]
}
GET /api/v1/channel renvoie le même document sans rien déclarer : c'est la question « où en
suis-je ? » de votre script de déploiement.
| Champ | Sens |
|---|---|
capabilities | ce qui est en vigueur : déclaré, vérifié et dans une partie active |
hubs.<partie>.state | shadow (observation), verified, live |
clockSkewSeconds | l'avance de votre horloge sur la nôtre, en secondes |
failingChecks | chaque vérification qui échoue ou attend, et celles de la nuit |
hubs est toujours un objet, {} quand rien n'est déclaré.
Une adresse de commandes qui change
Un bonjour qui change l'hôte de commandsUrl est accepté, et le commerçant voit pendant une
semaine que l'adresse a changé. L'adresse doit être publique et en HTTPS.