Commandes
Poussez les commandes de votre boutique pour que Humind mesure ce qu'il a apporté (quelles commandes ont suivi une conversation, quelles lignes ont été ajoutées au panier par l'assistant) et, sur PrestaShop, réponde à « où en est ma commande ? » dans le chat pour vos clients. Le module PrestaShop Humind fait tout cela pour vous ; cette page documente ce qu'il envoie. N'importe quel autre back-office peut pousser ses commandes de la même façon pour l'attribution ; le suivi de commande du chat et l'identité client ci-dessous ne sont servis que pour les boutiques PrestaShop (une autre plateforme garde l'API de suivi de commande personnalisée).
Les deux endpoints de cette page sont en écriture seule et demandent le scope orders:write. Il n'y a pas de GET : vous avez déjà vos commandes, et les résultats apparaissent de votre côté dans le dashboard (attribution) et dans le chat (suivi de commande).
Sur PrestaShop
Installez le module Humind et connectez-le : il pousse de lui-même chaque commande validée et chaque changement de statut, et sert l'endpoint d'identité client du widget. Rien à écrire.
Comment fonctionne l'attribution
Le widget de chat laisse des marqueurs sur la boutique pendant que le visiteur parle à l'assistant :
- sur Shopify, sous forme d'attributs de panier et de propriétés de ligne, lus par nos webhooks ;
- sur PrestaShop et toute autre plateforme, dans un cookie first-party nommé
humind_attribution, un objet JSON{ "v": "<id visiteur>", "t": "<id conversation>", "p": ["<produit>_<variante>", ...] }(30 jours,SameSite=Lax, chemin/).vettidentifient la conversation ;pliste les lignes de panier ajoutées par l'assistant, sous la forme<id_product>_<id_product_attribute>sur PrestaShop.
Quand une commande est validée, recopiez le cookie sur la commande que vous poussez : v et t deviennent les attributes de commande _humind_visitor et _humind_thread, et chaque ligne dont la clé figure dans p reçoit la propriété de ligne _humind_source: "humind". Humind rend ensuite son verdict exactement comme pour Shopify :
attribution.level | Signification |
|---|---|
direct | Au moins une ligne a été ajoutée au panier par l'assistant. |
recommended | Aucune ligne ne vient de l'assistant, mais la conversation a montré ou cité un produit de la commande. |
cart | Le visiteur a eu une conversation, et rien dans la commande n'en vient. |
null | Aucun marqueur Humind sur la commande. |
Le verdict est renvoyé à chaque push et visible dans le dashboard. Les valeurs du cookie viennent du navigateur, traitez-les comme déclaratives : ce sont des identifiants Humind pseudonymes, jamais des données client.
Pousser une commande
POST /orders enregistre une commande, ou la met à jour quand le même external_id a déjà été poussé. L'appel est idempotent par external_id : une relance après une erreur réseau est sans risque, et aucun header Idempotency-Key n'est nécessaire. Sur une commande déjà connue, un champ de statut ou de suivi laissé vide garde sa valeur stockée, pour qu'un push rejoué n'efface jamais un statut posé par PATCH, et un nouveau status remplace toujours status_label.
Scope requis : orders:write
| Champ | Requis | Type | Notes |
|---|---|---|---|
external_id | oui | chaîne ou entier, 128 max | L'id de la commande sur votre plateforme (id_order sur PrestaShop). La clé de l'upsert. |
name | non | chaîne, 64 max | Le numéro de commande tel que le client le connaît (reference sur PrestaShop). Utilisé par le chat pour retrouver une commande par son numéro. |
created_at | oui | ISO 8601 | Date de la commande. |
cancelled_at | non | ISO 8601 | Renseigné quand la commande est annulée. Les commandes annulées restent enregistrées et ne comptent pour rien. |
currency | non | ISO 4217 | EUR, USD... |
total_price | oui | nombre | Total payé, après remises, en unités majeures. |
subtotal_price | non | nombre | Avant frais de port et taxes, en unités majeures. |
test | non | booléen | Les commandes de test sont enregistrées et exclues de tous les chiffres. |
channel | non | chaîne, 64 max | Canal de vente (web, pos...). |
customer.external_id | non | chaîne ou entier, 128 max | L'id du client sur votre plateforme (id_customer). Nécessaire à la recherche de commandes du client connecté, voir Identité client. |
customer.email | non | L'email d'achat. Stocké uniquement sous forme de hash à clé, pour la recherche numéro de commande + email du chat. Jamais stocké en clair. | |
status | non | chaîne, 64 max | Statut de préparation. Utilisez une clé connue quand vous pouvez y rattacher la vôtre : unfulfilled, partially_fulfilled, fulfilled, delivered, ready_for_pickup, picked_up, voided ; le chat les traduit. Sinon envoyez votre propre clé et un status_label. |
status_label | non | chaîne, 128 max | Le statut tel que votre back-office le libelle, montré au client quand status n'est pas une clé connue. |
tracking_number | non | chaîne, 128 max | Numéro de suivi du colis. |
tracking_url | non | URL, 2048 max | Page de suivi du transporteur. |
attributes | non | objet ou liste [{ name, value }] | Clés/valeurs au niveau de la commande. Mettez-y _humind_visitor et _humind_thread, depuis le cookie. |
line_items | oui | tableau, 500 max | Voir ci-dessous. |
Chaque ligne :
| Champ | Requis | Type | Notes |
|---|---|---|---|
external_product_id | non | chaîne ou entier | L'id du produit, tel qu'envoyé dans la synchronisation du catalogue (id_product). Permet à Humind de rapprocher la ligne du catalogue et de dire si la conversation l'a recommandée. |
external_variant_id | non | chaîne ou entier | L'id de la variante, identique à la synchronisation du catalogue (product-<id> ou combination-<id> sur PrestaShop). |
quantity | oui | entier | |
price | non | nombre | Prix unitaire dans la devise de la commande, en unités majeures. |
title | non | chaîne | Titre du produit, montré sur la carte de commande dans le chat. Tronqué à 255 caractères. |
variant_title | non | chaîne | Tronqué à 255 caractères. |
sku | non | chaîne, 128 max | Référence marchand de la ligne. Acceptée, non stockée aujourd'hui. |
properties | non | objet ou liste [{ name, value }] | Clés/valeurs de ligne. Mettez-y _humind_source: "humind" quand la clé de la ligne figure dans le p du cookie. |
Les champs inconnus sont refusés avec validation_failed, pour qu'une faute de frappe dans une clé de marqueur ne passe jamais en silence. Une chaîne vide dans un champ texte facultatif (status_label, customer.email, tracking_number...) est lue comme « pas de valeur », jamais comme une erreur.
Requête
curl -X POST https://api.thehumind.com/public/v1/orders \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": 1042,
"name": "XKBKNABJK",
"created_at": "2026-11-03T08:15:00Z",
"currency": "EUR",
"total_price": 89.9,
"subtotal_price": 84.9,
"customer": { "external_id": 7, "email": "jane@example.com" },
"status": "unfulfilled",
"status_label": "Paiement accepté",
"attributes": { "_humind_visitor": "v_8f3a", "_humind_thread": "68a1c2d3e4f5a6b7c8d9e0f1" },
"line_items": [
{ "external_product_id": 11, "external_variant_id": "combination-111", "quantity": 1, "price": 49.9, "title": "Huile CBD", "variant_title": "10%" },
{ "external_product_id": 22, "external_variant_id": "product-22", "quantity": 2, "price": 20, "title": "Baume", "properties": { "_humind_source": "humind" } }
]
}'Réponse 201 Created (premier push) ou 200 OK (déjà connue)
{
"data": {
"id": "68a1c2d3e4f5a6b7c8d9e0f9",
"external_id": "1042",
"name": "XKBKNABJK",
"platform": "prestashop",
"store_id": "www.example.com",
"created_at": "2026-11-03T08:15:00.000Z",
"cancelled_at": null,
"test": false,
"currency": "EUR",
"total_price": 89.9,
"attribution": {
"level": "direct",
"sources": ["humind"],
"visitor_id": "v_8f3a",
"thread_id": "68a1c2d3e4f5a6b7c8d9e0f1"
},
"status": "unfulfilled",
"status_label": "Paiement accepté",
"tracking_number": null,
"tracking_url": null,
"ingested_via": "api",
"updated_at": "2026-11-03T08:15:02.000Z"
}
}platform vaut prestashop quand votre intégration catalogue est PrestaShop et custom sinon. store_id est l'hôte de votre boutique : le nom d'hôte de vitrine de votre company, sinon le domaine principal de vos domaines autorisés, sinon le premier ; avec external_id, il rend la commande unique entre vos boutiques.
Mettre à jour le statut d'une commande
PATCH /orders/api:{external_id} met à jour la préparation d'une commande déjà poussée : statut, libellé, suivi du colis, annulation. Le dernier écrit gagne, un champ omis garde sa valeur, un nouveau status sans status_label efface l'ancien libellé, et cancelled_at n'est jamais remis à zéro une fois renseigné. La commande doit avoir été poussée avant, sinon l'appel répond 404 not_found.
Scope requis : orders:write
| Champ | Type | Notes |
|---|---|---|
status | chaîne, 64 max | Mêmes clés que sur le push. |
status_label | chaîne, 128 max | |
tracking_number | chaîne, 128 max | |
tracking_url | URL, 2048 max | |
cancelled_at | ISO 8601 |
Au moins un champ est requis.
Requête
curl -X PATCH https://api.thehumind.com/public/v1/orders/api:1042 \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "fulfilled", "status_label": "Expédié", "tracking_number": "6A12345678901", "tracking_url": "https://www.laposte.fr/outils/suivre-vos-envois?code=6A12345678901" }'La réponse est le même objet que sur le push, avec les champs mis à jour.
Identité client
Une fois vos commandes poussées, le chat peut montrer à un client connecté ses propres commandes sans lui demander de numéro de commande ni d'email. Il faut pour cela une preuve que le visiteur est connecté en tant que tel client, et seul votre serveur peut la donner : le widget ne fait jamais confiance à un id client lu dans la page. Boutiques PrestaShop uniquement, via le module Humind.
Le déroulé :
- Le widget, sur une boutique dont l'intégration est PrestaShop, appelle le contrôleur d'identité du module (
index.php?fc=module&module=humind&controller=identitysous l'URL de base de la boutique) à l'ouverture du chat, avec le cookie de session de la boutique. - Le module vérifie la session PrestaShop. Si personne n'est connecté, il répond
204 No Content. Sinon il appellePOST /customer-identity/tokensavec votre clé API et l'id du client, et renvoie le jeton au navigateur sous la forme{ "token": "...", "expiresIn": 1800 }(l'API répondexpires_in, le module renomme). - Le widget envoie le jeton avec chaque message. L'assistant liste les commandes récentes du client (celles que vous avez poussées, avec leur statut courant) et peut se limiter à une seule par son numéro.
POST /customer-identity/tokens est réservé aux appels serveur à serveur. Une clé qui porte customers:identity ne doit jamais atteindre le navigateur : quiconque la détient pourrait se faire passer pour n'importe quel client de votre boutique dans le chat.
Scope requis : customers:identity
| Champ | Requis | Type | Notes |
|---|---|---|---|
customer_external_id | oui | chaîne ou entier, 64 max | L'id du client sur votre plateforme, celui que vous envoyez dans customer.external_id des commandes. |
email | non | Accepté pour compatibilité future, inutilisé aujourd'hui. |
Requête
curl -X POST https://api.thehumind.com/public/v1/customer-identity/tokens \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{ "customer_external_id": 7 }'Réponse 200 OK
{ "token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 1800 }Le jeton vit 30 minutes et nomme votre boutique et le client, rien d'autre. C'est un bearer lisible par n'importe quel script de la boutique, comme les pages de compte du client lui-même : ne le journalisez jamais et ne le persistez jamais. Le widget en redemande un quand il expire. Cet appel est compté dans le seau de rate limit reads, pour qu'une boutique active ne soit jamais freinée dessus par ses pushs de commandes.
Ce que montre le chat
La carte de commande montre le numéro, le statut (traduit quand c'est une clé connue, votre libellé sinon), le lien de suivi, les articles et une chronologie (commande passée, puis expédiée ou livrée quand le statut le dit, annulée le cas échéant). Elle ne montre jamais d'adresse ni d'email, parce que la commande poussée n'en contient pas.
Erreurs
| Statut | Code | Quand |
|---|---|---|
400 | validation_failed | Un champ manque, est malformé, est inconnu, ou le corps du PATCH est vide. error.details.issues liste les champs. |
403 | insufficient_scope | La clé n'a pas orders:write ou customers:identity. |
404 | not_found | PATCH sur une commande jamais poussée pour cette boutique. |
429 | rate_limited | Voir Rate limits. Les pushs de commandes utilisent le seau writes, les jetons d'identité le seau reads. |
Voir Erreurs pour l'enveloppe et les codes partagés.