Änderungen

So ändert sich die Schnittstelle#

Innerhalb von v1 kommen nur Ergänzungen, die nichts brechen: neue Felder, neue Routen, neue Fehlercodes, neue Ereignisse. Was bricht, kommt nur in einer neuen Version, und die alte läuft danach mindestens sechs Monate weiter. Flavoso-Api-Version und api_version nennen das Versionsdatum.

8. Oktober 2026: Feinschliff vor den ersten Kassen#

Bevor die ersten Kassen live gehen, haben wir den Vertrag an einigen Stellen nachgeschärft. Manches ist strenger als vorher; es kommt trotzdem innerhalb von v1, weil noch keine Anbindung live war. Hast du gegen einen früheren Stand gebaut, prüf diese Punkte.

• Versionsdatum: Flavoso-Api-Version und api_version neuer Ereignisse nennen jetzt 2026-10-08. Schon zugestellte oder abgefragte Ereignisse behalten 2026-10-04.
• Größe des Rumpfs: ein Rumpf, der größer ist, als die Operation annimmt (64 KB, bei PUT /menu 2 MB, gezählt in Bytes), bekommt 413 payload_too_large statt 400 invalid_request.
• Unbekanntes ist ein Fehler: ein unbekannter Abfrageparameter oder ein unbekanntes Feld im Rumpf ergibt bei jeder Operation 400 invalid_request mit param.
• Zeitpunkte mit Zeitzone: updated_since, created_since, starts_from und die übrigen Zeitpunkte einer Anfrage, auch until bei POST /store/pause, brauchen Z oder einen Versatz, sonst 400. Ein unkodiertes + in der Abfrage wird vor dem Versatz angenommen.
• Anlegen antwortet 201: POST /menu/categories, /menu/products, /menu/option-groups, /menu/option-groups/{id}/options und POST /store/closures für einen neuen Tag (200, wenn er einen ersetzt).
• Annehmen: POST /orders/{id}/accept schaltet eine Bestellung aus pending auf den nächsten Stand, den der Betrieb benutzt (nicht immer confirmed); steht sie schon dahinter, kommt sie unverändert mit 200 zurück, eine fertige oder stornierte antwortet mit 409 invalid_transition.
• Optionen in Bestellungen: items[].options[] tragen id, group_id und group_name (null bei älteren Bestellungen).
• Speisekarte: neu ist GET /menu/options; die Antwort von PUT /menu nennt warnings vor ids; ein Test-Betrieb behält höchstens 50 Bilder aus image_url (darüber warnt PUT /menu mit images_capped, ein einzelnes Gericht bekommt 400), Zurücksetzen löscht sie; menu.synced nennt die connection_id, die abgeglichen hat.
• Gleichzeitiges Schreiben: ein Schreibzugriff auf Speisekarte oder Laden (/store), der dreimal hintereinander mit einer anderen Änderung zusammenstößt, antwortet mit 409 conflict und Retry-After statt mit 500. Schick ihn danach unverändert noch einmal.
• Ereignisse: GET /events mit einem after, das nicht mehr aufbewahrt ist, macht beim ältesten aufbewahrten Ereignis weiter und sagt gap: true, statt mit 400 zu antworten; after=latest fängt jetzt an; next_after ist immer gesetzt. data.object.updated_at in Ereignissen zu Bestellungen und Reservierungen ist der Zeitpunkt der gemeldeten Änderung. store.paused und store.resumed tragen den Laden als object; store.updated meldet auch order_statuses; reservation.updated meldet auch eine geänderte note.
• Ablehnen statt kürzen: eine note der Pause über 140 Zeichen und ein reason über 200 Zeichen ergeben 400 mit param, statt gekürzt zu werden.
• Rechte: GET /tables und GET /areas gehen auch mit reservations:read.
• Berichtigt: order.paid verspricht keine vor Ort vermerkten Zahlungen mehr (Flavoso vermerkt keine); ein abgelaufenes oder widerrufenes Token zählt nicht mehr zur Grenze je IP-Adresse und bekommt immer 401; ein PATCH /reservations/{id}, das mit 409 antwortet, hat nichts geändert; ein Idempotency-Key, dessen erste Anfrage nie fertig wurde, ist nach 2 Minuten wieder frei; external_id folgt überall einer Regel (kein Leerzeichen am Anfang oder Ende, keine Steuerzeichen).

