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 connector 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 connector è 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 connector di riferimento che implementa questo contratto è in esecuzione in produzione su una catena multi-location; i nuovi connector 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 che voi ne costruiate.
• 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 connector 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 degli ordini in corso), e la gestione dei rimborsi si trova al di fuori del connector — 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 indicate coprono entrambi; la capacità di aggiungere articoli a un ordine aperto è ciò su cui il Pay-Later fa maggiore affidamento.

Il contratto è definito come operazioni, non come formato wire — il connector viene costruito per cliente rispetto all'interfaccia che già possedete. 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 indicate siano esposte in qualche modo.

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

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 (ad 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 sconti 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: il locale 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 il locale. 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 è importante, non solo la sua esistenza. La creazione degli ordini 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 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 Fooodo fa affidamento

L'integrazione è costruita per tollerare un POS brevemente non disponibile, e si basa sul fatto che il POS restituisca errori distinguibili:

• "L'ordine è bloccato / aperto a un terminale" deve essere distinguibile da un guasto grave. Il connector di riferimento riconosce codici di errore di blocco specifici e risponde ritentando con un breve backoff (circa cinque tentativi nell'arco di ~2,5 minuti) anziché restituire un errore. I rifiuti del contrassegno di pagato vengono ritentati con una pianificazione più lenta (~17 minuti) perché un ordine pagato è in fase di riconciliazione, non sta bloccando il servizio.
• Un POS irraggiungibile porta automaticamente la location in 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 nuovo tentativo 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 connector, a sistemi POS diversi. Valutate per la location con la connettività peggiore della catena, non per quella migliore.

Sicurezza

• Tutto il traffico del connector 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 connector, 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 lacune rispetto alle operazioni obbligatorie; 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 obbligatorie sopra indicate — lettura del menu, creazione dell'ordine, aggiunta di articoli a un ordine già aperto, contrassegno di 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 protetto?
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 nuovo tentativo 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 lo scopo della conversazione di scoping — diversi hanno più di una risposta valida.

Dalla valutazione a un connector live

1. Valutazione — il vostro team esamina questa guida, compila la checklist e confrontiamo le note. Di solito viene avviata da un cliente ristorante comune.
2. Scoping — una sessione di lavoro che mappa la vostra API al contratto del connector; le lacune ricevono opzioni. Fooodo definisce l'ambito e quota la propria build del connector per cliente, quando una catena si impegna; il lavoro necessario sul vostro lato viene dimensionato nella stessa conversazione, insieme all'accordo commerciale. È utile avere a portata di mano: 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 connector — viene consegnata durante l'onboarding.