Conector R-Keeper

R-Keeper este implementarea de referință live a contractului de conector POS al Fooodo — singurul conector care rulează în producție astăzi, și forma pe care orice conector suplimentar o adoptă. Contractul în sine este agnostic față de POS; conectorii noi sunt definiți per client și cotați la cerere. Această pagină documentează cum funcționează efectiv ciclul complet R-Keeper: ce date traversează granița, în ce direcție, și la ce să te aștepți când ceva nu merge bine. Numele metodelor specifice POS de mai jos aparțin R-Keeper; echivalentele de pe alți conectori se mapează la aceleași operațiuni ale contractului de conector.

Ce solicită Fooodo de la R-Keeper

Acestea sunt apeluri doar pentru citire — Fooodo nu modifică niciodată meniul, prețurile, modificatorii sau datele de referință din R-Keeper.

Ce scrie Fooodo în R-Keeper

Crearea comenzii și marcarea ca plătită sunt cele două scrieri care se află pe calea critică; ambele sunt puse în coadă, reîncercate cu backoff exponențial și înregistrate în detaliu. Celelalte două sunt suplimentare.

Configurare per restaurant

Credențialele R-Keeper se află în configurația restaurantului. Fiecare restaurant din Fooodo conține:

• URL-ul endpoint-ului API
• ID-ul restaurantului în R-Keeper
• Endpoint opțional pentru prețuri de fidelizare
• Cod opțional al programului de card de fidelizare
• Cod opțional al articolului de meniu pentru rutarea bacșișului

Restaurante diferite din aceeași companie Fooodo pot indica instanțe R-Keeper diferite. Acesta este modul în care lanțurile cu mai multe locații funcționează astăzi.

Cadrențele de sincronizare R-Keeper

Integrarea interogează și trimite date pe câteva programe diferite. Operatorii și inginerii de suport pentru parteneri sunt interesați de acestea deoarece stabilesc așteptările privind cât de repede apare o modificare din back-office în aplicația orientată spre client — și cât de repede apare o comandă a clientului la terminal.

Scrierile din Fooodo către R-Keeper nu sunt programate — sunt trimise imediat ce evenimentul are loc (comandă creată, comandă plătită, mesaj trimis) și sunt reîncercate cu backoff dacă R-Keeper le respinge. Bugetele de reîncercare sunt documentate în secțiunea Gestionarea eșecurilor de mai jos.

Prețuri de fidelizare per masă

Mesele pot opta pentru prețuri de fidelizare în două moduri, iar un restaurant poate rula ambele variante simultan:

• Aplicare card post-hoc. Când masa este configurată cu un cod de card de fidelizare la nivel de restaurant, Fooodo aplică cardul după exportul comenzii — R-Keeper recalculează articolele din linie cu logica de reducere a cardului, iar Fooodo reflectă totalurile ajustate înapoi către oaspete. Comanda este exportată o singură dată și apoi actualizată.
• Prețuri alternative rutate prin URL. Când masa este configurată cu un URL de conector pentru prețuri de fidelizare, Fooodo solicită de la R-Keeper meniul cu prețuri de fidelizare înainte ca oaspetele să vadă prețurile. Coșul, prețurile modificatorilor, totalurile — tot ceea ce vede oaspetele este deja prețul de fidelizare. Aceasta este calea cu latență mai mică și cea pe care o implementăm pe lanțurile noi.

Indiferent de varianta utilizată de o masă, reducerile prin cod de cupon sunt aplicate corect peste acestea: un oaspete cu card de fidelizare poate în continuare să valorifice un cupon, iar reducerea cuponului ajunge la R-Keeper independent de calea de fidelizare. Acest lucru nu a fost întotdeauna cazul — versiunile mai vechi condiționau cupoanele de calea post-hoc și le omitea pe mesele rutate prin URL — astfel că partenerii care migrează de pe o implementare mai veche ar trebui să verifice că partea lor R-Keeper contabilizează ambele efecte.

Prețurile de fidelizare provin din R-Keeper. Fooodo nu menține un tabel de reduceri paralel.

Atribuirea personalului și a comenzilor

Fooodo înregistrează care chelner este asociat cu fiecare comandă, astfel încât rapoartele de administrare să poată detalia serviciul și bacșișul pe angajat. Fluxul are două componente:

• Sincronizarea directorului de personal rulează nocturn la 08:45 și reîmprospătează lista de chelneri din sistemul de personal al lanțului — nume, funcții și ID-urile externe ale personalului care se mapează la R-Keeper. Chelnerii nu sunt creați manual în Fooodo; lista de administrare este doar pentru citire.
• Atribuirea comenzii are loc când o comandă este preluată sau actualizată din R-Keeper. Răspunsul de stare a comenzii din R-Keeper conține ID-ul chelnerului atribuit; Fooodo îl potrivește cu directorul de personal sincronizat și scrie atribuirea în comandă. Copiii unei comenzi împărțite moștenesc chelnerul comenzii-părinte.

În prezent, această atribuire este vizibilă doar în administrare. Pagina de plată expune chelnerul pe partea operatorului; nu există încă un card de chelner vizibil pentru oaspete pe confirmarea comenzii. Această funcționalitate este pe foaia de parcurs.

Gestionarea eșecurilor

Integrarea este proiectată să tolereze indisponibilitatea temporară a R-Keeper. Trei moduri de eșec pe care le vei întâlni în practică:

Comenzi blocate

R-Keeper returnează coduri de eroare specifice (2219 sau 13) când un chelner are comanda deschisă la terminalul din back-office. Răspunsul Fooodo:

• Marchează comanda ca Locked
• Reîncearcă exportul pe un program de backoff exponențial (5 s → 10 s → 20 s → 40 s → 80 s — cinci încercări, ~155 secunde total)
• Dacă toate reîncercările eșuează, escaladează la Error

În funcționarea normală, blocările durează câteva secunde. O blocare persistentă înseamnă de obicei că un chelner a plecat cu comanda deschisă la un terminal, iar soluția este să o închidă direct în R-Keeper.

Reîncercări marcare-plătit

Când R-Keeper respinge apelul PostPayOrder (cel mai adesea deoarece comanda este blocată la un terminal), Fooodo reîncearcă pe un program mai lent: 60 s → 120 s → 180 s → 240 s → 300 s — cinci încercări pe parcursul a ~17 minute. Cadența mai lentă este deliberată: o comandă plătită se reconciliază, nu blochează serviciul, deci îi acordăm R-Keeper timp să se elibereze.

Dacă toate cele cinci reîncercări se epuizează, comanda ajunge în Error. Plata Fooodo este în continuare înregistrată; R-Keeper necesită o reconciliere manuală rapidă de către chelner.

Restaurant inaccesibil

Dacă R-Keeper însuși este oprit sau restaurantul a trecut offline, Fooodo comută restaurantul în mod doar-citire automat (verificarea de disponibilitate la fiecare minut o detectează):

• Meniul orientat spre client se încarcă în continuare din cache — oaspeții nu văd o pagină defectă
• Comenzile noi sunt blocate la checkout cu un mesaj clar
• Comenzile existente pun actualizările în coadă în loc să le abandoneze

Odată ce R-Keeper revine, operațiunile din coadă se procesează și restaurantul revine la normal — nu este necesară nicio intervenție din partea operatorului.

Jurnalizare

Integrarea scrie jurnale structurate la patru niveluri: traseul complet cerere/răspuns, un flux doar pentru eșecuri, un flux cu domeniu de comandă și un flux de tranziție a stărilor. Pentru cazurile de suport ale partenerilor, jurnalul de cereri este primul loc de verificat — cea mai frecventă cauză a „comanda nu a ajuns la bucătărie" este o întrerupere momentană a R-Keeper pe care bugetul de reîncercări nu a acoperit-o, iar fluxul de eșecuri o evidențiază imediat.

Modul mock pentru dezvoltare

Mediile de dezvoltare pot rula cu traficul R-Keeper simulat end-to-end — util pentru integratorii parteneri care doresc să testeze față de aplicația de meniu Fooodo fără o instanță R-Keeper live. Staging-ul oglindește producția prin accesarea mediului de test R-Keeper; producția nu rulează niciodată în modul mock.

Ce vede bucătăria

Contractul este: o comandă creată prin Fooodo ajunge în R-Keeper în mod indistinct față de o comandă creată la un terminal. Același rutaj de imprimantă, același comportament KDS, aceleași rapoarte. Personalul din bucătărie nu trebuie să știe că Fooodo există, iar chelnerii continuă să folosească R-Keeper exact cum o făceau înainte.

Acest lucru este intenționat. Integrarea este invizibilă prin design; sistemul de operare extinde R-Keeper, nu îl înlocuiește.