6. Oktober 2026: die Entwicklerplattform#

Die große Erweiterung: Kassen und andere Systeme pflegen jetzt die Karte, übernehmen Bestellungen, führen Zeiten und Reservierungen und gleichen Umsätze ab.

• Speisekarte: PUT /menu gleicht die ganze Karte ab (merge, replace, dry_run); POST /menu/availability meldet bis zu 500 Einträge auf einmal; Kategorien, Gerichte, Optionsgruppen und Optionen lassen sich einzeln anlegen, ändern und löschen; image_url; jedes Objekt trägt external_id und updated_at.
• Bestellungen: POST /orders/{id}/acknowledge übernimmt eine Bestellung mit eigener Kennung; neue Filter paid, acknowledged, created_since, created_until, external_id; neue Felder source, external_id, acknowledged_at und tax mit Steuerzeilen.
• Betrieb: GET /store nennt Kontakt, Anschrift, Lage, Mindestbestellwert, Vorlaufzeiten, Lieferzeiten und kommende Sondertage; neu sind PATCH /store, GET und PUT /store/hours und die Sondertage unter /store/closures.
• Tische und Bereiche: GET /tables, GET /areas.
• Reservierungen: POST /reservations, PATCH /reservations/{id}, GET /reservations/availability; neue Filter starts_from und starts_until.
• Berichte: GET /reports/sales und GET /reports/products, mit dem neuen Recht reports:read.
• Ereignisse abrufen: GET /events und GET /events/{id}. Ereignisse entstehen jetzt für jede aktive Verbindung, auch ohne Webhook.
• Neue Ereignisarten: order.paid, store.updated, app.scopes_changed, menu.category.*, menu.product.created und .deleted, menu.option_group.*, menu.option.created und .deleted, menu.synced (ein Ereignis je Abgleich). menu.product.updated und menu.option.updated kommen bei jeder Feldänderung, mit changed und previous.
• Test und echt: livemode in GET /me und in jedem Ereignis. GET /me nennt dazu tenant.country, plan und rate_limit.
• Fehler: param nennt das fehlerhafte Feld; neue Codes external_id_taken, slot_unavailable, limit_exceeded.
• OAuth: ein schon getauschtes Refresh-Token wird 60 Sekunden lang noch angenommen.
• Webhooks: jede Zustellung mit jedem Versuch in der Konsole, „Erneut senden“, Test-Ereignisse jeder Art; Flavoso-Delivery-Attempt zählt auch Sendungen von Hand.
• Werkzeuge: Anfrage-Protokoll, API-Explorer, Test-Token, App-Verzeichnis, postman.json, operationId an jeder Operation der Spezifikation, und diese Dokumentation.

5. Oktober 2026: die neue Adresse#

Die Schnittstelle hat eine eigene Adresse: https://api.flavoso.com. Tokens und Antworten bleiben dieselben, und die alten Adressen gelten weiter. Handeln musst du nur, wenn deine App iss mit einem festen Wert vergleicht.

• Routen: jede Route liegt unter https://api.flavoso.com/v1, auch openapi.json und postman.json.
• OAuth: Token unter https://api.flavoso.com/oauth/token, Widerruf unter https://api.flavoso.com/oauth/revoke, Metadaten unter https://api.flavoso.com/.well-known/oauth-authorization-server. Der Zustimmungsbildschirm bleibt unter https://app.flavoso.com/oauth/authorize, denn dort meldet sich der Inhaber an.
• Aussteller: issuer in den Metadaten und iss bei der Rückkehr sind jetzt https://api.flavoso.com statt https://app.flavoso.com. Vergleicht deine App iss mit einem festen Wert, stell ihn um; besser liest sie ihn aus den Metadaten.
• Alte Adressen: https://app.flavoso.com/api/public/v1/… und https://app.flavoso.com/api/oauth/… antworten weiter; die alte Adresse der Metadaten leitet auf die neue weiter.

4. Oktober 2026: die erste Fassung#

Die erste Fassung von v1, mit Anmeldung per OAuth 2.0 und PKCE: Bestellungen lesen, annehmen, ablehnen, stornieren und weiterschalten; die Speisekarte lesen, Ausverkauft und Preise melden; den Laden pausieren; Reservierungen lesen und ihren Stand setzen; signierte Webhooks.