Connettore R-Keeper

R-Keeper è l'implementazione di riferimento live del contratto di connettore POS di Fooodo — l'unico connettore attivo in produzione oggi, e la forma su cui si allinea ogni connettore aggiuntivo. Il contratto stesso è indipendente dal POS; i nuovi connettori vengono definiti per cliente e quotati su richiesta. Questa pagina documenta come funziona effettivamente il ciclo completo di R-Keeper: quali dati attraversano il confine, in quale direzione, e cosa aspettarsi quando qualcosa va storto. I nomi dei metodi specifici di POS riportati di seguito appartengono a R-Keeper; gli equivalenti su altri connettori si mappano sulle stesse operazioni del contratto di connettore.

Cosa chiede Fooodo a R-Keeper

Queste sono chiamate di sola lettura — Fooodo non modifica mai il menu, i prezzi, i modificatori o i dati di riferimento di R-Keeper.

Cosa scrive Fooodo su R-Keeper

La creazione dell'ordine e la marcatura come pagato sono le due scritture che si trovano sul percorso critico; entrambe vengono accodate, ritentate con backoff esponenziale e registrate in dettaglio. Le altre due sono supplementari.

Configurazione per ristorante

Le credenziali di R-Keeper risiedono nella configurazione del ristorante. Ogni ristorante in Fooodo contiene:

• URL dell'endpoint API
• ID del ristorante all'interno di R-Keeper
• Endpoint opzionale per i prezzi fedeltà
• Codice opzionale del programma carta fedeltà
• Codice opzionale della voce di menu per l'instradamento delle mance

Ristoranti diversi nella stessa azienda Fooodo possono puntare a istanze R-Keeper diverse. È così che operano oggi le catene multi-sede.

Cadenze di sincronizzazione di R-Keeper

L'integrazione esegue polling e push secondo alcune cadenze diverse. Gli operatori e i tecnici del supporto partner si preoccupano di queste perché stabiliscono le aspettative su quanto rapidamente una modifica nel back-office appare nell'app rivolta al cliente — e quanto rapidamente un ordine del cliente appare al terminale.

Le scritture da Fooodo a R-Keeper non sono pianificate — vengono inviate non appena si verifica l'evento (ordine creato, ordine pagato, messaggio inviato) e vengono ritentate con backoff se R-Keeper le rifiuta. I budget di retry sono documentati nella sezione Gestione dei fallimenti di seguito.

Prezzi fedeltà per tavolo

I tavoli possono aderire ai prezzi fedeltà in due modi, e un ristorante può utilizzare entrambe le modalità contemporaneamente:

• Applicazione della carta a posteriori. Quando il tavolo è configurato con un codice carta fedeltà a livello di ristorante, Fooodo applica la carta dopo che l'ordine è stato esportato — R-Keeper ricalcola le voci con la logica di sconto della carta e Fooodo riflette i totali aggiornati all'ospite. L'ordine viene esportato una volta e poi aggiornato.
• Prezzi alternativi instradati tramite URL. Quando il tavolo è configurato con un URL del connettore per i prezzi fedeltà, Fooodo chiede a R-Keeper il menu con prezzi fedeltà prima che l'ospite veda i prezzi. Il carrello, i prezzi dei modificatori, i totali — tutto ciò che l'ospite vede è già il prezzo fedeltà. Questo è il percorso a latenza inferiore ed è quello che distribuiamo sulle nuove catene.

Qualunque modalità utilizzi un tavolo, gli sconti tramite codice coupon vengono applicati correttamente in aggiunta: un ospite con una carta fedeltà può comunque riscattare un coupon, e lo sconto del coupon raggiunge R-Keeper indipendentemente dal percorso fedeltà. Non è sempre stato così — le versioni precedenti condizionavano i coupon al percorso a posteriori e li saltavano sui tavoli instradati tramite URL — quindi i partner che effettuano l'onboarding da una distribuzione precedente dovrebbero verificare che il loro lato R-Keeper conteggi entrambi gli effetti.

I prezzi fedeltà provengono da R-Keeper. Fooodo non mantiene una tabella di sconti parallela.

Attribuzione del personale e degli ordini

Fooodo registra quale cameriere è associato a ciascun ordine in modo che i report amministrativi possano suddividere il servizio e le mance per membro del personale. Il flusso ha due componenti:

