Modifiche

Come cambia l'API#

All'interno di v1 arrivano solo aggiunte compatibili: nuovi campi, nuovi endpoint, nuovi codici di errore, nuovi eventi. Ciò che rompe la compatibilità arriva solo in una nuova versione, e quella vecchia continua a funzionare per almeno sei mesi. Flavoso-Api-Version e api_version indicano la data di versione.

8 ottobre 2026: rifiniture prima delle prime casse#

Prima che le prime casse vadano in produzione, abbiamo reso il contratto più rigoroso in alcuni punti. Alcune cose sono più severe di prima; restano comunque in v1 perché nessuna integrazione era ancora in produzione. Se hai sviluppato su una versione precedente, controlla questi punti.

• Data di versione: Flavoso-Api-Version e api_version dei nuovi eventi indicano ora 2026-10-08. Gli eventi già consegnati o letti mantengono 2026-10-04.
• Dimensione del corpo: un corpo più grande di quanto l'operazione accetta (64 KB, 2 MB per PUT /menu, contati in byte) riceve 413 payload_too_large invece di 400 invalid_request.
• Ciò che è sconosciuto è un errore: un parametro di query o un campo del corpo sconosciuto dà 400 invalid_request con param, in ogni operazione.
• Timestamp con fuso orario: updated_since, created_since, starts_from e gli altri timestamp di una richiesta, anche until di POST /store/pause, devono avere Z o uno scostamento, altrimenti 400. Un + non codificato davanti allo scostamento nella query viene comunque accettato.
• La creazione risponde 201: POST /menu/categories, /menu/products, /menu/option-groups, /menu/option-groups/{id}/options e POST /store/closures per un giorno nuovo (200 se ne sostituisce uno).
• Accettare: POST /orders/{id}/accept porta un ordine pending allo stato successivo che il locale usa (non sempre confirmed); un ordine che ha già superato pending torna invariato con 200, uno completato o annullato risponde 409 invalid_transition.
• Opzioni negli ordini: items[].options[] riportano id, group_id e group_name (null per gli ordini più vecchi).
• Menu: nuovo GET /menu/options; la risposta di PUT /menu mette warnings prima di ids; un locale di prova conserva al massimo 50 immagini da image_url (oltre, PUT /menu avvisa con images_capped e un singolo piatto riceve 400), e reimpostarlo le elimina; menu.synced indica il connection_id che ha sincronizzato.
• Scritture contemporanee: una scrittura sul menu o sul locale (/store) che collide tre volte di seguito con un'altra modifica risponde 409 conflict con Retry-After invece di 500. In quel caso inviala di nuovo invariata.
• Eventi: GET /events con un after non più conservato riprende dall'evento conservato più vecchio e indica gap: true invece di rispondere 400; after=latest parte da adesso; next_after c'è sempre. data.object.updated_at negli eventi di ordini e prenotazioni è il momento della modifica segnalata. store.paused e store.resumed riportano il locale in object; store.updated segnala anche order_statuses; reservation.updated segnala anche una note modificata.
• Rifiutare invece di troncare: una note della pausa oltre 140 caratteri e un reason oltre 200 danno 400 con param invece di essere troncati.
• Permessi: GET /tables e GET /areas funzionano anche con reservations:read.
• Correzioni: order.paid non promette più pagamenti registrati in loco (Flavoso non ne registra); un token scaduto o revocato non conta più nel limite per indirizzo IP e riceve sempre 401; un PATCH /reservations/{id} che risponde 409 non ha cambiato nulla; un Idempotency-Key la cui prima richiesta non è mai terminata torna libero dopo 2 minuti; external_id segue ovunque la stessa regola (niente spazi all'inizio o alla fine, niente caratteri di controllo).

6 ottobre 2026: la piattaforma per sviluppatori#

La grande espansione: casse e altri sistemi ora possono curare il menu, prendere in carico gli ordini, gestire orari e prenotazioni e riconciliare il fatturato.

• Menu: PUT /menu sincronizza tutto il menu (merge, replace, dry_run); POST /menu/availability segnala fino a 500 voci in una volta; categorie, piatti, gruppi di opzioni e opzioni si possono creare, modificare ed eliminare singolarmente; image_url; ogni oggetto ha external_id e updated_at.
• Ordini: POST /orders/{id}/acknowledge prende in carico un ordine con un identificativo proprio; nuovi filtri paid, acknowledged, created_since, created_until, external_id; nuovi campi source, external_id, acknowledged_at e tax con le righe d'imposta.
• Locale: GET /store indica contatti, indirizzo, posizione, ordine minimo, tempi di preparazione, orari di consegna e i prossimi giorni speciali; novità: PATCH /store, GET e PUT /store/hours e i giorni speciali sotto /store/closures.
• Tavoli e aree: GET /tables, GET /areas.
• Prenotazioni: POST /reservations, PATCH /reservations/{id}, GET /reservations/availability; nuovi filtri starts_from e starts_until.
• Report: GET /reports/sales e GET /reports/products, con il nuovo permesso reports:read.
• Recuperare gli eventi: GET /events e GET /events/{id}. Gli eventi ora vengono generati per ogni collegamento attivo, anche senza webhook.
• Nuovi tipi di evento: order.paid, store.updated, app.scopes_changed, menu.category.*, menu.product.created e .deleted, menu.option_group.*, menu.option.created e .deleted, menu.synced (un evento per sincronizzazione). menu.product.updated e menu.option.updated arrivano a ogni modifica di un campo, con changed e previous.
• Prova e reale: livemode in GET /me e in ogni evento. GET /me indica inoltre tenant.country, plan e rate_limit.
• Errori: param indica il campo errato; nuovi codici external_id_taken, slot_unavailable, limit_exceeded.
• OAuth: un token di aggiornamento già scambiato viene ancora accettato per 60 secondi.
• Webhook: ogni consegna con ogni tentativo nella console, «Rinvia», eventi di prova di ogni tipo; Flavoso-Delivery-Attempt conta anche gli invii manuali.
• Strumenti: registro delle richieste, esploratore API, token di prova, elenco delle app, postman.json, un operationId su ogni operazione della specifica, e questa documentazione.

5 ottobre 2026: il nuovo indirizzo#

L'API ha ora un indirizzo tutto suo: https://api.flavoso.com. Token e risposte restano gli stessi, e i vecchi indirizzi continuano a funzionare. Devi intervenire solo se la tua app confronta iss con un valore fisso.

• Endpoint: ogni endpoint si trova sotto https://api.flavoso.com/v1, compresi openapi.json e postman.json.
• OAuth: token su https://api.flavoso.com/oauth/token, revoca su https://api.flavoso.com/oauth/revoke, metadati su https://api.flavoso.com/.well-known/oauth-authorization-server. La schermata di consenso resta su https://app.flavoso.com/oauth/authorize, perché è lì che il titolare accede.
• Emittente: issuer nei metadati e iss al ritorno sono ora https://api.flavoso.com invece di https://app.flavoso.com. Se la tua app confronta iss con un valore fisso, aggiornalo; meglio ancora, leggilo dai metadati.
• Vecchi indirizzi: https://app.flavoso.com/api/public/v1/… e https://app.flavoso.com/api/oauth/… continuano a rispondere; il vecchio indirizzo dei metadati reindirizza a quello nuovo.

4 ottobre 2026: la prima versione#

La prima versione di v1, con accesso tramite OAuth 2.0 e PKCE: leggere, accettare, rifiutare, annullare e far avanzare gli ordini; leggere il menu, segnalare esauriti e prezzi; mettere in pausa il locale; leggere le prenotazioni e impostarne lo stato; webhook firmati.