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

# Gestion des statuts

> Appliquez des transitions de statut idempotentes et bidirectionnelles depuis un POS connecté.

Un POS connecté met à jour une commande Chataigne avec :

```http theme={null}
PUT /v1/locations/{location_id}/orders/{order_id}/status
Idempotency-Key: pos-transition-0189
Content-Type: application/json

{
  "status": "accepted",
  "reason": "Acceptée par la cuisine"
}
```

`Idempotency-Key` est obligatoire. Réutiliser une clé avec le même body retourne la réponse initiale ; la réutiliser avec un autre body est rejeté. Générez une clé durable pour chaque transition voulue et conservez-la jusqu’à la fin de la requête.

## Cycle de vie canonique

Les valeurs canoniques actuelles sont :

* `received`
* `accepted`
* `in_preparation`
* `awaiting_shipment`
* `awaiting_collection`
* `in_delivery`
* `completed`
* `rejected`
* `cancelled`
* `delivery_failed`

`received` est créé par Chataigne et ne peut pas être envoyé comme cible. Les états terminé, rejeté, annulé et échec de livraison sont terminaux. `awaiting_collection` n’est pas valide pour une livraison ; `awaiting_shipment` n’est pas valide pour une collecte. Une transition hors du cycle autorisé est rejetée.

<Info>
  Envoyer le statut actuel de la commande est une opération sans effet qui réussit. Elle
  n’incrémente pas `status_version` et n’émet pas de doublon d’événement de statut.
</Info>

## Mises à jour bidirectionnelles

Les changements peuvent provenir du POS, des opérateurs Chataigne, d’une automatisation planifiée, du parcours de commande ou d’un fournisseur de livraison. Chaque transition acceptée passe par la même machine d’état, devient le statut canonique et incrémente `status_version`.

Utilisez `status_version` pour écarter les anciens webhooks. La livraison est au moins une fois et peut survenir dans le désordre après des retries. Un payload dont la version est inférieure ou égale à la plus haute version déjà traitée pour cette commande peut être acquitté puis ignoré.

Lorsqu’une intégration POS ou un receiver API soumet un statut, Chataigne applique la première transition valide qui atteint la base de données. Un writer concurrent ayant observé la version précédente reçoit `409 order_status_conflict` ; il doit relire la commande avant de décider de réessayer. Les événements `order.status.updated` acceptés sont livrés au receiver primaire et aux observateurs abonnés, y compris lorsque leur source est un POS synchrone.

## Gestion des conflits

| Réponse | Signification                                        | Action                                                                  |
| ------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |
| `200`   | Transition appliquée, rejouée ou statut déjà atteint | Conserver la commande et la version retournées                          |
| `400`   | Body malformé ou transition invalide                 | Corriger le statut cible                                                |
| `404`   | Commande absente ou hors du périmètre autorisé       | Réconcilier l’identifiant et le périmètre                               |
| `409`   | Conflit d’idempotence ou changement concurrent       | Récupérer la commande et décider selon son statut et sa version actuels |

Une réponse webhook `2xx` confirme uniquement la réception. Si votre POS ne peut pas accepter une commande, acquittez le webhook, puis envoyez `rejected` via l’endpoint de statut avec une clé d’idempotence durable et une raison optionnelle.