• La sincronizzazione della rubrica del personale viene eseguita ogni notte alle 08:45 e aggiorna l'elenco dei camerieri dal sistema del personale della catena — nomi, qualifiche e gli ID del personale esterni che si mappano su R-Keeper. I camerieri non vengono creati manualmente in Fooodo; l'elenco amministrativo è di sola lettura.
• L'attribuzione degli ordini avviene quando un ordine viene recuperato o aggiornato da R-Keeper. La risposta sullo stato dell'ordine di R-Keeper contiene l'ID del cameriere assegnato; Fooodo lo confronta con la rubrica del personale sincronizzata e scrive l'attribuzione sull'ordine. I figli della divisione del conto ereditano il cameriere del genitore.

Oggi questa attribuzione è visibile solo agli amministratori. La pagina di pagamento espone il cameriere sul lato operatore; non è ancora presente una scheda cameriere rivolta all'ospite nella conferma dell'ordine. Quella superficie è nella roadmap.

Gestione dei fallimenti

L'integrazione è progettata per tollerare brevi periodi di indisponibilità di R-Keeper. Tre modalità di fallimento che si verificano in pratica:

Ordini bloccati

R-Keeper restituisce codici di errore specifici (2219 o 13) quando un cameriere ha l'ordine aperto al terminale del back-office. La risposta di Fooodo:

• Contrassegna l'ordine come Locked
• Riprova l'esportazione con una pianificazione a backoff esponenziale (5 s → 10 s → 20 s → 40 s → 80 s — cinque tentativi, ~155 secondi in totale)
• Se tutti i tentativi falliscono, passa allo stato Error

In condizioni normali, i blocchi durano pochi secondi. Un blocco persistente di solito significa che un cameriere si è allontanato con l'ordine aperto a un terminale e la soluzione è chiuderlo direttamente in R-Keeper.

Retry per la marcatura come pagato

Quando R-Keeper rifiuta la chiamata PostPayOrder (il più delle volte perché l'ordine è bloccato a un terminale), Fooodo riprova con una pianificazione più lenta: 60 s → 120 s → 180 s → 240 s → 300 s — cinque tentativi nell'arco di ~17 minuti. La cadenza più lenta è deliberata: un ordine pagato è in fase di riconciliazione, non sta bloccando il servizio, quindi diamo a R-Keeper il tempo di liberarsi.

Se tutti e cinque i tentativi si esauriscono, l'ordine finisce in Error. Il pagamento Fooodo è comunque registrato; R-Keeper necessita di una rapida riconciliazione manuale da parte del cameriere.

Ristorante irraggiungibile

Se R-Keeper stesso è inattivo o il ristorante è andato offline, Fooodo porta automaticamente il ristorante in sola lettura (la verifica di disponibilità ogni minuto lo rileva):

• Il menu rivolto al cliente continua a caricarsi dalla cache — gli ospiti non vedono una pagina rotta
• I nuovi ordini vengono bloccati al checkout con un messaggio chiaro
• Gli ordini esistenti accodano gli aggiornamenti invece di eliminarli

Una volta che R-Keeper torna operativo, le operazioni accodate vengono elaborate e il ristorante torna alla normalità — senza alcun intervento dell'operatore.

Logging

L'integrazione scrive log strutturati su quattro livelli: il tracciato completo richiesta/risposta, un feed solo per i fallimenti, un feed per ordine e un feed per le transizioni di stato. Per i casi di supporto ai partner, il log delle richieste è il primo posto dove guardare — la causa più comune di "l'ordine non è arrivato in cucina" è un'interruzione momentanea di R-Keeper che il budget di retry non ha coperto, e il feed dei fallimenti la evidenzia immediatamente.

Modalità mock per lo sviluppo

Gli ambienti di sviluppo possono essere eseguiti con il traffico R-Keeper simulato end-to-end — utile per i partner integratori che vogliono testare l'app menu di Fooodo senza un'istanza R-Keeper live. Lo staging rispecchia la produzione colpendo l'ambiente di test di R-Keeper; la produzione non viene mai eseguita in modalità mock.

Cosa vede la cucina

Il contratto è: un ordine creato tramite Fooodo arriva in R-Keeper in modo indistinguibile da un ordine creato a un terminale. Stesso instradamento della stampante, stesso comportamento del KDS, stessi report. Il personale di cucina non ha bisogno di sapere che Fooodo esiste, e i camerieri continuano a usare R-Keeper esattamente come facevano prima.

Questo è intenzionale. L'integrazione è invisibile per design; il sistema operativo estende R-Keeper, non lo sostituisce.