Requisiti di integrazione POS

Fooodo è uno strato di ordinazione e pagamento rivolto agli ospiti che opera sopra un POS esistente. Gli ospiti ordinano e pagano dal tavolo tramite QR; gli ordini vengono scritti nel POS attraverso un connettore lato server e arrivano in modo identico agli ordini inseriti a un terminale. Il POS non viene sostituito: rimane il sistema di riferimento per il menu e la fonte di verità per le operazioni di cucina e la reportistica.

Questo documento specifica cosa richiede un'integrazione Fooodo da un POS — le operazioni che l'API POS deve esporre, le aspettative sui dati a livello di entità, i requisiti di connettività e prestazioni, e la semantica dei guasti — seguiti da una checklist di valutazione e il percorso verso la produzione. Il lettore previsto è il team di ingegneria di un POS vendor che valuta la fattibilità e lo sforzo necessario.

Direzione dell'integrazione: Fooodo chiama l'API POS. Il connettore è implementato e gestito da Fooodo; la vostra parte fornisce, documenta e supporta una superficie API raggiungibile dal cloud di Fooodo. Nessun software Fooodo viene installato o ospitato sul lato POS. Un connettore di riferimento che implementa questo contratto è in esecuzione in produzione su una catena multi-location; i nuovi connettori vengono definiti per cliente nel momento in cui una catena firma.

Come è strutturata l'integrazione

• Fooodo è lo strato di ordinazione e pagamento rivolto agli ospiti; il POS continua a gestire la cucina — stesso instradamento delle stampanti, stesso KDS, stessi report.
• Il contratto è: un ordine creato tramite Fooodo arriva nel POS in modo indistinguibile da un ordine digitato a un terminale. Il personale di cucina non ha bisogno di sapere che Fooodo esiste.
• Fooodo è il lato chiamante. Le letture vengono eseguite tramite polling secondo una pianificazione (menu, stato degli ordini); le scritture vengono inviate nel momento in cui si verifica un evento (ordine creato, ordine pagato). Fooodo non consuma webhook o push di eventi dal POS — non è necessario costruirne.
• La vostra parte fornisce, documenta e supporta l'API — Fooodo costruisce e gestisce tutto il resto.
• I dati di riferimento sono di sola lettura attraverso il confine: Fooodo non modifica mai il menu POS, i prezzi, i modificatori o altri dati master.

Cosa deve esporre il vostro POS

Il contratto del connettore copre quattro domini — location, menu, ordini e pagamenti. In concreto, come operazioni — denominate genericamente qui; la vostra API avrà i propri nomi per esse:

Questa è anche la superficie di scrittura completa — non esiste nessuna scrittura di annullamento, storno o rimborso attraverso questo confine. Gli storni avvengono al terminale POS come avviene oggi (Fooodo li rileva tramite l'aggiornamento dell'ordine in corso), e la gestione dei rimborsi si trova al di fuori del connettore — non tocca mai la vostra API.

Fooodo gestisce due flussi di ordinazione — Pay-First e Pay-Later dine-in multi-round, dove i round vengono aggiunti a un ordine POS aperto e pagati alla fine (vedere fooodo.com/docs/order-flows). Le operazioni sopra coprono entrambi; la capacità di aggiungere a un ordine aperto è quella su cui Pay-Later fa maggiore affidamento.

Il contratto è definito come operazioni, non come formato wire — il connettore viene costruito per cliente rispetto all'interfaccia che già avete. Il trasporto e il formato della vostra API vengono esaminati durante la definizione dell'ambito; ciò che conta per la fattibilità è che le operazioni sopra siano esposte in qualche modo.

Se il vostro POS non riesce a esporre direttamente una delle operazioni richieste, questo non è automaticamente un vicolo cieco — è la prima cosa che una chiamata di scoping risolve.

Come appaiono i dati

