Anfragen

Basis-URL#

Jede Route liegt unter https://api.flavoso.com/v1. Nur HTTPS. Die Version steht im Pfad (v1), das Versionsdatum im Kopf Flavoso-Api-Version.

Kopfzeilen#

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#

Rümpfe sind JSON-Objekte, Antworten auch. Feldnamen sind englisch und in snake_case. Ein Rumpf darf 64 KB groß sein, beim Abgleich der Speisekarte (PUT /menu) 2 MB, gezählt in Bytes; ein größerer bekommt 413 payload_too_large. Ein Feld, das die Operation nicht kennt, und ein unbekannter Abfrageparameter ergeben 400 invalid_request mit param: so fällt ein Tippfehler sofort auf.

Jedes Objekt nennt seine Art in object, eine Liste ist { "object": "list", "data": [ … ] }. Ein Feld ohne Wert ist null.

Geld und Steuern#

Geldbeträge sind ganze Zahlen in der kleinsten Einheit der Währung, also Cent: 1290 sind 12,90 €. Die Währung steht daneben (currency, ISO 4217) oder beim Betrieb. Nie Kommazahlen.

Steuersätze stehen in Basispunkten: 700 sind 7 %, 1900 sind 19 %. Preise auf Flavoso sind Bruttopreise; eine Bestellung trägt ihre Steuer zusätzlich aufgeteilt nach Satz (tax.lines). Hat der Betrieb für einen Anteil keinen Satz hinterlegt, steht dort rate_bps: null, und net und tax sind null; ebenso kann tax_rate_bps einer Position null sein. Buch einen solchen Anteil zur Klärung, nicht als steuerfrei.

Zeit#

• Zeitpunkte nach ISO 8601 in UTC mit Z: 2026-10-04T17:44:59.942Z. Schick sie mit Zeitzone, Z oder einem Versatz wie +02:00; ohne Zone gibt es 400. In einer Abfrage schreibst du + als %2B (oder nimmst Z). Antworten kommen immer in UTC.
• Kalendertage als YYYY-MM-DD in der Ortszeit des Betriebs, etwa bei Sondertagen und Berichten.
• Uhrzeiten als HH:MM in der Ortszeit des Betriebs, etwa bei Öffnungszeiten. weekday 0 ist Montag, 6 ist Sonntag.
• Die Zeitzone des Betriebs (IANA, etwa Europe/Berlin) steht in GET /me und GET /store.

Kennungen#

Kennungen sind UUIDs und ändern sich nie. Ausnahmen: Ereignisse (evt_…) und Anfragen (req_…). Eine Bestellung hat dazu einen kurzen code, den der Gast sieht, etwa 3271CD; er ist nicht für Zuordnungen gedacht.

Eigene Kennungen: external_id#

Mit external_id hängst du deine eigene Kennung an ein Objekt: die Artikelnummer deiner Kasse an ein Gericht, die Belegnummer an eine Bestellung. Danach findest du es darüber wieder und musst dir keine Zuordnung merken.

• 1 bis 100 Zeichen, keine Steuerzeichen, kein Leerzeichen am Anfang oder Ende. Gezählt in Zeichen, nicht in Bytes.
• Eindeutig je App, Betrieb und Art: zwei Gerichte deiner App im selben Betrieb können nicht dieselbe tragen, ein Gericht und eine Bestellung schon.
• Nur deine App sieht ihre Kennungen, in den Antworten der Routen. Für jede andere App steht dort null, und in Ereignissen immer null: ein Umschlag geht an alle Empfänger gleich.
• Es gibt sie an Kategorien, Gerichten, Optionsgruppen, Optionen und Bestellungen.
• Gesetzt wird sie über PUT /menu, beim Anlegen und Ändern, und bei Bestellungen mit POST /orders/{id}/acknowledge.
• Gefiltert wird mit ?external_id= auf den Listen.
• Ist sie schon vergeben, antwortet Flavoso mit 409 external_id_taken.
• Wird das Objekt gelöscht, verschwindet seine Kennung mit.

# 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 steht in GET /me und in jedem Ereignis: false für einen Test-Betrieb, true für jeden echten. Es gibt dafür keine eigene Adresse und keine eigenen Schlüssel.

Versionen#

Innerhalb von v1 kommen nur Ergänzungen, die nichts brechen: neue Felder, neue Routen, neue Fehlercodes, neue Ereignisse. Was bricht (ein Feld entfällt oder ändert seine Bedeutung), kommt nur in einer neuen Version, und die alte läuft danach mindestens sechs Monate weiter.

Flavoso-Api-Version in jeder Antwort und api_version in jedem Ereignis nennen das Versionsdatum, derzeit 2026-10-08. Was sich wann geändert hat, steht unter Änderungen.

Kein CORS#

Die Schnittstelle arbeitet von Server zu Server. Routen mit Daten senden keinen Access-Control-Allow-Origin, also lässt kein Browser eine fremde Seite ihre Antwort lesen. Ein Token im Browser wäre ein veröffentlichtes Token. Ohne Anmeldung abrufbar sind nur openapi.json, postman.json und die OAuth-Metadaten.

Methoden#

Ein unbekannter Pfad unter /v1 antwortet mit 404 not_found in derselben Fehlerform.