Konzepte

Das Modell#

Flavoso ist ein Bestellsystem für Restaurants. Jeder Betrieb hat seine eigene Bestellseite, Speisekarte, Küche und sein Dashboard. Deine App arbeitet im Auftrag eines Betriebs, nachdem sein Inhaber zugestimmt hat.

App#

Eine App ist deine Software, wie Flavoso sie kennt: angelegt in der Konsole, mit Client-ID (flv_app_…), Client-Typ, Redirect-URIs, den Rechten, die sie anfragen darf, und einem Webhook. Eine App kann mit beliebig vielen Betrieben verbunden sein; ein Konto hat höchstens 10 Apps.

Jede App hat einen Stand: in Entwicklung, in Prüfung, freigegeben, abgelehnt oder gesperrt. Bis zur Freigabe verbindet sie sich nur mit deinem Test-Betrieb und mit Betrieben, in denen du selbst Inhaber bist.

Betrieb#

Ein Betrieb ist ein Restaurant auf Flavoso. In der Schnittstelle heißt er tenant: mit id, name, slug (der Teil der Adresse seiner Bestellseite), timezone, currency und country. GET /me nennt ihn.

Ein Betrieb hat einen Tarif (Starter, Pro, Premium). Die Schnittstelle gehört zu jedem Tarif; Reservierungen gibt es ab Pro.

Verbindung#

Eine Verbindung ist die Zustimmung eines Inhabers: diese App darf mit diesem Betrieb arbeiten, mit diesen Rechten. Ihre Kennung steht in der Antwort des Token-Endpunkts und in jedem Ereignis als connection_id, in GET /me als id, denn GET /me gibt die Verbindung selbst zurück. Dort steht auch ihr created_at.

Je App und Betrieb gibt es höchstens eine aktive Verbindung. Verbindet der Inhaber neu, gelten danach die neuen Rechte. Eine Verbindung endet, wenn der Inhaber trennt, wenn deine App DELETE /connection ruft oder wenn Flavoso sie beendet; dann kommt app.disconnected.

Tokens#

• Access-Token (flv_at_…): steht in jeder Anfrage, gilt eine Stunde.
• Refresh-Token (flv_rt_…): holt neue Access-Tokens, gilt 180 Tage ab seiner letzten Nutzung und wird bei jeder Nutzung gegen ein neues getauscht.

Jedes Token gehört zu genau einer Verbindung und damit zu genau einem Betrieb. Eine App mit hundert Betrieben verwaltet hundert Token-Paare, am besten gespeichert unter der connection_id oder der tenant.id.

Rechte#

Neun Rechte steuern, was eine Verbindung darf, etwa orders:write oder menu:read. Schreiben schließt Lesen ein. Der Inhaber sieht sie beim Verbinden in Klartext. Alles dazu unter Rechte.

Test und echt#

Es gibt keine getrennten Test-Schlüssel und keine zweite Adresse. Der Unterschied ist der Betrieb: ein Test-Betrieb kann nie live gehen, und alles aus ihm trägt livemode: false, in GET /me und in jedem Ereignis. Dieselbe App, dieselben Routen, dieselben Tokenformen.

Objekte und Kennungen#

Jedes Objekt trägt sein object (order, product, reservation, event …) und eine id. Kennungen sind UUIDs, außer bei Ereignissen (evt_…) und Anfragen (req_…). Eine Kennung ändert sich nie, auch wenn der Betrieb Name oder Preis ändert.

Deine eigenen Kennungen, etwa die Artikelnummer deiner Kasse, legst du als external_id daneben. Siehe Anfragen.

Zwei Richtungen#

• Deine App fragt: REST unter https://api.flavoso.com/v1, JSON hin und zurück.
• Flavoso meldet: jede Änderung als Ereignis, zugestellt per Webhook oder abgeholt mit GET /events.

Eine Änderung entsteht überall gleich, egal ob im Dashboard, am Küchenbildschirm, in der Handy-App, am Bondrucker oder über die API. Ein Ereignis zeigt sie genau einmal.