Aspettative a livello di entità, in modo che il vostro team possa mapparle rispetto al proprio modello di dati. (Gli schemi a livello di campo si trovano nel repository di integrazione, che i partner ricevono durante l'onboarding.)

• Menu — categorie contenenti prodotti; i prodotti portano prezzi, flag fiscali, varianti (es. dimensioni) e gruppi di modificatori (aggiunta / rimozione / sostituzione di ingredienti, ciascuno con il proprio prezzo). Il POS rimane la fonte di verità: Fooodo legge questa struttura, non la scrive mai.
• Ordine — un riferimento a un tavolo specifico in una location specifica; voci con la variante scelta, i modificatori e le quantità; totali. Gli ordini possono essere integrati mentre sono aperti (il flusso Pay-Later aggiunge round a un ordine POS aperto), e gli effetti di sconto o fedeltà si riflettono nell'ordine che il POS riceve.
• Pagamento — un contrassegno "pagato" applicato a un ordine esistente. Le mance possono essere indirizzate a una voce designata nel POS. I dati di carta o wallet non compaiono mai in questo flusso.
• Stato — location online/offline; disponibilità per articolo (flag "esaurito"); stato per ordine, incluso "bloccato — aperto a un terminale". Gli ordini estratti dal POS possono portare l'identificatore del cameriere assegnato, che Fooodo utilizza per l'attribuzione al personale nei report.

Requisiti di connettività

Questa è la parte su cui si concentrano la maggior parte delle valutazioni.

• L'API POS di ogni location deve essere raggiungibile dal cloud di Fooodo tramite internet, via HTTPS, a un URL stabile per location. La configurazione di Fooodo contiene un endpoint API e un identificatore di location per ogni ristorante — quell'endpoint deve rispondere quando Fooodo chiama.
• POS on-premise: la sede ha bisogno di una connessione a banda larga affidabile, e l'API POS deve essere esposta a Fooodo in modo sicuro — tramite il vostro gateway cloud del vendor, un tunnel VPN, o un reverse proxy protetto presso la sede. Il meccanismo viene concordato durante la definizione dell'ambito; "il POS è raggiungibile solo dalla rete locale" è il gap più comune.
• POS cloud: una connessione server-to-server (S2S) tra il cloud di Fooodo e la vostra API cloud, con credenziali e identificatori per location.
• La qualità della connessione conta, non solo la sua esistenza. La creazione dell'ordine e il contrassegno di pagato si trovano sul percorso critico del checkout dell'ospite, e il controllo online/offline viene eseguito ogni minuto in modo che Fooodo possa portare la location in modalità sola lettura nel momento in cui il POS diventa irraggiungibile. Un collegamento che cade per qualche minuto viene gestito con grazia; un collegamento che fluttua tutto il giorno degrada l'esperienza dell'ospite in quella location, indipendentemente da quanto sia buona l'integrazione.

L'inviluppo di prestazioni

Il deployment di riferimento esegue queste cadenze per location, tutto il giorno durante il servizio:

La vostra API deve sostenere questo polling per ogni location connessa contemporaneamente, e le due scritture sul percorso critico — creazione ordine, contrassegno pagato — devono completarsi in pochi secondi. Le scritture che falliscono vengono ritentate con una pianificazione di backoff esponenziale, quindi un rifiuto momentaneo è recuperabile; un endpoint cronicamente lento non lo è.

Semantica dei guasti su cui si basa Fooodo

L'integrazione è costruita per tollerare una breve indisponibilità del POS, e si basa sul fatto che il POS restituisca errori distinguibili:

• "Ordine bloccato / aperto a un terminale" deve essere distinguibile da un guasto grave. Il connettore di riferimento riconosce specifici codici di errore di blocco e risponde ritentando con un breve backoff (circa cinque tentativi in ~2,5 minuti) invece di restituire un errore. I rifiuti del contrassegno di pagato vengono ritentati con una pianificazione più lenta (~15 minuti) perché un ordine pagato è in fase di riconciliazione, non sta bloccando il servizio.
• Un POS irraggiungibile porta automaticamente la location in modalità sola lettura. Il menu in cache si carica ancora per gli ospiti, i nuovi ordini vengono bloccati al checkout con un messaggio chiaro, e gli aggiornamenti in coda vengono elaborati quando il POS torna online — senza intervento dell'operatore.
• Le scritture ritentate devono essere sicure. Fooodo riprova le sottomissioni di ordini fallite; durante la definizione dell'ambito verifichiamo insieme che un retry dopo un timeout non possa creare un ordine duplicato sul vostro lato.

Catene multi-location

Fooodo è costruito per le catene. Ogni ristorante in un'azienda porta il proprio endpoint POS, identificatore di location e credenziali — location diverse possono puntare a istanze POS diverse — e, man mano che vengono costruiti ulteriori connettori, a sistemi POS diversi. Valutate per la location con la connettività peggiore della catena, non per la migliore.

Sicurezza

• Tutto il traffico del connettore viene eseguito su HTTPS/TLS, con credenziali per location. I meccanismi delle credenziali (chiave API, token, OAuth, mTLS) vengono concordati durante la definizione dell'ambito.
• I dati della carta non attraversano mai il confine POS. I pagamenti vengono elaborati tramite il servizio di pagamento separato di Fooodo (Mollie — carta, Apple Pay, Google Pay); il vostro POS riceve un ordine e successivamente un contrassegno "pagato", mai i dati dello strumento di pagamento. L'integrazione non aggiunge flussi di dati di carta al vostro POS.
• La postura di sicurezza più ampia di Fooodo — crittografia, sub-processor, GDPR — è documentata su fooodo.com/security.

Ambienti e test

• È prevista un'istanza di test del vostro POS. L'ambiente di staging di Fooodo viene eseguito rispetto al vostro ambiente di test; il traffico di produzione non lo tocca mai.
• La modalità mock consente allo sviluppo iniziale di essere eseguito rispetto all'app menu di Fooodo con il traffico POS simulato end-to-end — utile prima che sia disponibile qualsiasi connettività.
• I partner ricevono il repository di integrazione — il contratto completo del connettore, con il pinning della versione — durante l'onboarding.

Checklist di valutazione

Per la vostra stima dello sforzo, il lavoro sul vostro lato si concentra tipicamente in quattro aree: colmare eventuali gap rispetto alle operazioni richieste; esporre l'API per location (vedere Connettività); emettere identificatori e credenziali per location; e allestire un ambiente di test.

Se potete rispondere sì a queste domande, l'integrazione è molto probabilmente fattibile:

1. Il vostro POS espone un'API che copre le operazioni richieste sopra — lettura del menu, creazione dell'ordine, aggiunta di articoli a un ordine già aperto, contrassegno pagato, stato della location?
2. Quell'API può essere resa raggiungibile da internet tramite HTTPS per ogni location — cloud del vendor, S2S, VPN, o proxy sicuro?
3. Ogni location ha un identificatore stabile e delle credenziali?
4. L'API restituisce errori distinguibili per "ordine bloccato a un terminale" rispetto a guasti gravi?
5. Può sostenere il polling al minuto per location e completare le scritture degli ordini in pochi secondi?
6. Esiste un ambiente di test su cui lo staging di Fooodo può essere eseguito?
7. Gli ordini creati tramite API si comportano esattamente come gli ordini da terminale in cucina (stampa, KDS, report)?
8. Un retry di creazione ordine dopo un timeout può essere reso sicuro contro la doppia creazione — una chiave di idempotenza, o un modo per verificare se l'ordine esiste già?

Un "no" o "non sono sicuro" su uno qualsiasi di questi è esattamente l'argomento per cui esiste la conversazione di scoping — diversi hanno più di una risposta valida.

Dalla valutazione a un connettore live

1. Valutazione — il vostro team esamina questa guida, compila la checklist, e confrontiamo le note. Di solito viene avviata da un cliente ristorante condiviso.
2. Definizione dell'ambito — una sessione di lavoro che mappa la vostra API al contratto del connettore; i gap ricevono opzioni. Fooodo definisce l'ambito e quota la propria build del connettore per cliente, quando una catena si impegna; il lavoro necessario sul vostro lato viene dimensionato nella stessa conversazione, insieme all'accordo commerciale. È utile avere pronti: la documentazione della vostra API, un piano per l'ambiente di test, gli identificatori per location e un contatto tecnico sul vostro lato.
3. Build e test — lo sviluppo inizia in modalità mock, poi si sposta nel vostro ambiente di test rispetto allo staging di Fooodo.
4. Pilot e rollout — prima una location live, poi la catena.

Per iniziare: inviate le vostre risposte alla checklist e una stima approssimativa dello sforzo per il vostro lato a partners@fooodo.com, oppure utilizzate il modulo per sviluppatori su fooodo.com/developers. La vista a livello di build — il repository di integrazione con il contratto completo del connettore — viene consegnata durante l'onboarding.