Démarrage rapide

Votre première réponse en deux minutes avec un jeton de test, puis le parcours complet via OAuth 2.0.

Deux méthodes

Il existe deux façons d'obtenir un jeton, et vous avez besoin des deux :

Jeton de test : un clic dans la console, et vous interrogez votre propre établissement de test. Idéal pour découvrir l'API en deux minutes.
OAuth 2.0 : c'est ainsi que chaque établissement connectera plus tard votre application. Le propriétaire s'identifie, donne son accord, et votre application reçoit des jetons pour cet établissement précis.

Un compte Flavoso gratuit suffit : pas besoin d'établissement à vous ni d'abonnement. Les exemples fonctionnent avec curl, Node.js 18 ou plus récent, Python 3 avec requests et PHP 8 ou plus récent.

Avec l'assistant de configuration

Le chemin le plus rapide passe par la console elle-même. Si vous n'avez pas encore d'application, la console ouvre l'assistant de configuration, qui vous mène en cinq étapes jusqu'à votre première réponse. Tant que tout n'est pas terminé, vous le trouvez à gauche sous Configuration.

1
Créer l'application
Nom, où elle s'exécute (sur votre serveur ou sur un appareil dans l'établissement) et ce qu'elle a le droit de faire. L'assistant n'affiche le client secret qu'une seule fois.
Console › Configuration
2
Créer l'établissement de test
Un restaurant pour essayer, avec une carte d'exemple et des tables.
3
Créer un jeton de test
Un accès à l'établissement de test sans parcours OAuth.
4
Première requête
GET /me avec le jeton, depuis votre code ou directement dans le navigateur. L'assistant détecte la requête dès qu'elle arrive chez Flavoso et affiche le statut et la réponse.
5
Recevoir des événements
Par webhook vers votre serveur, ou récupérés avec GET /events. Une commande test montre qu'ils arrivent.

Les sections ci-dessous reprennent les mêmes étapes à la main, avec du code pour chacune.

Créer une application et un établissement de test

1
Créer un compte
Cliquez sur « Compte développeur gratuit », sur la page d'accueil de cette documentation. Si vous avez déjà un compte Flavoso, connectez-vous simplement.
app.flavoso.com
2
Créer une application
Dans la console, sous Applications, choisissez « Nouvelle application » et indiquez le nom, le type de client (confidentiel pour les applications dotées de leur propre serveur), une URI de redirection et les droits dont votre application a besoin. Acceptez les conditions pour les développeurs. Le client secret ne s'affiche qu'une seule fois : copiez-le immédiatement.
Console › Applications › Nouvelle application
3
Créer un établissement de test
Un clic crée votre établissement de test : un restaurant gratuit pour essayer, avec une carte d'exemple et des tables. Toutes vos applications le partagent.
Console › Établissement de test

Pour le démarrage rapide, les droits orders:write, menu:write et store:write suffisent. La liste complète des droits figure sous Droits.

Méthode 1 : jeton de test

Dans les Identifiants de votre application, « Créer un jeton de test » délivre un jeton d'accès et un jeton de rafraîchissement pour votre établissement de test, tous deux avec les droits de votre application. Le jeton d'accès est valable une heure, le jeton de rafraîchissement 180 jours à compter de sa dernière utilisation ; comme tout jeton de rafraîchissement, il est remplacé par un nouveau à chaque utilisation. La console affiche les deux une seule fois. Cela crée aussi la connexion entre l'application et l'établissement de test, exactement comme le ferait un consentement.

Placez le jeton dans la variable d'environnement ACCESS_TOKEN et appelez GET /me, qui renvoie la connexion elle-même :

# The test token from the developer console (valid for up to one hour)
export ACCESS_TOKEN="flv_at_..."

curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La réponse indique l'établissement, les droits accordés et livemode. Dans l'établissement de test, livemode vaut toujours false :

Réponse

