> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d’ensemble des commandes

> Consultez les commandes Chataigne depuis un POS ou un middleware.

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 :

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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 :

```json theme={null}
{
  "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`.