Locale di prova

Che cos'è un locale di prova#

Un locale di prova è un ristorante su Flavoso che esiste solo per l'API. Non costa nulla, non richiede abbonamento e di base è aperto giorno e notte. Per l'API vale come piano Pro: tutti gli endpoint sono disponibili, prenotazioni comprese.

Ogni account ha al massimo un locale di prova, e tutte le tue app lo condividono. Include un menu di esempio con categorie, piatti e un gruppo di opzioni, più alcuni tavoli. Lo gestisci nella console, in Locale di prova, in cinque schede: Locale, Ordini, Prenotazioni, Menu ed Eventi.

Creare e usare#

1. 1

   Crea

   «Crea locale di prova»: un clic ed è pronto. Nell'assistente di configurazione è il secondo passo.

   Console › Locale di prova

2. 2

   Collega l'app

   Con un token di prova o con il flusso OAuth, scegliendo il locale di prova. Solo allora vengono generati eventi: senza un'app collegata con il permesso adatto, nessuno è in ascolto.

3. 3

   Prova

   Ordina e prenota come cliente, rispondi come locale: fai avanzare gli ordini, metti in pausa, cambia gli orari, segna i piatti come esauriti. Ogni modifica arriva come evento alle tue app collegate.

   Console › Locale di prova

Come un locale reale#

Per la tua app il locale di prova si comporta come un locale reale: stessi endpoint, stessi eventi, stessi errori. Ordini e prenotazioni di prova seguono lo stesso percorso di quelli di un cliente, e far avanzare un ordine nella console ha lo stesso effetto che in cucina. Ogni modifica arriva alla tua app come evento, via webhook o tramite GET /events. Ci sono tre differenze:

• livemode è false, in GET /me e in ogni evento. Un locale di prova non può mai andare online.
• I pagamenti online sono simulati: un ordine di prova che crei come pagato online genera order.created e subito dopo order.paid, senza fornitore di pagamento e senza denaro.
• Il locale di prova conserva al massimo 50 immagini da image_url. Oltre questo limite PUT /menu non ne scarica altre e avvisa con images_capped; reimpostarlo le elimina.

Gli strumenti#

Le schede del locale di prova nella console fanno ciò che altrimenti farebbero clienti, cucina, accoglienza e dashboard. Si aggiornano da sole appena qualcosa cambia nel locale di prova, anche quando è la tua app a fare la modifica tramite l'API.

Di più sugli strumenti della tua app in Strumenti.

Menu e sincronizzazione#

La scheda Menu mostra il menu del locale di prova esattamente come GET /menu lo restituisce a un'app collegata, con i suoi identificativi (external_id). Ciò che non ha alcun identificativo di quell'app è evidenziato: una sincronizzazione non lo tocca mai.

1. 1

   Assegna identificativi

   Per ogni oggetto senza identificativo inserisce un valore proposto come external_id della tua app, ad esempio demo-pizza-margherita. Piatti, prezzi e opzioni restano come sono, e non viene generato alcun evento.

   Console › Locale di prova › Menu

2. 2

   Sincronizzazione di esempio

   Un corpo pronto per PUT /menu con il menu com'è adesso, in merge o replace e sempre con dry_run. Da copiare o da aprire direttamente nell'esploratore API.

   Console › Locale di prova › Menu

3. 3

   Sincronizza

   La tua app invia il suo menu. Con gli identificativi assegnati, la sincronizzazione cambia solo ciò che differisce; una simulazione lo mostra prima.

4. 4

   Controlla

   «Ultime sincronizzazioni» mostra ogni PUT /menu delle tue app con modalità e riepilogo, accanto agli eventi menu.synced. Questi vengono generati solo quando una sincronizzazione cambia davvero qualcosa.

   Console › Locale di prova › Menu

«Reimposta il menu» svuota il menu o ricrea il menu di esempio; ordini, orari e collegamenti restano, le immagini scaricate da image_url vengono eliminate con il menu. Ogni categoria, piatto e gruppo eliminato segnala un menu.*.deleted (le opzioni spariscono insieme al loro gruppo), ogni nuovo oggetto un menu.*.created, anche ogni opzione. La console ti dice prima quanti eventi arriveranno. Come funziona la sincronizzazione è spiegato in Sincronizzare il menu.

Seguire gli eventi#

La scheda Eventi mostra gli ultimi 30 eventi del locale di prova. Per ogni app collegata indica cosa ne ha fatto il suo webhook (consegnato, in attesa del prossimo tentativo, fallito o saltato, con il motivo) e se l'ha già recuperato con GET /events.

• Busta: una riga si apre e mostra l'evento esattamente come lo riceve l'app scelta.
• Invia di nuovo: invia ancora una consegna, con lo stesso identificativo di evento.
• Invia al webhook: invia al webhook di un'app un evento senza consegna, ad esempio uno precedente alla configurazione del webhook o di un tipo a cui non è iscritto.
• Recupera da qui: copia la chiamata GET /events la cui risposta inizia esattamente con questo evento.

Al massimo dieci invii al minuto per app, contando «Rinvia» e «Invia un evento di prova» in Webhook. Gli eventi di prova e ping non compaiono mai in GET /events; la scheda lo indica nel punto giusto.

Reimpostare#

«Reimposta il locale di prova» cancella tutti gli ordini e le prenotazioni, ricrea il menu di esempio, termina una pausa, cancella i giorni speciali e riporta orari di apertura, tipi di ordine, tempi di preparazione, preordine, ordine minimo, mance, zona di consegna e prenotazioni come alla creazione. Le immagini scaricate da image_url vengono eliminate. Tavoli e collegamenti restano.

• Il menu genera gli stessi eventi di «Reimposta il menu»: ogni oggetto cancellato con menu.*.deleted, ogni nuovo con menu.*.created. Una cassa che rispecchia il menu vede così che i piatti con i suoi identificativi non ci sono più.
• Se cambiano orari, giorni speciali, tempi di preparazione, tipi di ordine, preordine o ordine minimo, arriva store.updated, e store.resumed se c'era una pausa in corso.
• Per ordini e prenotazioni cancellati non arriva alcun evento.

Puoi reimpostare al massimo cinque volte in dieci minuti, contando anche «Reimposta il menu».

Distinguere prova e reale#

livemode compare in GET /me e in ogni evento. Nel locale di prova è false, in ogni locale reale true. Controllalo nel punto in cui la tua app fa qualcosa di reale: un ordine di prova non deve finire in nessuna cassa reale.

// Test and live share one API, one address and one token format. livemode tells them apart.
const me = await fetch("https://api.flavoso.com/v1/me", {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then((r) => r.json());
if (!me.livemode) console.log(`Connected to the test restaurant "${me.tenant.name}"`);

// In the webhook handler: never book a test order into a real till
export function handleEvent(event) {
  if (!event.livemode) return handleTestEvent(event);
  return handleLiveEvent(event);
}

Provare con un locale reale#

Già prima dell'approvazione la tua app si collega anche ai locali di cui sei tu stesso titolare. È pensato per l'ultima prova con un menu reale.