Richieste

URL di base#

Ogni endpoint si trova sotto https://api.flavoso.com/v1. Solo HTTPS. La versione è nel percorso (v1), la data di versione nell'intestazione Flavoso-Api-Version.

Intestazioni#

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#

I corpi sono oggetti JSON, e così le risposte. I nomi dei campi sono in inglese e in snake_case. Un corpo può arrivare a 64 KB (2 MB nella sincronizzazione del menu, PUT /menu), contati in byte; uno più grande riceve 413 payload_too_large. Un campo che l'operazione non conosce, e un parametro di query sconosciuto, danno 400 invalid_request con param: un errore di battitura non passa in silenzio.

Ogni oggetto indica il suo tipo in object, un elenco è { "object": "list", "data": [ … ] }. Un campo senza valore è null.

Importi e imposte#

Gli importi sono numeri interi nella più piccola unità della valuta, quindi centesimi: 1290 sono 12,90 €. La valuta è indicata accanto (currency, ISO 4217) oppure è quella del locale. Niente numeri decimali.

Le aliquote sono in punti base: 700 è il 7%, 1900 è il 19%. I prezzi su Flavoso sono lordi; un ordine riporta in più la sua imposta suddivisa per aliquota (tax.lines). Se il locale non ha registrato alcuna aliquota per una quota, quella riga ha rate_bps: null, e net e tax sono null; anche il tax_rate_bps di una voce può essere null. Contabilizza una quota di questo tipo come da verificare, non come esente da imposta.

Date e orari#

• I timestamp seguono ISO 8601 in UTC con Z: 2026-10-04T17:44:59.942Z. Inviali con un fuso orario, Z o uno scostamento come +02:00; senza fuso la risposta è 400. In una query scrivi + come %2B (oppure usa Z). Le risposte arrivano sempre in UTC.
• I giorni di calendario come YYYY-MM-DD nel fuso orario del locale, per esempio per i giorni speciali e i report.
• Gli orari come HH:MM nel fuso orario del locale, per esempio per gli orari di apertura. weekday 0 è lunedì, 6 è domenica.
• Il fuso orario del locale (IANA, per esempio Europe/Berlin) è in GET /me e GET /store.

Identificativi#

Gli identificativi sono UUID e non cambiano mai. Eccezioni: eventi (evt_…) e richieste (req_…). Un ordine ha inoltre un breve code che il cliente vede, per esempio 3271CD; non è pensato come chiave di associazione.

Identificativi propri: external_id#

Con external_id associ il tuo identificativo a un oggetto: il codice articolo della tua cassa a un piatto, il numero di scontrino a un ordine. Poi ritrovi l'oggetto tramite quello e non devi tenere una tabella di corrispondenze.

• Da 1 a 100 caratteri, senza caratteri di controllo e senza spazi all'inizio o alla fine. Contati in caratteri, non in byte.
• Univoco per app, locale e tipo: due piatti della tua app nello stesso locale non possono avere lo stesso, un piatto e un ordine sì.
• Solo la tua app vede i suoi identificativi, nelle risposte degli endpoint. Per ogni altra app lì c'è null, e negli eventi sempre null: una busta è identica per tutti i destinatari.
• Esiste per categorie, piatti, gruppi di opzioni, opzioni e ordini.
• Si imposta con PUT /menu, alla creazione e alla modifica, e per gli ordini con POST /orders/{id}/acknowledge.
• Si filtra con ?external_id= sugli elenchi.
• Se è già in uso, Flavoso risponde 409 external_id_taken.
• Se l'oggetto viene eliminato, anche il suo identificativo scompare.

# 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 compare in GET /me e in ogni evento: false per un locale di prova, true per ogni locale reale. Per questo non ci sono né un indirizzo né chiavi separate.

Versioni#

All'interno di v1 arrivano solo aggiunte compatibili: nuovi campi, nuovi endpoint, nuovi codici di errore, nuovi eventi. Ciò che rompe la compatibilità (un campo scompare o cambia significato) arriva solo in una nuova versione, e quella vecchia continua a funzionare per almeno sei mesi.

Flavoso-Api-Version in ogni risposta e api_version in ogni evento indicano la data di versione, attualmente 2026-10-08. Cosa è cambiato e quando lo trovi in Modifiche.

Niente CORS#

L'API funziona solo da server a server. Gli endpoint con dati non inviano Access-Control-Allow-Origin, quindi nessun browser lascia leggere la loro risposta a una pagina esterna. Un token nel browser sarebbe un token pubblicato. Senza autenticazione si possono recuperare solo openapi.json, postman.json e i metadati OAuth.

Metodi#

Un percorso sconosciuto sotto /v1 risponde 404 not_found nello stesso formato di errore.