Requêtes

URL de base#

Chaque route se trouve sous https://api.flavoso.com/v1. HTTPS uniquement. La version figure dans le chemin (v1), la date de version dans l'en-tête Flavoso-Api-Version.

En-têtes#

curl -i -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID" \
  -H "User-Agent: ExamplePOS/4.2 (support@example.com)"

JSON#

Les corps sont des objets JSON, les réponses aussi. Les noms de champs sont en anglais et en snake_case. Un corps peut peser jusqu'à 64 Ko, et jusqu'à 2 Mo pour la synchronisation de la carte (PUT /menu), comptés en octets ; au-delà, la réponse est 413 payload_too_large. Un champ inconnu de l'opération ou un paramètre de requête inconnu renvoie 400 invalid_request avec param : une faute de frappe ne passe donc pas inaperçue.

Chaque objet indique son type dans object, une liste est { "object": "list", "data": [ … ] }. Un champ sans valeur vaut null.

Montants et TVA#

Les montants sont des entiers dans la plus petite unité de la devise, donc en centimes : 1290 correspond à 12,90 €. La devise figure à côté (currency, ISO 4217) ou sur l'établissement. Jamais de nombres décimaux.

Les taux de TVA sont exprimés en points de base : 700 correspond à 7 %, 1900 à 19 %. Les prix sur Flavoso sont des prix TTC ; une commande porte en plus sa TVA ventilée par taux (tax.lines). Si l'établissement n'a enregistré aucun taux pour une part, cette ligne porte rate_bps: null, et net et tax valent null ; le tax_rate_bps d'une ligne de commande peut aussi valoir null. Comptabilisez une telle part comme à clarifier, et non comme exonérée de TVA.

Dates et heures#

• Les horodatages suivent la norme ISO 8601, en UTC avec Z : 2026-10-04T17:44:59.942Z. Envoyez-les avec un fuseau, Z ou un décalage comme +02:00 ; sans fuseau, la réponse est 400. Dans les paramètres de requête, écrivez + sous la forme %2B (ou utilisez Z). Les réponses sont toujours en UTC.
• Les jours calendaires au format YYYY-MM-DD dans l'heure locale de l'établissement, par exemple pour les jours particuliers et les rapports.
• Les heures au format HH:MM dans l'heure locale de l'établissement, par exemple pour les horaires d'ouverture. weekday 0 correspond au lundi, 6 au dimanche.
• Le fuseau horaire de l'établissement (IANA, par exemple Europe/Berlin) figure dans GET /me et GET /store.

Identifiants#

Les identifiants sont des UUID et ne changent jamais. Exceptions : les événements (evt_…) et les requêtes (req_…). Une commande a en plus un court code que voit le client, par exemple 3271CD ; il n'est pas destiné au rapprochement des données.

Vos propres identifiants : external_id#

Avec external_id, vous attachez votre propre identifiant à un objet : le numéro d'article de votre caisse à un plat, le numéro de ticket à une commande. Vous retrouvez ensuite l'objet grâce à lui, sans table de correspondance à tenir.

• 1 à 100 caractères, sans caractère de contrôle, sans espace au début ni à la fin. Comptés en caractères, pas en octets.
• Unique par application, établissement et type : deux plats de votre application dans le même établissement ne peuvent pas porter le même, un plat et une commande le peuvent.
• Seule votre application voit ses identifiants, dans les réponses des routes. Pour toute autre application, le champ vaut null, et dans les événements il vaut toujours null : une même enveloppe part vers tous les destinataires.
• Disponible sur les catégories, les plats, les groupes d'options, les options et les commandes.
• Défini via PUT /menu, lors de la création et de la modification, et pour les commandes avec POST /orders/{id}/acknowledge.
• Filtrable avec ?external_id= sur les listes.
• S'il est déjà pris, Flavoso répond 409 external_id_taken.
• Si l'objet est supprimé, son identifiant disparaît avec lui.

# Find the dish your POS knows as ART-1001
curl "https://api.flavoso.com/v1/menu/products?external_id=ART-1001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find the order you booked as receipt R-2026-000123
curl "https://api.flavoso.com/v1/orders?external_id=R-2026-000123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

livemode#

livemode figure dans GET /me et dans chaque événement : false pour un établissement de test, true pour tout établissement réel. Il n'existe pour cela ni adresse distincte ni clés distinctes.

Versions#

Au sein de v1, seuls des ajouts rétrocompatibles sont publiés : nouveaux champs, nouvelles routes, nouveaux codes d'erreur, nouveaux événements. Tout changement incompatible (un champ disparaît ou change de signification) n'arrive qu'avec une nouvelle version, et l'ancienne continue de fonctionner au moins six mois.

Flavoso-Api-Version dans chaque réponse et api_version dans chaque événement indiquent la date de version, actuellement 2026-10-08. Les changements et leur date figurent dans le Journal des modifications.

Pas de CORS#

L'API fonctionne de serveur à serveur. Les routes qui renvoient des données n'envoient pas d'en-tête Access-Control-Allow-Origin, donc aucun navigateur ne laisse une page tierce lire leur réponse. Un jeton placé dans un navigateur serait un jeton rendu public. Seuls openapi.json, postman.json et les métadonnées OAuth sont accessibles sans authentification.

Méthodes#

Un chemin inconnu sous /v1 répond 404 not_found dans le même format d'erreur.