POS integracijos reikalavimai

Fooodo yra svečiams skirtas užsakymų ir mokėjimų sluoksnis, veikiantis virš esamos POS sistemos. Svečiai užsisako ir moka prie stalo naudodami QR kodą; užsakymai įrašomi į POS per serverio pusės jungtį ir patenka ten lygiai taip pat, kaip užsakymai, įvesti terminale. POS sistema nekeičiama: ji išlieka meniu įrašų sistema ir virtuvės operacijų bei ataskaitų tiesos šaltiniu.

Šiame dokumente nurodoma, ko Fooodo integracija reikalauja iš POS sistemos — kokias operacijas turi atskleisti POS API, kokie yra duomenų lygmens lūkesčiai, prisijungimo ir našumo reikalavimai bei gedimų semantika — taip pat pateikiamas vertinimo kontrolinis sąrašas ir kelias iki gamybos paleidimo. Numatomas skaitytojas — POS tiekėjo inžinerinė komanda, vertinanti įgyvendinamumą ir pastangas.

Integracijos kryptis: Fooodo kviečia POS API. Jungtį įgyvendina ir eksploatuoja Fooodo; jūsų pusė teikia, dokumentuoja ir palaiko API paviršių, pasiekiamą iš Fooodo debesies. Jokia Fooodo programinė įranga nėra diegiama ar talpinama POS pusėje. Etaloninė jungtis, įgyvendinanti šią sutartį, veikia gamyboje kelių vietų tinkle; naujos jungtys apimamos kiekvienam klientui atskirai, kai tinklas pasirašo sutartį.

Kaip formuojama integracija

• Fooodo yra svečiams skirtas užsakymų ir mokėjimų sluoksnis; POS toliau valdo virtuvę — tie patys spausdintuvo maršrutai, ta pati KDS, tos pačios ataskaitos.
• Sutartis tokia: užsakymas, sukurtas per Fooodo, POS sistemoje pasirodo neatskiriamai nuo užsakymo, įvesto terminale. Virtuvės darbuotojams nereikia žinoti, kad Fooodo egzistuoja.
• Fooodo yra kviečiančioji pusė. Skaitymai apklausiami pagal grafiką (meniu, užsakymo būsena); įrašai siunčiami iš karto, kai įvyksta įvykis (sukurtas užsakymas, apmokėtas užsakymas). Fooodo nevartoja webhook'ų ar įvykių siuntimo iš POS — jums nereikia jų kurti.
• Jūsų pusė teikia, dokumentuoja ir palaiko API — Fooodo sukuria ir valdo visa kita.
• Etaloniniai duomenys yra tik skaitomi per ribą: Fooodo niekada nekeičia POS meniu, kainų, modifikatorių ar kitų pagrindinių duomenų.

Ką turi atskleisti jūsų POS sistema

Jungties sutartis apima keturias sritis — vietas, meniu, užsakymus ir mokėjimus. Konkrečiai, kaip operacijos — čia pavadintos bendrai; jūsų API turės savus pavadinimus:

Tai taip pat yra visas rašymo paviršius — per šią ribą nėra atšaukimo, anuliavimo ar grąžinimo rašymo. Anuliavimas vyksta POS terminale, kaip ir šiandien (Fooodo juos paima per vykstančio užsakymo atnaujinimą), o grąžinimų tvarkymas yra visiškai už jungties ribų — jis niekada neliečia jūsų API.

Fooodo vykdo du užsakymų srautus — Pay-First ir Pay-Later kelių raundų maitinimą vietoje, kai raundai pridedami prie atviro POS užsakymo ir apmokama pabaigoje (žr. fooodo.com/docs/order-flows). Aukščiau nurodytos operacijos apima abu srautus; labiausiai Pay-Later remiasi galimybe pridėti elementus prie atviro užsakymo.

Sutartis apibrėžiama kaip operacijos, o ne kaip laidų formatas — jungtis kuriama kiekvienam klientui atskirai pagal jau turimą sąsają. Jūsų API transportas ir formatas peržiūrimi apimties nustatymo metu; svarbiausia įgyvendinamumui yra tai, kad aukščiau nurodytos operacijos būtų atskleistos kokiu nors būdu.

Jei jūsų POS negali tiesiogiai atskleisti vienos iš privalomų operacijų, tai automatiškai nėra aklavietė — tai pirmasis dalykas, kurį nagrinėja apimties nustatymo skambutis.

Kaip atrodo duomenys

Duomenų lygmens lūkesčiai, kad jūsų komanda galėtų juos susieti su savo duomenų modeliu. (Laukų lygio schemos yra integracijos saugykloje, kurią partneriai gauna įvedimo metu.)

