Journal des modifications

Comment l'API évolue#

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 n'arrive qu'avec une nouvelle version, et l'ancienne continue de fonctionner au moins six mois. Flavoso-Api-Version et api_version indiquent la date de version.

8 octobre 2026 : finitions avant les premières caisses#

Avant la mise en service des premières caisses, nous avons resserré le contrat à quelques endroits. Certains points sont plus stricts qu'avant ; cela reste malgré tout dans v1, car aucune intégration n'était encore en service. Si vous avez développé sur une version antérieure, vérifiez les points suivants.

• Date de version : Flavoso-Api-Version et api_version des nouveaux événements indiquent désormais 2026-10-08. Les événements déjà livrés ou récupérés gardent 2026-10-04.
• Taille du corps : un corps plus grand que ce que l'opération accepte (64 Ko, 2 Mo pour PUT /menu, comptés en octets) reçoit 413 payload_too_large au lieu de 400 invalid_request.
• Tout élément inconnu est une erreur : un paramètre de requête ou un champ de corps inconnu renvoie 400 invalid_request avec param, sur toutes les opérations.
• Horodatages avec fuseau : updated_since, created_since, starts_from et les autres horodatages d'une requête, ainsi que until de POST /store/pause, doivent porter Z ou un décalage, sinon la réponse est 400. Un + non encodé dans les paramètres de requête est accepté devant le décalage.
• Les créations renvoient 201 : POST /menu/categories, /menu/products, /menu/option-groups, /menu/option-groups/{id}/options et POST /store/closures pour un nouveau jour (200 s'il en remplace un).
• Accepter : POST /orders/{id}/accept fait passer une commande pending au statut suivant utilisé par l'établissement (pas toujours confirmed) ; une commande qui a déjà dépassé pending est renvoyée inchangée avec 200 ; pour une commande terminée ou annulée, la réponse est 409 invalid_transition.
• Options des commandes : items[].options[] portent id, group_id et group_name (null pour les commandes plus anciennes).
• Carte : nouveau GET /menu/options ; la réponse de PUT /menu place warnings avant ids ; un établissement de test garde au plus 50 images issues de image_url (au-delà, PUT /menu avertit avec images_capped et un plat envoyé seul reçoit 400), une réinitialisation les supprime ; menu.synced indique le connection_id à l'origine de la synchronisation.
• Écritures simultanées : une écriture sur la carte ou l'établissement (/store) qui entre en collision trois fois de suite avec une autre modification reçoit 409 conflict avec Retry-After au lieu de 500. Renvoyez-la ensuite telle quelle.
• Événements : GET /events avec un after qui n'est plus conservé reprend au plus ancien événement conservé et indique gap: true au lieu de répondre 400 ; after=latest part de l'instant présent ; next_after est toujours renseigné. data.object.updated_at des événements de commandes et de réservations est l'heure du changement signalé. store.paused et store.resumed portent l'établissement dans object ; store.updated signale aussi order_statuses ; reservation.updated signale aussi une note modifiée.
• Refuser plutôt que tronquer : une note de pause de plus de 140 caractères et un reason de plus de 200 renvoient 400 avec param au lieu d'être tronqués.
• Droits : GET /tables et GET /areas fonctionnent aussi avec reservations:read.
• Corrections : order.paid ne promet plus de paiements enregistrés sur place (Flavoso n'en enregistre aucun) ; un jeton expiré ou révoqué ne compte plus dans la limite par adresse IP et reçoit toujours 401 ; un PATCH /reservations/{id} qui répond 409 n'a rien modifié ; une Idempotency-Key dont la première requête n'a jamais abouti est de nouveau libre après 2 minutes ; external_id suit partout la même règle (pas d'espace au début ni à la fin, pas de caractères de contrôle).

6 octobre 2026 : la plateforme développeurs#

Une extension majeure : les caisses et d'autres systèmes tiennent désormais la carte à jour, prennent en charge les commandes, gèrent horaires et réservations et rapprochent le chiffre d'affaires.

• Carte : PUT /menu synchronise toute la carte (merge, replace, dry_run) ; POST /menu/availability signale jusqu'à 500 entrées à la fois ; catégories, plats, groupes d'options et options peuvent être créés, modifiés et supprimés un par un ; image_url ; chaque objet porte external_id et updated_at.
• Commandes : POST /orders/{id}/acknowledge prend en charge une commande avec votre propre identifiant ; nouveaux filtres paid, acknowledged, created_since, created_until, external_id ; nouveaux champs source, external_id, acknowledged_at et tax avec les lignes de TVA.
• Établissement : GET /store indique le contact, l'adresse, l'emplacement, le montant minimum de commande, les délais de préparation, les horaires de livraison et les prochains jours particuliers ; nouveautés : PATCH /store, GET et PUT /store/hours et les jours particuliers sous /store/closures.
• Tables et zones : GET /tables, GET /areas.
• Réservations : POST /reservations, PATCH /reservations/{id}, GET /reservations/availability ; nouveaux filtres starts_from et starts_until.
• Rapports : GET /reports/sales et GET /reports/products, avec le nouveau droit reports:read.
• Récupérer les événements : GET /events et GET /events/{id}. Les événements sont désormais créés pour chaque connexion active, même sans webhook.
• Nouveaux types d'événements : order.paid, store.updated, app.scopes_changed, menu.category.*, menu.product.created et .deleted, menu.option_group.*, menu.option.created et .deleted, menu.synced (un événement par synchronisation). menu.product.updated et menu.option.updated arrivent à chaque modification de champ, avec changed et previous.
• Test et réel : livemode dans GET /me et dans chaque événement. GET /me indique aussi tenant.country, plan et rate_limit.
• Erreurs : param indique le champ fautif ; nouveaux codes external_id_taken, slot_unavailable, limit_exceeded.
• OAuth : un jeton de rafraîchissement déjà échangé est encore accepté pendant 60 secondes.
• Webhooks : chaque livraison et toutes ses tentatives dans la console, « Renvoyer », événements de test de tous types ; Flavoso-Delivery-Attempt compte aussi les envois manuels.
• Outils : journal des requêtes, explorateur d'API, jetons de test, annuaire des applications, postman.json, un operationId sur chaque opération de la spécification, et cette documentation.

5 octobre 2026 : la nouvelle adresse#

L'API a désormais sa propre adresse : https://api.flavoso.com. Les jetons et les réponses restent les mêmes, et les anciennes adresses continuent de fonctionner. Vous n'avez à intervenir que si votre application compare iss à une valeur fixe.

• Routes : chaque route se trouve sous https://api.flavoso.com/v1, y compris openapi.json et postman.json.
• OAuth : jeton sous https://api.flavoso.com/oauth/token, révocation sous https://api.flavoso.com/oauth/revoke, métadonnées sous https://api.flavoso.com/.well-known/oauth-authorization-server. L'écran de consentement reste sous https://app.flavoso.com/oauth/authorize, car c'est là que le propriétaire s'identifie.
• Émetteur : issuer dans les métadonnées et iss au retour valent désormais https://api.flavoso.com au lieu de https://app.flavoso.com. Si votre application compare iss à une valeur fixe, mettez-la à jour ; mieux encore, lisez-la dans les métadonnées.
• Anciennes adresses : https://app.flavoso.com/api/public/v1/… et https://app.flavoso.com/api/oauth/… répondent toujours ; l'ancienne adresse des métadonnées redirige vers la nouvelle.

4 octobre 2026 : la première version#

La première version de v1, avec authentification via OAuth 2.0 et PKCE : lire, accepter, refuser, annuler et faire avancer les commandes ; lire la carte, signaler les plats épuisés et les prix ; mettre l'établissement en pause ; lire les réservations et définir leur statut ; webhooks signés.