Concetti

Il modello#

Flavoso è un sistema di ordinazione per ristoranti. Ogni locale ha la propria pagina ordini, il proprio menu, la propria cucina e la propria dashboard. La tua app lavora per conto di un locale dopo che il suo titolare ha dato il consenso.

App#

Un'app è il tuo software così come lo conosce Flavoso: creata nella console, con client ID (flv_app_…), tipo di client, URI di reindirizzamento, i permessi che può richiedere e un webhook. Un'app può essere collegata a un numero qualsiasi di locali; un account ha al massimo 10 app.

Ogni app ha uno stato: in sviluppo, in revisione, approvata, rifiutata o bloccata. Fino all'approvazione si collega solo al tuo locale di prova e ai locali di cui sei tu stesso titolare.

Locale#

Un locale è un ristorante su Flavoso. Nell'API si chiama tenant: con id, name, slug (la parte dell'indirizzo della sua pagina ordini), timezone, currency e country. GET /me lo indica.

Un locale ha un piano (Starter, Pro, Premium). L'API è inclusa in ogni piano; le prenotazioni sono disponibili dal piano Pro.

Collegamento#

Un collegamento è il consenso di un titolare: questa app può lavorare con questo locale, con questi permessi. Il suo identificativo si chiama connection_id nella risposta dell'endpoint del token e in ogni evento, e id in GET /me, perché GET /me restituisce il collegamento stesso. Lì c'è anche il suo created_at.

Per ogni app e locale c'è al massimo un collegamento attivo. Se il titolare collega di nuovo l'app, da lì in poi valgono i nuovi permessi. Un collegamento termina quando il titolare scollega l'app, quando la tua app chiama DELETE /connection o quando Flavoso lo chiude; allora arriva app.disconnected.

Token#

• Token di accesso (flv_at_…): va in ogni richiesta, vale un'ora.
• Token di aggiornamento (flv_rt_…): serve a ottenere nuovi token di accesso, vale 180 giorni dal suo ultimo utilizzo e a ogni utilizzo viene sostituito da uno nuovo.

Ogni token appartiene a un solo collegamento e quindi a un solo locale. Un'app con cento locali gestisce cento coppie di token, meglio se salvate sotto il connection_id o il tenant.id.

Permessi#

Nove permessi stabiliscono cosa può fare un collegamento, per esempio orders:write o menu:read. La scrittura include la lettura. Il titolare li vede in parole chiare quando collega l'app. I dettagli sono in Permessi.

Prova e reale#

Non ci sono chiavi di prova separate né un secondo indirizzo. La differenza è il locale: un locale di prova non può mai andare online, e tutto ciò che viene da lì porta livemode: false, in GET /me e in ogni evento. La stessa app, gli stessi endpoint, gli stessi formati di token.

Oggetti e identificativi#

Ogni oggetto ha il suo object (order, product, reservation, event …) e un id. Gli identificativi sono UUID, tranne per gli eventi (evt_…) e le richieste (req_…). Un identificativo non cambia mai, nemmeno quando il locale cambia nome o prezzo.

Puoi aggiungere i tuoi identificativi, per esempio il codice articolo della tua cassa, come external_id. Vedi Richieste.

Due direzioni#

• La tua app chiede: REST su https://api.flavoso.com/v1, JSON in entrambe le direzioni.
• Flavoso segnala: ogni modifica come evento, consegnato via webhook o recuperato con GET /events.

Una modifica è la stessa ovunque avvenga: nella dashboard, sul display di cucina, nell'app per il telefono, alla stampante per scontrini o tramite l'API. Un evento la segnala esattamente una volta.