• Meniu — kategorijos, kuriose yra produktai; produktai turi kainas, mokesčių žymes, variantus (pvz., dydžius) ir modifikatorių grupes (ingredientų pridėjimas / pašalinimas / keitimas, kiekvienas su savo kaina). POS išlieka tiesos šaltiniu: Fooodo skaito šią struktūrą, niekada jos nerašo.
• Užsakymas — nuoroda į konkretų stalą konkrečioje vietoje; eilutės elementai su pasirinktu variantu, modifikatoriais ir kiekiais; sumos. Užsakymai gali būti papildomi, kol yra atviri (Pay-Later srautas prideda raundus prie atviro POS užsakymo), o nuolaidų ar lojalumo efektai atsispindi POS gaunamame užsakyme.
• Mokėjimas — žymė „apmokėta", pritaikyta esamam užsakymui. Arbatpinigiai gali būti nukreipti į nurodytą POS eilutę. Kortelės ar piniginės duomenys niekur šiame sraute nepasirodo.
• Būsena — vieta prisijungusi / atsijungusi; kiekvieno elemento prieinamumas (žymės „išparduota"); kiekvieno užsakymo būsena, įskaitant „užrakinta — atidaryta terminale". Iš POS gauti užsakymai gali turėti priskirto padavėjo identifikatorių, kurį Fooodo naudoja darbuotojų priskyrimui ataskaitose.

Prisijungimo reikalavimai

Tai dalis, nuo kurios priklauso dauguma vertinimų.

• Kiekvienos vietos POS API turi būti pasiekiama iš Fooodo debesies per internetą, naudojant HTTPS, stabiliu kiekvienos vietos URL. Fooodo konfigūracija kiekvienam restoranui saugo API galinį tašką ir vietos identifikatorių — tas galinis taškas turi atsakyti, kai Fooodo kviečia.
• Vietinė POS sistema: vietai reikia patikimo plačiajuosčio ryšio, o POS API turi būti atskleista Fooodo saugiu būdu — per jūsų tiekėjo debesies šliuzą, VPN tunelį arba sustiprintą atvirkštinį tarpinį serverį vietoje. Mechanizmas suderinamas apimties nustatymo metu; „POS pasiekiama tik iš vietinio tinklo" yra dažniausia spraga.
• Debesies POS: serveris su serveriu (S2S) ryšys tarp Fooodo debesies ir jūsų debesies API, su kiekvienos vietos kredencialais ir identifikatoriais.
• Svarbi ryšio kokybė, o ne tik jo buvimas. Užsakymo sukūrimas ir apmokėjimo žymėjimas yra svečio atsiskaitymo kritiniame kelyje, o prisijungimo / atsijungimo patikrinimas vykdomas kas minutę, kad Fooodo galėtų perjungti vietą į tik skaitymo režimą, kai tik POS tampa nepasiekiama. Ryšys, nutrūkstantis kelioms minutėms, tvarkomas grakščiai; ryšys, kuris visą dieną svyruoja, blogina svečių patirtį toje vietoje, nepriklausomai nuo integracijos kokybės.

Našumo ribos

Etaloninė diegimo versija vykdo šiuos ciklus kiekvienai vietai visą parą aptarnavimo metu:

Jūsų API turi palaikyti šią apklausą visoms prijungtoms vietoms vienu metu, o du kritinio kelio įrašai — sukurti užsakymą, pažymėti kaip apmokėtą — turi būti įvykdyti per kelias sekundes. Nepavykę įrašai kartojami pagal eksponentinio atsitraukimo grafiką, todėl momentinis atmetimas yra atkuriamas; lėtai veikiantis galinis taškas — ne.

Gedimų semantika, kuria remiasi Fooodo

Integracija sukurta taip, kad toleruotų trumpalaikį POS neprieinamumą, ir remiasi tuo, kad POS grąžina atskiriamas klaidas:

• „Užsakymas užrakintas / atidarytas terminale" turi būti atskiriamas nuo rimto gedimo. Etaloninė jungtis atpažįsta konkrečius užrakto klaidų kodus ir reaguoja kartodama su trumpu atsitraukimu (apie penkis bandymus per ~2,5 minutės), o ne grąžindama klaidą. Apmokėjimo žymėjimo atmetimai kartojami lėtesniu grafiku (~17 minučių), nes apmokėtas užsakymas suderinamas, o ne blokuoja aptarnavimą.
• Nepasiekiama POS automatiškai perjungia vietą į tik skaitymo režimą. Talpykloje esantis meniu vis dar įkeliamas svečiams, nauji užsakymai blokuojami atsiskaitymo metu su aiškiu pranešimu, o eilėje laukiantys atnaujinimai nusausina, kai POS grįžta — operatoriaus įsikišimo nereikia.
• Pakartoti įrašai turi būti saugūs. Fooodo kartoja nepavykusius užsakymų pateikimus; apimties nustatymo metu kartu patikriname, ar pakartojimas po skirtojo laiko pabaigos negali sukurti dvigubo užsakymo jūsų pusėje.

Kelių vietų tinklai

Fooodo sukurtas tinklams. Kiekvienas įmonės restoranas turi savo POS galinį tašką, vietos identifikatorių ir kredencialus — skirtingos vietos gali nurodyti skirtingus POS egzempliorius — ir, kuriant papildomas jungtis, skirtingas POS sistemas. Vertinkite pagal blogiausiai prijungtą tinklo vietą, o ne geriausią.

Saugumas

• Visas jungties srautas vyksta per HTTPS/TLS su kiekvienos vietos kredencialais. Kredencialų mechanizmas (API raktas, žetonas, OAuth, mTLS) suderinamas apimties nustatymo metu.
• Kortelės duomenys niekada neperžengia POS ribos. Mokėjimai vykdomi per atskirą Fooodo mokėjimų paslaugą (Mollie — kortelė, Apple Pay, Google Pay); jūsų POS gauna užsakymą ir vėliau žymę „apmokėta", bet niekada mokėjimo priemonės duomenų. Integracija neprideda jokių kortelės duomenų srautų prie jūsų POS.
• Platesnis Fooodo saugumo požiūris — šifravimas, subduomenų tvarkytojai, GDPR — dokumentuotas adresu fooodo.com/security.

Aplinkos ir testavimas

• Tikimasi jūsų POS bandomosios versijos. Fooodo bandomoji aplinka veikia prieš jūsų bandomąją aplinką; gamybos srautas jos niekada neliečia.
• Imitacijos režimas leidžia ankstyvajam kūrimui vykti prieš Fooodo meniu programą, kai POS srautas imituojamas nuo galo iki galo — naudinga prieš užmezgant bet kokį ryšį.
• Partneriai gauna integracijos saugyklą — visą jungties sutartį su versijų prisegimo informacija — įvedimo metu.

Vertinimo kontrolinis sąrašas

Jūsų pastangų įvertinimui: darbas jūsų pusėje paprastai sutelktas keturiose vietose — spragų šalinimas pagal privalomas operacijas; API atskleidimas kiekvienai vietai (žr. Prisijungimo reikalavimai); kiekvienos vietos identifikatorių ir kredencialų išdavimas; bandomosios aplinkos sukūrimas.

Jei galite atsakyti taip į šiuos klausimus, integracija labai tikėtinai yra įgyvendinama:

1. Ar jūsų POS atskleidžia API, apimančią privalomas aukščiau nurodytas operacijas — meniu skaitymą, užsakymo sukūrimą, elementų pridėjimą prie jau atviro užsakymo, apmokėjimo žymėjimą, vietos būseną?
2. Ar tas API gali būti pasiekiamas iš interneto per HTTPS kiekvienai vietai — tiekėjo debesis, S2S, VPN ar apsaugotas tarpinis serveris?
3. Ar kiekviena vieta turi stabilų identifikatorių ir kredencialus?
4. Ar API grąžina atskiriamas klaidas „užsakymas užrakintas terminale" ir rimtų gedimų atveju?
5. Ar jis gali palaikyti apklausą kas minutę kiekvienai vietai ir įvykdyti užsakymų įrašus per kelias sekundes?
6. Ar yra bandomoji aplinka, prieš kurią gali veikti Fooodo bandomoji versija?
7. Ar per API sukurti užsakymai virtuvėje elgiasi lygiai taip pat kaip terminalo užsakymai (spausdinimas, KDS, ataskaitos)?
8. Ar pakartotą užsakymo sukūrimą po skirtojo laiko pabaigos galima apsaugoti nuo dvigubo sukūrimo — idempotencijos raktu arba galimybe patikrinti, ar užsakymas jau egzistuoja?

„Ne" arba „neaišku" bet kuriame iš šių punktų yra kaip tik tai, kam skirtas apimties nustatymo pokalbis — kai kurie turi daugiau nei vieną tinkamą atsakymą.

Nuo vertinimo iki veikiančios jungties

1. Vertinimas — jūsų komanda peržiūri šį vadovą, užpildo kontrolinį sąrašą ir mes lyginame pastabas. Paprastai inicijuojamas bendro restorano kliento.
2. Apimties nustatymas — darbo sesija, kurioje jūsų API susiejama su jungties sutartimi; spragoms randami sprendimai. Fooodo nustato apimtį ir kainoraštį savo jungties kūrimui kiekvienam klientui atskirai, kai tinklas įsipareigoja; darbas, reikalingas jūsų pusėje, įvertinamas tame pačiame pokalbyje kartu su komerciniu susitarimu. Naudinga turėti paruoštą: jūsų API dokumentaciją, bandomosios aplinkos planą, kiekvienos vietos identifikatorius ir techninį kontaktą jūsų pusėje.
3. Kūrimas ir testavimas — kūrimas pradedamas imitacijos režimu, tada pereinama prie jūsų bandomosios aplinkos prieš Fooodo bandomąją versiją.
4. Bandomasis paleidimas ir diegimas — pirmiausia viena gyva vieta, tada visas tinklas.

Pradėti: siųskite savo kontrolinio sąrašo atsakymus ir apytikslį pastangų įvertinimą jūsų pusėje adresu partners@fooodo.com arba naudokite kūrėjų formą adresu fooodo.com/developers. Kūrimo lygio vaizdas — integracijos saugykla su visa jungties sutartimi — perduodamas įvedimo metu.