Cerințe de integrare POS

Fooodo este un strat de comandă și plăți orientat către oaspeți, care funcționează deasupra unui POS existent. Oaspeții comandă și plătesc de la masă prin QR; comenzile sunt scrise în POS printr-un conector server-side și ajung identic cu comenzile introduse la un terminal. POS-ul nu este înlocuit: rămâne sistemul de evidență pentru meniu și sursa de adevăr pentru operațiunile de bucătărie și raportare.

Acest document specifică ce necesită o integrare Fooodo de la un POS — operațiunile pe care API-ul POS trebuie să le expună, așteptările privind datele la nivel de entitate, cerințele de conectivitate și performanță, precum și semantica eșecurilor — urmate de o listă de verificare pentru evaluare și calea spre producție. Cititorul vizat este echipa de inginerie a unui furnizor POS care evaluează fezabilitatea și efortul.

Direcția integrării: Fooodo apelează API-ul POS. Conectorul este implementat și operat de Fooodo; partea dumneavoastră furnizează, documentează și susține o suprafață API accesibilă din cloud-ul Fooodo. Niciun software Fooodo nu este instalat sau găzduit pe partea POS. Un conector de referință care implementează acest contract rulează în producție la un lanț cu mai multe locații; conectorii noi sunt dimensionați per-client odată ce un lanț semnează.

Cum este structurată integrarea

• Fooodo este stratul de comandă și plăți orientat către oaspeți; POS-ul continuă să gestioneze bucătăria — același routing de imprimantă, același KDS, aceleași rapoarte.
• Contractul este: o comandă creată prin Fooodo ajunge în POS în mod indistinguibil față de o comandă introdusă la un terminal. Personalul de bucătărie nu trebuie să știe că Fooodo există.
• Fooodo este partea care apelează. Citirile sunt interogate conform unui program (meniu, starea comenzii); scrierile sunt trimise în momentul în care are loc un eveniment (comandă creată, comandă plătită). Fooodo nu consumă webhook-uri sau push de evenimente din POS — nu trebuie să construiți niciunul.
• Partea dumneavoastră furnizează, documentează și susține API-ul — Fooodo construiește și rulează tot restul.
• Datele de referință sunt doar în citire peste limită: Fooodo nu modifică niciodată meniul POS, prețurile, modificatorii sau alte date master.

Ce trebuie să expună POS-ul dumneavoastră

Contractul conectorului acoperă patru domenii — locații, meniuri, comenzi și plăți. Concret, ca operațiuni — denumite generic aici; API-ul dumneavoastră va avea propriile denumiri pentru ele:

Aceasta este și suprafața completă de scriere — nu există nicio scriere de anulare, invalidare sau rambursare peste această limită. Invalidările au loc la terminalul POS, ca și până acum (Fooodo le preia prin reîmprospătarea comenzii în curs), iar gestionarea rambursărilor se află în afara conectorului în totalitate — nu atinge niciodată API-ul dumneavoastră.

Fooodo rulează două fluxuri de comandă — Pay-First și Pay-Later cu mai multe runde dine-in, unde rundele sunt adăugate la o comandă POS deschisă și plătite la final (consultați fooodo.com/docs/order-flows). Operațiunile de mai sus acoperă ambele fluxuri; capacitatea de adăugare la o comandă deschisă este cea pe care Pay-Later se bazează cel mai mult.

Contractul este definit ca operațiuni, nu ca format wire — conectorul este construit per-client față de interfața pe care o aveți deja. Transportul și formatul API-ului dumneavoastră sunt revizuite în timpul dimensionării; ceea ce contează pentru fezabilitate este că operațiunile de mai sus sunt expuse cumva.

Dacă POS-ul dumneavoastră nu poate expune direct una dintre operațiunile obligatorii, aceasta nu este automat un impas — este primul lucru pe care îl rezolvă un apel de dimensionare.

Cum arată datele

Așteptări la nivel de entitate, astfel încât echipa dumneavoastră să le poată mapa față de propriul model de date. (Schemele la nivel de câmp se află în repo-ul de integrare, pe care partenerii îl primesc în timpul onboarding-ului.)

