Envoyer des événements
Votre application raconte ce qui change par une file d'envoi : chaque changement devient une
ligne, et un processus poste les lignes par lots à POST /api/v1/channel/events.
Un événement décrit l'objet tel qu'il est maintenant : order.upserted porte la commande
entière, quelle que soit la transition qui l'a causée. Renvoyer un événement est
sans danger, et un événement perdu se rattrape au suivant. Deux événements font exception parce
qu'ils sont des faits à part entière : loyalty.recorded (une ligne de points ne change plus) et
order.refunded (de l'argent rendu).
Le lot
{
"events": [
{
"eventId": "019a3b1e-7c2d-7f3a-9b1e-2d4c6e8f0a12",
"type": "stock.changed",
"occurredAt": "2026-10-30T14:02:11.482913+01:00",
"payload": { "productId": "NOZA-CEND0210", "quantity": 17 }
}
]
}
- 100 événements et 1 Mo au plus par lot.
occurredAtest l'instant où le fait était vrai, avec son fuseau.eventIdest un UUID neuf à chaque émission. Ne le réutilisez que pour réessayer ce même envoi, avec le même contenu. Un identifiant tiré du contenu ferait passer pour un doublon un client revenu à son ancienne adresse.
Le verdict
La réponse rend un verdict par événement, dans l'ordre du lot :
{
"results": [
{ "eventId": "019a3b1e-…", "status": "processed" },
{ "eventId": "019a3b1f-…", "status": "shadowed" },
{ "eventId": "019a3b20-…", "status": "rejected",
"errors": [{ "path": "payload.priceCents", "code": "not_an_integer", "message": "12.5 is not an integer amount of cents." }] }
],
"hubs": { "catalog": "live", "stock": "live", "loyalty": "shadow" }
}
| Verdict | Sens | Votre application |
|---|---|---|
processed | appliqué | terminé |
ignored | valide, rien à faire ; note dit pourquoi (« Aucun article lié ») | terminé |
failed | valide, Kult Lab a échoué à l'appliquer ; il le rejouera depuis son journal | terminé : c'est à nous de corriger |
duplicate | cet eventId a déjà été reçu | terminé |
shadowed | valide et journalisé, sa partie est en observation | terminé |
stale | une lecture de stock plus ancienne que celle que Kult Lab tient | terminé |
queued | une lecture de stock arrivée pendant qu'un stock.set de ce produit attend sa réponse : gardée, appliquée ensuite | terminé |
rejected | invalide et non enregistré | met la ligne de côté et alerte ; le même eventId peut repartir une fois corrigé |
Un warnings[] peut accompagner n'importe quel verdict. Seul rejected demande une action de votre
part : tous les autres verdicts retirent la ligne de votre file.
Pas d'écho
Une écriture faite chez vous à la demande de Kult Lab (une commande) reçoit sa réponse et ne produit pas d'événement. Votre code d'envoi a donc besoin d'un drapeau autour de l'écriture d'une commande, pour ne pas raconter ce que Kult Lab vient de vous demander.