Zonal (Aztec)

Zonal (Aztec) è una delle integrazioni POS più complete disponibili su storekit. Offre la sincronizzazione completa del menu, l’iniezione automatica degli ordini con validazione del carrello, la sync della planimetria per il dine-in e il supporto per portate, taglie e modificatori nidificati.

​

Prerequisiti

Prima di connettere Zonal, assicurati di avere:

• Zonal Aztec POS con accesso alla API iOrder
• iOrder Brand Token dal tuo account manager Zonal
• iOrder User Device Identifier
• Accesso admin alla tua dashboard storekit

​

Configurazione della connessione

​

Passo 1: inserire le credenziali Zonal

1. Vai su Store Settings > Integrations nella tua dashboard storekit
2. Trova Zonal e clicca su Connect
3. Inserisci le tue credenziali iOrder:
   • Brand Token — il tuo token di autenticazione iOrder brand
   • User Device Identifier — il tuo identificatore univoco di device
   • Bundle Identifier (opzionale) — bundle ID personalizzato se fornito
4. Clicca su Connect

storekit verifica le credenziali con l’endpoint authCheck di Zonal prima di salvare.

​

Passo 2: selezionare il tuo locale

Dopo l’autenticazione:

1. storekit recupera i locali disponibili dal tuo account Zonal
2. Seleziona il locale (site) che corrisponde a questo store storekit
3. Il Site ID del locale viene salvato per tutte le future chiamate API

​

Passo 3: sincronizzare il menu

Una volta connesso, importa il tuo menu da Zonal:

1. Vai su Menu nella tua dashboard
2. Clicca su Sync Menu
3. storekit recupera i menu da tutte le sales area
4. Categorie e prodotti vengono importati con la struttura completa dei modificatori

​

Sincronizzazione del menu

​

Cosa viene sincronizzato

​

Tipi di sync

Sync completa: Importa la struttura completa del menu con categorie, prodotti, modificatori e immagini. Usa dopo modifiche significative al menu. Sync leggera: Aggiorna solo prezzi e disponibilità senza reimportare la struttura completa. Molto più veloce — ideale per frequenti modifiche di prezzo o aggiornamenti di stock.

​

Opzioni di sync

​

Restrizioni per sales area

I menu Zonal sono organizzati per sales area. Durante la sync, storekit:

1. Recupera i menu da tutte le sales area
2. Fonde i menu identici tra le aree
3. Crea restrizioni di area a livello di categoria

Questo significa che i prodotti possono essere disponibili in alcune aree e non in altre (es. menu diversi per bar vs ristorante).

​

Porzioni (taglie)

Quando un prodotto ha più porzioni in Zonal, storekit crea un gruppo di modificatori “Size”:

• Il prezzo base del prodotto viene impostato a £0
• Ogni porzione diventa un modificatore con il suo prezzo
• I clienti devono selezionare una taglia per aggiungere l’articolo

​

Iniezione degli ordini

Quando un cliente effettua un ordine, storekit lo invia a Zonal tramite il metodo placePaidOrder.

​

Flusso ordine

1. Validazione del carrello — storekit chiama checkBasket per validare gli articoli
2. Pagamento elaborato — il cliente paga tramite storekit
3. Ordine inviato — l’ordine viene inviato a Zonal con il basket ID
4. Conferma — Zonal restituisce il receipt ID, l’ordine viene marcato come accettato

​

Tipi di servizio

​

Invio dei pre-ordini

Per i pre-ordini, storekit calcola il momento ottimale di invio:

• Ordini in giornata: inviati immediatamente
• Ordini futuri: inviati alle 6 del mattino del giorno dell’ordine

Questo evita che gli ordini intasino la coda del tuo POS con giorni di anticipo.

​

Cosa riceve Zonal

Ogni ordine include:

• Nome, email e telefono del cliente
• Tutti gli articoli con ingredient ID, display record ID e tipo di porzione
• Modificatori come choice line con struttura nidificata
• Assegnazioni di portata (se configurate)
• Modificatori di rimozione (per articoli di default rimossi)
• Righe di sconto (percentuale o importo fisso)
• Importo della mancia
• Indirizzo di consegna (per ordini delivery)
• Timeslot (per pickup/delivery)
• Codice di ritiro (8 caratteri)
• Note d’ordine personalizzate (tramite prodotto note d’ordine)

​

Note d’ordine

Zonal accetta le note del cliente solo come voce di riga, quindi un Order Note Product ID deve essere configurato prima che le note possano comparire sui ticket Zonal. Vai su Stores → [il tuo store] → Settings → Integrations → Zonal e imposta Order Note Product ID con l’ID del prodotto Zonal che il tuo account manager Zonal fornisce per le note d’ordine. storekit aggiunge quindi una voce di riga usando quel prodotto con la nota formattata allegata. Le note vengono convertite in maiuscolo e ripulite dai caratteri che Zonal non può visualizzare, e vengono troncate a 840 caratteri. Usa Order Note Template per controllare come la nota viene composta. Anche due impostazioni storekit devono permettere il passaggio della nota:

