Vue d’ensemble des commandes

L’API Commandes permet à un POS ou à un middleware connecté de récupérer les commandes créées par Chataigne. Chataigne reste le système de référence : la V1 n’expose aucun POST /orders et n’importe aucune commande créée à l’extérieur.

Endpoints

Besoin	Opération
Lister les commandes d’un établissement	`GET /v1/locations/{location_id}/orders`
Récupérer une commande d’un établissement	`GET /v1/locations/{location_id}/orders/{order_id}`
Lister les commandes d’une organisation	`GET /v1/organizations/{organization_id}/orders`
Récupérer une commande d’une organisation	`GET /v1/organizations/{organization_id}/orders/{order_id}`
Mettre à jour un statut depuis le POS	`PUT /v1/locations/{location_id}/orders/{order_id}/status`

La lecture exige orders.read. La mise à jour d’un statut exige orders.write. Chaque requête reste limitée aux établissements et organisations autorisés pour la clé API.

Pagination et réconciliation

Les listes utilisent une pagination déterministe par curseur, ordonnée selon les clés immuables (created_at DESC, id DESC). Définissez limit entre 1 et 100 et utilisez soit starting_after, soit ending_before, jamais les deux. Les filtres comprennent status, service_type, location_id sur les listes d’organisation, ainsi que les bornes temporelles created_after, created_before, updated_after et updated_before. Pour effectuer une réconciliation après l’indisponibilité d’un consommateur ou un incident webhook, capturez un horodatage de borne haute avant la première requête. Envoyez le point de reprise précédent dans updated_after et la même borne haute dans updated_before sur chaque page, puis continuez jusqu’à ce que has_more vaille false. Une fois ce parcours borné terminé, avancez le point de reprise jusqu’à la borne haute. Les bornes temporelles étant exclusives, conservez un chevauchement d’une milliseconde pour la prochaine valeur updated_after et dédupliquez avec id et status_version. Ce protocole empêche les mises à jour effectuées pendant le parcours de franchir son curseur ; elles seront renvoyées au parcours suivant. Ne supposez pas que l’ordre de livraison des webhooks correspond à l’ordre des mises à jour.

Identité de la commande

id est l’identifiant stable Chataigne utilisé dans les chemins API et la déduplication des webhooks.
short_id est le numéro lisible affiché au personnel du restaurant.
location_id identifie le restaurant propriétaire de la commande.
status_version augmente de un à chaque transition canonique.

Articles et références externes

Les produits et les formules sont réunis dans le même tableau items. Lisez type avant les champs spécifiques à l’article :

{
  "items": [
    {
      "type": "product",
      "id": "burger-classic",
      "name": "Burger classique",
      "quantity": 2,
      "unit_price": { "amount": 12.5, "currency": "EUR" },
      "modifier_groups": []
    },
    {
      "type": "bundle",
      "id": "menu-midi",
      "name": "Menu du midi",
      "quantity": 1,
      "unit_price": { "amount": 18, "currency": "EUR" },
      "lines": []
    }
  ]
}

Pour un produit, id est sa référence SKU externe. Une formule, une ligne de formule, un groupe de modifiers et un modifier utilisent leurs références externes persistées. Chataigne ne remplace jamais une référence externe manquante par un identifiant interne de base de données.

Un établissement ne peut pas activer un receiver POS API tant que son catalogue actif ne possède pas de référence externe pour chaque produit vendable, modifier, groupe de modifiers, formule et ligne de formule. Si une commande historique ne possède malgré tout pas une référence, sa livraison vers le receiver primaire est bloquée. Les endpoints observateurs reçoivent toujours le snapshot public avec null à la place de cette référence ; Chataigne n’expose jamais d’identifiant interne.

Montants et frais

Toutes les valeurs monétaires utilisent { "amount": nombre, "currency": chaîne }. Le tableau public charges contient uniquement les frais delivery et service, avec exactement la même forme :

{
  "charges": [
    { "type": "delivery", "amount": { "amount": 3.5, "currency": "EUR" } },
    { "type": "service", "amount": { "amount": 1, "currency": "EUR" } }
  ]
}

Les métadonnées fournisseur, identifiants internes de frais et de SKU, identifiants de paiement et champs POS privés ne sont jamais exposés. total reste le montant canonique facturé pour la commande et peut donc inclure des frais fournisseur ou privés volontairement absents du tableau public charges.

Horaires de préparation et de livraison

expected_pickup_time indique quand la commande doit quitter le restaurant ou être retirée.
expected_delivery_time indique l’heure d’arrivée promise au client pour une livraison.
expected_time est la promesse client : heure de livraison pour une livraison, heure de retrait pour une collecte.

Une livraison peut donc avoir une heure de passage du coursier et une heure d’arrivée client ultérieure. Pour une collecte, expected_delivery_time vaut null.

​Endpoints

​Pagination et réconciliation

​Identité de la commande

​Articles et références externes

​Montants et frais

​Horaires de préparation et de livraison