• Meniu — categorii care conțin produse; produsele poartă prețuri, indicatori fiscali, variante (de ex. mărimi) și grupuri de modificatori (adăugare / eliminare / înlocuire ingredient, fiecare cu propriul preț). POS-ul rămâne sursa de adevăr: Fooodo citește această structură, nu o scrie niciodată.
• Comandă — o referință la o masă specifică dintr-o locație specifică; articole de linie cu varianta aleasă, modificatorii și cantitățile; totaluri. Comenzile pot fi completate cât timp sunt deschise (fluxul Pay-Later adaugă runde la o comandă POS deschisă), iar efectele de reducere sau fidelitate se reflectă în comanda pe care o primește POS-ul.
• Plată — un marcaj „plătit" aplicat unei comenzi existente. Bacșișurile pot fi direcționate către o linie desemnată în POS. Datele cardului sau ale portofelului electronic nu apar nicăieri în acest flux.
• Stare — locație online/offline; disponibilitate per articol (indicatori „epuizat"); stare per comandă, inclusiv „blocată — deschisă la un terminal". Comenzile preluate din POS pot purta identificatorul chelnerului atribuit, pe care Fooodo îl folosește pentru atribuirea personalului în rapoarte.

Cerințe de conectivitate

Aceasta este partea de care depind cele mai multe evaluări.

• API-ul POS al fiecărei locații trebuie să fie accesibil din cloud-ul Fooodo prin internet, prin HTTPS, la un URL stabil per locație. Configurația Fooodo conține un endpoint API și un identificator de locație pentru fiecare restaurant — acel endpoint trebuie să răspundă când Fooodo apelează.
• POS on-premise: locația are nevoie de o conexiune broadband fiabilă, iar API-ul POS trebuie expus către Fooodo într-un mod securizat — prin gateway-ul cloud al furnizorului dumneavoastră, un tunel VPN sau un reverse proxy întărit la locație. Mecanismul este convenit în timpul dimensionării; „POS-ul este accesibil doar din rețeaua locală" este cel mai frecvent decalaj.
• POS cloud: o conexiune server-to-server (S2S) între cloud-ul Fooodo și API-ul dumneavoastră cloud, cu credențiale și identificatori per locație.
• Calitatea conexiunii contează, nu doar existența ei. Crearea comenzii și marcarea ca plătită se află pe calea critică de checkout a oaspetelui, iar verificarea online/offline rulează în fiecare minut, astfel încât Fooodo să poată comuta locația în modul doar-citire în momentul în care POS-ul devine inaccesibil. O legătură care cade câteva minute este gestionată cu grație; o legătură care fluctuează toată ziua degradează experiența oaspetelui la acea locație, indiferent cât de bună este integrarea.

Anvelopa de performanță

Implementarea de referință rulează aceste cadențe per locație, non-stop în timpul serviciului:

API-ul dumneavoastră ar trebui să susțină această interogare pentru fiecare locație conectată în mod concurent, iar cele două scrieri pe calea critică — creare comandă, marcare ca plătită — ar trebui să se finalizeze în câteva secunde. Scrierile care eșuează sunt reîncercate conform unui program de backoff exponențial, astfel că o respingere momentană este recuperabilă; un endpoint cronic lent nu este.

Semantica eșecurilor pe care se bazează Fooodo

Integrarea este construită pentru a tolera un POS temporar indisponibil și se bazează pe faptul că POS-ul returnează erori distincte:

• „Comanda este blocată / deschisă la un terminal" trebuie să fie distingibilă de o eroare gravă. Conectorul de referință recunoaște coduri de eroare de blocare specifice și răspunde prin reîncercare cu un backoff scurt (aproximativ cinci încercări în ~2,5 minute), în loc să returneze o eroare. Respingerile de marcare ca plătită sunt reîncercate conform unui program mai lent (~17 minute), deoarece o comandă plătită se reconciliază, nu blochează serviciul.
• POS inaccesibil comută locația în modul doar-citire automat. Meniul din cache se încarcă în continuare pentru oaspeți, comenzile noi sunt blocate la checkout cu un mesaj clar, iar actualizările din coadă se golesc când POS-ul revine — fără intervenție din partea operatorului.
• Scrierile reîncercate trebuie să fie sigure. Fooodo reîncercă trimiterile de comenzi eșuate; în timpul dimensionării verificăm împreună că o reîncercare după un timeout nu poate crea dublu o comandă pe partea dumneavoastră.

Lanțuri cu mai multe locații

Fooodo este construit pentru lanțuri. Fiecare restaurant dintr-o companie are propriul endpoint POS, identificator de locație și credențiale — locații diferite pot indica instanțe POS diferite — și, pe măsură ce sunt construiți mai mulți conectori, sisteme POS diferite. Evaluați pentru locația cu cea mai slabă conectivitate din lanț, nu pentru cea mai bună.

Securitate

• Tot traficul conectorului rulează prin HTTPS/TLS, cu credențiale per locație. Mecanica credențialelor (cheie API, token, OAuth, mTLS) este convenită în timpul dimensionării.
• Datele cardului nu traversează niciodată limita POS. Plățile rulează prin serviciul de plăți separat al Fooodo (Mollie — card, Apple Pay, Google Pay); POS-ul dumneavoastră primește o comandă și ulterior un marcaj „plătit", niciodată datele instrumentului de plată. Integrarea nu adaugă niciun flux de date de card la POS-ul dumneavoastră.
• Postura de securitate mai largă a Fooodo — criptare, sub-procesatori, GDPR — este documentată la fooodo.com/security.

Medii și testare

• Se așteaptă o instanță de test a POS-ului dumneavoastră. Mediul de staging al Fooodo rulează față de mediul dumneavoastră de test; traficul de producție nu îl atinge niciodată.
• Modul mock permite dezvoltării timpurii să ruleze față de aplicația de meniu Fooodo cu traficul POS simulat end-to-end — util înainte ca orice conectivitate să fie în vigoare.
• Partenerii primesc repo-ul de integrare — contractul complet al conectorului, cu fixarea versiunii — în timpul onboarding-ului.

Lista de verificare pentru evaluare

Pentru estimarea efortului dumneavoastră, munca de pe partea dumneavoastră se concentrează de obicei în patru locuri: închiderea oricăror decalaje față de operațiunile obligatorii; expunerea API-ului per locație (consultați Conectivitate); emiterea de identificatori și credențiale per locație; și configurarea unui mediu de test.

Dacă puteți răspunde da la acestea, integrarea este foarte probabil fezabilă:

1. Expune POS-ul dumneavoastră un API care acoperă operațiunile obligatorii de mai sus — citire meniu, creare comandă, adăugarea de articole la o comandă deja deschisă, marcare ca plătită, stare locație?
2. Poate acel API fi făcut accesibil din internet prin HTTPS pentru fiecare locație — cloud vendor, S2S, VPN sau proxy securizat?
3. Are fiecare locație un identificator stabil și credențiale?
4. Returnează API-ul erori distincte pentru „comandă blocată la un terminal" față de erori grave?
5. Poate susține interogarea per minut per locație și poate finaliza scrierile de comenzi în câteva secunde?
6. Există un mediu de test față de care staging-ul Fooodo poate rula?
7. Se comportă comenzile create prin API exact ca comenzile de terminal în bucătărie (imprimare, KDS, rapoarte)?
8. Poate fi făcută sigură o reîncercare de creare-comandă după un timeout față de crearea dublă — o cheie de idempotență sau o modalitate de a verifica dacă comanda există deja?

Un „nu" sau „nu sunt sigur" la oricare dintre acestea este exact pentru ce este conversația de dimensionare — mai multe au mai mult de un răspuns viabil.

De la evaluare la un conector live

1. Evaluare — echipa dumneavoastră revizuiește acest ghid, completează lista de verificare și comparăm notele. De obicei declanșat de un client restaurant comun.
2. Dimensionare — o sesiune de lucru care mapează API-ul dumneavoastră față de contractul conectorului; decalajele primesc opțiuni. Fooodo dimensionează și cotează construirea conectorului per-client, când un lanț se angajează; munca necesară pe partea dumneavoastră este dimensionată în aceeași conversație, alături de aranjamentul comercial. Util de pregătit: documentația API, un plan de mediu de test, identificatori per locație și un contact tehnic pe partea dumneavoastră.
3. Construire și testare — dezvoltarea începe în modul mock, apoi trece la mediul dumneavoastră de test față de staging-ul Fooodo.
4. Pilot și lansare — o locație live mai întâi, apoi lanțul.

Pentru a începe: trimiteți răspunsurile la lista de verificare și o estimare aproximativă a efortului pentru partea dumneavoastră la partners@fooodo.com sau folosiți formularul pentru dezvoltatori la fooodo.com/developers. Vizualizarea la nivel de construire — repo-ul de integrare cu contractul complet al conectorului — este predată în timpul onboarding-ului.