API FlavosoGuidesDéroulement des commandes

Déroulement des commandes

Le cycle de vie d'une commande, ses champs, ses lignes de TVA, ses modes de paiement et ses sources.

Le cycle de vie

pending

nouvelle, attend l'établissement

confirmed

acceptée

preparing

en préparation

ready

prête ; en livraison, prête pour le livreur

completed

retirée, servie ou livrée

cancelled annulée, depuis tout statut ouvert ; depuis pending, cela signifie refuser

Vers l'avant, on peut sauter des statuts (confirmed → ready) ; revenir en arrière est impossible.

Un établissement peut désactiver confirmed, preparing et ready ; accepter passe alors au statut suivant qu'il utilise. Les statuts qu'il utilise figurent dans GET /store sous order_statuses.

Les statuts

status	Signification	Comment y arriver
`pending`	Nouvelle, attend l'établissement.	La commande est créée.
`confirmed`	Acceptée.	`POST /orders/{id}/accept` (si l'établissement utilise `confirmed` ; sinon, accepter passe à son statut suivant)
`preparing`	En préparation.	`POST /orders/{id}/status` avec `preparing`
`ready`	Prête ; en livraison, prête pour le livreur.	`POST /orders/{id}/status` avec `ready`
`completed`	Retirée, servie ou livrée.	`POST /orders/{id}/status` avec `completed`
`cancelled`	Annulée ou refusée.	`POST /orders/{id}/reject` (seulement depuis `pending`) ou `POST /orders/{id}/cancel`

Faire avancer

Vers l'avant, on peut sauter des statuts, par exemple confirmed → ready. Revenir en arrière n'est pas possible : 409 invalid_transition.
Un établissement peut désactiver des statuts. Ceux qu'il utilise figurent dans GET /store sous order_statuses ; un statut désactivé répond 409 stage_not_used.
Si la commande est déjà au statut cible, elle est renvoyée inchangée avec 200. accept fait passer une commande pending au statut suivant utilisé par l'établissement (s'il a désactivé confirmed, preparing et ready, completed) ; une commande qui a déjà dépassé pending est renvoyée inchangée, une commande terminée ou annulée répond 409 invalid_transition.
Refuser et annuler acceptent un motif (reason, jusqu'à 200 caractères ; au-delà, 400) pour le journal de l'établissement ; le client ne le voit pas.
Chaque changement se déroule comme un clic dans le tableau de bord : le client reçoit son message, l'équipe sa notification, et le journal de l'établissement nomme votre application.

# Accept (pending → confirmed)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

# Advance: confirmed → preparing → ready → completed (skipping ahead is allowed)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "preparing"}'

# Reject an order that was not accepted yet; the reason goes to the audit log
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/reject \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Out of dough"}'

# Cancel from any open status
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Guest called to cancel"}'

Avec paiement sur place, la commande existe immédiatement. Avec paiement en ligne, seulement une fois le paiement confirmé : avant, elle ne figure dans aucune liste et ne déclenche aucun événement. order.created arrive exactement une fois par commande.

Les champs

Champ	Signification
`code`	Code court que voit le client, par exemple `3271CD`.
`type`	`pickup`, `delivery` ou `dine_in`.
`source`	Sa provenance, voir ci-dessous.
`requested_for`	Heure souhaitée d'une précommande ; `null` signifie dès que possible.
`amounts`	`subtotal`, `delivery_fee`, `service_fee`, `discount`, `tip`, `total`, tous en centimes.
`tax`	La TVA par taux, voir ci-dessous.
`payment`	`method`, `status`, `paid_at`.
`customer`	Le nom et, pour la vente à emporter et la livraison, le numéro de téléphone.
`delivery`	Pour la livraison, l'adresse.
`table`	À table : identifiant et libellé.
`note`	La note du client pour la cuisine. Les allergies y figurent souvent.
`items`	Lignes avec quantité, prix unitaire et prix de ligne, options (avec `id`, `group_id` et `group_name`) et le taux de TVA figé au moment de la commande (`tax_rate_bps`, `null` sans taux enregistré).
`external_id`, `acknowledged_at`	Identifiant et prise en charge par votre application, voir Intégration caisse. Toujours `null` dans les événements.

{
  "object": "order",
  "id": "cce01f52-5188-410f-9659-6ce26ba9b784",
  "code": "3271CD",
  "type": "delivery",
  "status": "pending",
  "source": "storefront",
  "created_at": "2026-10-04T17:44:59.942Z",
  "updated_at": "2026-10-04T17:45:10.118Z",
  "requested_for": null,
  "currency": "EUR",
  "amounts": {
    "subtotal": 2490,
    "delivery_fee": 250,
    "service_fee": 0,
    "discount": 0,
    "tip": 200,
    "total": 2940
  },
  "tax": {
    "included": true,
    "lines": [
      {
        "rate_bps": 700,
        "gross": 2421,
        "net": 2263,
        "tax": 158
      },
      {
        "rate_bps": 1900,
        "gross": 319,
        "net": 268,
        "tax": 51
      }
    ]
  },
  "payment": {
    "method": "online",
    "status": "paid",
    "paid_at": "2026-10-04T17:45:10.000Z"
  },
  "customer": {
    "name": "Alex",
    "phone": "+49 151 00000000"
  },
  "delivery": {
    "address": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin"
  },
  "table": null,
  "note": "Please ring twice",
  "external_id": null,
  "acknowledged_at": null,
  "items": [
    {
      "id": "e9c0ce66-7f7f-42cf-a4bf-7d66f87768c1",
      "product_id": "303b87c9-58a3-4644-9a8b-2841cc1f89d6",
      "name": "Pizza Margherita",
      "quantity": 2,
      "unit_price": 1100,
      "line_total": 2200,
      "tax_rate_bps": 700,
      "options": [
        {
          "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
          "name": "Extra cheese",
          "price_delta": 150,
          "group_id": "8e7d6c5b-4a39-4281-b0f9-e8d7c6b5a4f3",
          "group_name": "Extras"
        }
      ]
    },
    {
      "id": "0d1e2f3a-4b5c-4d6e-8f70-81a2b3c4d5e6",
      "product_id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
      "name": "Cola 0,33 l",
      "quantity": 1,
      "unit_price": 290,
      "line_total": 290,
      "tax_rate_bps": 1900,
      "options": []
    }
  ]
}

Lignes de TVA

tax ventile le montant TTC de la commande par taux de TVA : { "included": true, "lines": [{ "rate_bps", "gross", "net", "tax" }] }. Les lignes couvrent les lignes de commande, les frais de livraison et les frais de service, selon le même calcul que le ticket et l'export DATEV. La TVA est comprise dans le prix (included: true).

Dans l'exemple ci-dessus : pizza à 7 %, cola à 19 %, les frais de livraison répartis proportionnellement entre les deux. Le pourboire n'est pas du chiffre d'affaires et ne figure dans aucune ligne.

Si l'établissement n'a enregistré aucun taux pour une part, cette part figure dans une ligne avec rate_bps: null, et net et tax y valent null, pas 0. Comptabilisez-la comme à clarifier, et non comme exonérée de TVA.

Modes de paiement

payment.method	payment.status	Signification
`online`	`paid`	Payée en ligne. La commande n'existe qu'à partir de ce moment.
`on_site`	`open`	Paiement sur place, encore ouvert : espèces ou carte au retrait, à la livraison ou à table.
`online`	`open`	Jamais visible : une commande en ligne n'existe pour l'API qu'une fois payée. Flavoso n'enregistre pas les paiements sur place, `on_site` reste donc `open`.

Avec le paiement en ligne, l'argent va directement à l'établissement ; Flavoso n'est jamais le bénéficiaire du paiement. Le pourboire figure dans amounts.tip et est inclus dans total.

Sources

source	Provenance
`storefront`	La page de commande de l'établissement, y compris intégrée à son site web.
`table`	Le QR code à table.
`app`	L'application Flavoso pour les clients.

Données des clients

Une commande ne contient que ce qui est nécessaire pour la remettre : le nom, pour la vente à emporter et la livraison le numéro de téléphone, pour la livraison l'adresse. Jamais l'adresse e-mail, jamais le compte client. À table, le numéro de téléphone est omis lui aussi. Voir Protection des données.

Une question reste ouverte ? Écrivez à support@flavoso.com en indiquant l'identifiant de X-Request-Id. Il nous permet de retrouver votre requête dans le journal.