• Stores → [il tuo store] → Settings → Operations → Order Notes deve essere Optional o Mandatory (non Hidden), altrimenti i clienti non hanno mai un campo note
• Se usi il batching degli ordini, Include order notes deve essere attivo, oppure le note vengono rimosse dall’ordine unito prima di essere inviate a Zonal — vedi Note del cliente sui ticket in batch

Il prodotto usato per le note d’ordine è escluso dalla sync del menu, quindi non compare mai nel tuo menu storekit.

​

Validazione del carrello e sconti

L’integrazione Zonal valida gli ordini al checkout utilizzando la API checkBasket.

​

Come funziona

1. Il cliente procede al checkout
2. storekit invia il carrello a Zonal con tutti gli articoli e modificatori
3. Zonal valida la disponibilità e calcola eventuali sconti
4. L’importo dello sconto viene restituito e applicato al totale dell’ordine
5. Il basket ID viene memorizzato e usato al momento dell’invio dell’ordine

​

Configurazione degli sconti

​

Auto-snooze in caso di errore

Se checkBasket restituisce un errore di sold-out (codice -216), storekit automaticamente:

1. Identifica l’articolo non disponibile
2. Lo mette in snooze per 6 ore
3. Svuota la cache del menu
4. Restituisce le informazioni sull’articolo al cliente

​

Sincronizzazione della planimetria

Sincronizza il layout dei tavoli da Zonal per l’ordinazione dine-in:

1. Vai su Stores → [il tuo store] → Settings → Integrations → Zonal
2. Clicca su Sync tables
3. Le aree (sales area) e i tavoli vengono importati

​

Cosa viene sincronizzato

• Sales area come aree del locale
• Gruppi di tavoli all’interno delle aree
• Singoli tavoli con numeri e nomi
• Capienza del tavolo

Le modifiche in Zonal si sincronizzano automaticamente — i nuovi tavoli vengono aggiunti, quelli rimossi vengono archiviati.

​

Impostazioni di integrazione

​

ID sales area per pickup e delivery

Di default, storekit utilizza il sales area ID 1 per gli ordini pickup e delivery. Se la tua configurazione Zonal richiede una sales area specifica per questi metodi di fulfillment, configurala utilizzando le impostazioni fulfillment sales area ID:

​

Testare l’integrazione

​

Checklist pre-lancio

1. Sincronizzazione del menu
   • Categorie importate da tutte le sales area
   • I prodotti hanno prezzi corretti (incluse le varianti di porzione)
   • I modificatori compaiono correttamente
   • I modificatori nidificati funzionano
   • Le immagini vengono visualizzate
2. Flusso ordine
   • Il carrello viene validato con successo
   • L’ordine compare nel POS Zonal
   • Articoli, modificatori e portate sono corretti
   • Codice di ritiro/timeslot compare
3. Sconti (se configurati)
   • Applica un codice sconto
   • Verifica che l’importo corrisponda al calcolo Zonal
4. Planimetria (se usi dine-in)
   • Tavoli sincronizzati correttamente
   • Gli ordini vengono instradati ai tavoli corretti

​

Troubleshooting

​

Connessione fallita

• Verifica che il Brand Token e lo User Device Identifier siano corretti
• Controlla che le credenziali non siano scadute
• Contatta il supporto Zonal per confermare l’accesso alla API iOrder

​

Il menu non si sincronizza

• Assicurati che i menu siano pubblicati in Zonal
• Controlla che i prodotti siano assegnati ai display group
• Verifica che le sales area siano configurate
• Controlla eventuali errori di sync nella dashboard

​

Ordini falliti

• “Missing basket ID”: la validazione del carrello potrebbe essere fallita — controlla la disponibilità degli articoli
• Errore -238: basket scaduto — storekit riproverà con un basket fresco
• Errore -216: articolo esaurito — l’articolo viene messo in auto-snooze

​

I modificatori non compaiono

• Controlla che i choice group siano configurati sui prodotti
• Verifica che i modificatori abbiano prezzi di supplemento (o abilita “Import Choices With No Price”)
• Ri-sincronizza il menu dopo modifiche in Zonal

​

Le note d’ordine non compaiono

• Controlla che Order Note Product ID sia impostato nelle impostazioni dell’integrazione Zonal — senza di esso non viene inviata alcuna riga di nota
• Controlla che Order Notes sotto Operations sia Optional o Mandatory, non Hidden
• Se il batching degli ordini è attivo, controlla che Include order notes sia abilitato
• Conferma che l’ID del prodotto per le note sia valido in Zonal — Zonal rifiuta la riga d’ordine se il prodotto non esiste

​

Prezzi sbagliati

• Controlla la configurazione delle porzioni in Zonal
• Verifica che sia impostata la porzione corretta come default
• Per prodotti multi-porzione, controlla i prezzi dei modificatori di taglia

Per ulteriore assistenza, contatta il supporto.

​

Funzionalità supportate