Schnellstart

Zwei Wege#

Es gibt zwei Wege zu einem Token, und du brauchst beide:

• Test-Token: ein Klick in der Konsole, und du fragst deinen eigenen Test-Betrieb ab. Ideal, um die Schnittstelle in zwei Minuten kennenzulernen.
• OAuth 2.0: so verbindet später jeder Betrieb deine App. Der Inhaber meldet sich an, stimmt zu, und deine App bekommt Tokens für genau diesen Betrieb.

Du brauchst dafür nur ein kostenloses Flavoso-Konto, keinen eigenen Betrieb und kein Abo. Die Beispiele laufen mit curl, Node.js ab Version 18, Python 3 mit requests und PHP ab Version 8.

Mit dem Einrichtungs-Assistenten#

Am schnellsten geht es in der Konsole selbst. Hast du noch keine App, öffnet sie den Einrichtungs-Assistenten, und er führt dich in fünf Schritten zur ersten Antwort. Bis alles erledigt ist, steht er links unter Einrichtung.

1. 1

   App anlegen

   Name, wo sie läuft (auf deinem Server oder auf einem Gerät im Betrieb) und was sie dürfen soll. Das Client-Secret zeigt der Assistent genau einmal.

   Konsole › Einrichtung

2. 2

   Test-Betrieb anlegen

   Ein Restaurant zum Ausprobieren, mit Beispiel-Speisekarte und Tischen.

3. 3

   Test-Token erzeugen

   Zugang zum Test-Betrieb ohne den OAuth-Ablauf.

4. 4

   Erste Anfrage

   GET /me mit dem Token, aus deinem Code oder direkt im Browser. Der Assistent erkennt die Anfrage, sobald sie bei Flavoso ankommt, und zeigt Status und Antwort.

5. 5

   Ereignisse empfangen

   Per Webhook an deinen Server oder abgeholt mit GET /events. Eine Testbestellung zeigt, dass es ankommt.

Die Abschnitte darunter gehen dieselben Schritte von Hand durch, mit Code für jeden.

App und Test-Betrieb anlegen#

1. 1

   Konto anlegen

   Über „Kostenloses Entwicklerkonto“ auf der Startseite dieser Dokumentation. Hast du schon ein Flavoso-Konto, meldest du dich einfach an.

   app.flavoso.com

2. 2

   App anlegen

   In der Konsole unter Apps „Neue App“ wählen: Name, Client-Typ (vertraulich für Apps mit eigenem Server), eine Redirect-URI und die Rechte, die deine App braucht. Die Entwicklerbedingungen bestätigen. Das Client-Secret wird genau einmal angezeigt: sofort kopieren.

   Konsole › Apps › Neue App

3. 3

   Test-Betrieb anlegen

   Ein Klick legt deinen Test-Betrieb an: ein kostenloses Restaurant zum Ausprobieren, mit Beispiel-Speisekarte und Tischen. Alle deine Apps teilen ihn.

   Konsole › Test-Betrieb

Für den Schnellstart reichen die Rechte orders:write, menu:write und store:write. Welche es gibt, steht unter Rechte.

Weg 1: Test-Token#

Unter Zugangsdaten deiner App erzeugt „Test-Token erzeugen“ ein Access-Token und ein Refresh-Token für deinen Test-Betrieb, beide mit den Rechten deiner App. Das Access-Token gilt eine Stunde, das Refresh-Token 180 Tage ab der letzten Nutzung und wird wie jedes andere bei jeder Nutzung getauscht. Die Konsole zeigt beide genau einmal. Dabei entsteht die Verbindung zwischen App und Test-Betrieb, genau wie bei einer Zustimmung.

Setz das Token als Umgebungsvariable ACCESS_TOKEN und frag GET /me ab, also die Verbindung selbst:

# 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"

Die Antwort nennt den Betrieb, die erteilten Rechte und livemode. Im Test-Betrieb ist livemode immer false:

{
  "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"
}

Erste Bestellung annehmen#

1. 1

   Testbestellung anlegen

   „Testbestellungen anlegen“ legt im Test-Betrieb eine echte Bestellung an, als hätte ein Gast sie aufgegeben. Sie erscheint in der API und löst Webhooks aus.

   Konsole › Test-Betrieb › Bestellungen

2. 2

   Offene Bestellungen holen

   GET /orders?status=pending liefert die Bestellungen, die auf den Betrieb warten.

3. 3

   Annehmen

   POST /orders/{id}/accept nimmt sie an, wie ein Klick im Dashboard. Mit Idempotency-Key ist eine Wiederholung gefahrlos.

# 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"

In der Konsole unter Test-Betrieb › Bestellungen steht die Bestellung danach als angenommen, und das Protokoll deiner App zeigt die Anfrage samt Antwort.

Weg 2: Verbinden per OAuth#

Ein echter Betrieb gibt dir kein Token in die Hand. Sein Inhaber verbindet deine App, und dafür baust du den Ablauf nach OAuth 2.0 mit PKCE ein. Mit deinem Test-Betrieb probierst du ihn aus, bevor ihn jemand anderes sieht.

1. 1

   state und PKCE erzeugen

   Einen zufälligen code_verifier und state erzeugen, daraus die code_challenge rechnen (SHA-256, Base64URL).

2. 2

   Zur Zustimmung schicken

   Den Browser an https://app.flavoso.com/oauth/authorize schicken. Dort mit deinem Konto anmelden, den Test-Betrieb wählen, „Verbinden“ drücken.

3. 3

   Code gegen Tokens tauschen

   Flavoso leitet mit code, state und iss auf deine Redirect-URI zurück. state vergleichen, dann den Code innerhalb von 10 Minuten bei https://api.flavoso.com/oauth/token tauschen.

4. 4

   Anfragen

   Mit dem access_token aus der Antwort fragst du die API ab, genau wie mit dem Test-Token.

# 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"

Die Antwort des Token-Endpunkts:

{
  "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"
  }
}

Alles zu Client-Typen, Redirect-URIs, Fehlern und der Zustimmung steht unter Authentifizierung.

Token erneuern#

Ein Access-Token gilt eine Stunde. Danach holst du mit dem Refresh-Token ein neues Paar. Jede Erneuerung bringt ein neues Refresh-Token, und nur das neue gilt weiter: speichere es, bevor du das neue Access-Token benutzt.

# 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

Wie Rotation, Gnadenfrist und Widerruf zusammenhängen, steht unter Authentifizierung.

Wie es weitergeht#

• Webhooks einrichten, damit neue Bestellungen von selbst ankommen. Eine Kasse ohne öffentliche Adresse ruft die Ereignisse ab.
• Für eine Kasse: der Leitfaden Kassenanbindung von A bis Z.
• Fehler richtig behandeln: Fehler, Idempotenz, Anfragegrenzen.
• Wenn alles läuft: Freigabe und Verzeichnis.