{
  "object": "connection",
  "id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "livemode": false,
  "app": {
    "client_id": "flv_app_...",
    "name": "Example POS"
  },
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Test restaurant",
    "slug": "test-k7q2m9",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "country": "DE"
  },
  "scopes": [
    "orders:write",
    "menu:write",
    "store:write",
    "reports:read"
  ],
  "plan": "pro",
  "rate_limit": {
    "limit": 120,
    "window_seconds": 60
  },
  "created_at": "2026-10-04T17:40:00.000Z"
}

Accepter votre première commande

1
Créer une commande test
« Créer des commandes test » crée une vraie commande dans l'établissement de test, comme si un client l'avait passée. Elle apparaît dans l'API et déclenche des webhooks.
Console › Établissement de test › Commandes
2
Récupérer les commandes en attente
GET /orders?status=pending renvoie les commandes qui attendent une réponse de l'établissement.
3
Accepter
POST /orders/{id}/accept l'accepte, comme un clic dans le tableau de bord. Avec une Idempotency-Key, une nouvelle tentative est sans risque.

# The orders waiting for the restaurant ("Create test orders" in the console creates one)
curl "https://api.flavoso.com/v1/orders?status=pending" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Accept one. The same key gives the same result, so a retry is safe.
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

Dans la console, sous Établissement de test › Commandes, la commande apparaît ensuite comme acceptée, et le journal de votre application montre la requête avec sa réponse.

Méthode 2 : connexion avec OAuth

Un vrai établissement ne vous remet pas de jeton. Son propriétaire connecte votre application, et pour cela vous intégrez le parcours OAuth 2.0 avec PKCE. Vous le testez d'abord avec votre établissement de test, avant que quiconque ne le voie.

1
Créer state et PKCE
Générez un code_verifier et un state aléatoires, et dérivez-en le code_challenge (SHA-256, Base64URL).
2
Rediriger vers le consentement
Redirigez le navigateur vers https://app.flavoso.com/oauth/authorize. Identifiez-vous avec votre compte, choisissez l'établissement de test, cliquez sur « Connecter ».
3
Échanger le code contre des jetons
Flavoso redirige vers votre URI de redirection avec code, state et iss. Vérifiez state, puis échangez le code auprès de https://api.flavoso.com/oauth/token dans les 10 minutes.
4
Envoyer des requêtes
Appelez l'API avec l'access_token de la réponse, exactement comme avec le jeton de test.

# 1. PKCE: a random code_verifier, its S256 code_challenge and a random state
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

# 2. Open this address in a browser, sign in, pick your test restaurant, press "Connect".
#    http://127.0.0.1:8080/callback must be one of your app's redirect URIs. For a
#    confidential app such a loopback address only connects your test restaurant.
echo "https://app.flavoso.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&scope=orders%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 3. The browser lands on http://127.0.0.1:8080/callback?code=...&state=...&iss=...
#    Nothing has to listen there. Compare state with $STATE, then copy the code (valid 10 minutes, once).
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=http://127.0.0.1:8080/callback \
  -d code_verifier=$CODE_VERIFIER

# 4. First request with the access_token from the response
curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La réponse du point de terminaison des jetons :

Réponse

{
  "access_token": "flv_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "flv_rt_...",
  "scope": "orders:write menu:write store:write reports:read",
  "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Pizzeria Example",
    "slug": "pizzeria-example"
  }
}

Types de client, URI de redirection, erreurs, consentement : tout est détaillé sous Authentification.

Rafraîchir un jeton

Un jeton d'accès est valable une heure. Ensuite, vous obtenez une nouvelle paire avec le jeton de rafraîchissement. Chaque rafraîchissement fournit aussi un nouveau jeton de rafraîchissement, et seul celui-ci reste valable : enregistrez-le avant d'utiliser le nouveau jeton d'accès.

# Access tokens last one hour. The response carries a NEW refresh token: store it.
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

Pour comprendre comment s'articulent la rotation, le délai de grâce et la révocation, consultez Authentification.

Pour aller plus loin

Configurez des webhooks pour que les nouvelles commandes arrivent d'elles-mêmes. Une caisse sans adresse publique récupère les événements.
Pour une caisse : le guide Intégration caisse de A à Z.
Traitez correctement les erreurs : Erreurs, Idempotence, Limites de requêtes.
Quand tout fonctionne : Validation et annuaire.

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.