Concepts

Le modèle#

Flavoso est un système de commande pour les restaurants. Chaque établissement a sa propre page de commande, sa carte, sa cuisine et son tableau de bord. Votre application travaille pour le compte d'un établissement, une fois que son propriétaire a donné son accord.

Application#

Une application, c'est votre logiciel tel que Flavoso le connaît : créée dans la console, avec un client ID (flv_app_…), un type de client, des URI de redirection, les droits qu'elle peut demander et un webhook. Une application peut être connectée à autant d'établissements que nécessaire ; un compte peut avoir jusqu'à 10 applications.

Chaque application a un statut : en développement, en cours d'examen, approuvée, refusée ou bloquée. Jusqu'à sa validation, elle ne se connecte qu'à votre établissement de test et aux établissements dont vous êtes vous-même propriétaire.

Établissement#

Un établissement est un restaurant sur Flavoso. Dans l'API, c'est l'objet tenant, avec id, name, slug (la partie de l'adresse de sa page de commande), timezone, currency et country. GET /me le renvoie.

Un établissement a une offre (Starter, Pro, Premium). L'API est incluse dans chaque offre ; les réservations sont disponibles à partir de l'offre Pro.

Connexion#

Une connexion, c'est le consentement d'un propriétaire : cette application peut travailler avec cet établissement, avec ces droits. Son identifiant s'appelle connection_id dans la réponse du point de terminaison des jetons et dans chaque événement, et id dans GET /me, car GET /me renvoie la connexion elle-même. Son created_at y figure aussi.

Il existe au plus une connexion active par application et par établissement. Si le propriétaire connecte à nouveau l'application, ce sont ensuite les nouveaux droits qui s'appliquent. Une connexion prend fin quand le propriétaire déconnecte l'application, quand votre application appelle DELETE /connection ou quand Flavoso y met fin ; vous recevez alors app.disconnected.

Jetons#

• Jeton d'accès (flv_at_…) : accompagne chaque requête, valable une heure.
• Jeton de rafraîchissement (flv_rt_…) : sert à obtenir de nouveaux jetons d'accès, valable 180 jours à compter de sa dernière utilisation et remplacé par un nouveau à chaque utilisation.

Chaque jeton appartient à une seule connexion, donc à un seul établissement. Une application connectée à cent établissements gère cent paires de jetons, idéalement enregistrées sous le connection_id ou le tenant.id.

Droits#

Neuf droits déterminent ce qu'une connexion peut faire, par exemple orders:write ou menu:read. L'écriture inclut la lecture. Le propriétaire les voit formulés en clair quand il connecte l'application. Tous les détails sous Droits.

Test et réel#

Il n'y a ni clés de test séparées ni seconde adresse. La différence, c'est l'établissement : un établissement de test ne peut jamais passer en ligne, et tout ce qui en provient porte livemode: false, dans GET /me et dans chaque événement. Même application, mêmes routes, mêmes formats de jetons.

Objets et identifiants#

Chaque objet porte son object (order, product, reservation, event …) et un id. Les identifiants sont des UUID, sauf pour les événements (evt_…) et les requêtes (req_…). Un identifiant ne change jamais, même quand l'établissement modifie un nom ou un prix.

Vos propres identifiants, par exemple le numéro d'article de votre caisse, se placent à côté, dans external_id. Voir Requêtes.

Deux sens#

• Votre application interroge : REST sur https://api.flavoso.com/v1, JSON dans les deux sens.
• Flavoso signale : chaque changement sous forme d'événement, livré par webhook ou récupéré avec GET /events.

Un changement est le même où qu'il se produise : dans le tableau de bord, sur l'écran de cuisine, dans l'application mobile, à l'imprimante de tickets ou via l'API. Un événement le signale une seule fois.