> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zonal (Aztec)

> Collega Zonal Aztec POS a storekit per sync del menu, iniezione ordini con validazione del carrello, sync della planimetria per il dine-in e funzionalità pay-at-table completa.

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

<Note>
  Contatta il tuo account manager Zonal per richiedere le credenziali API iOrder. Serviranno il Brand Token e lo User Device Identifier per connettersi.
</Note>

## 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

| Dato                        | Sincronizzato                        |
| --------------------------- | ------------------------------------ |
| Categorie                   | Sì (dai display group)               |
| Prodotti                    | Sì                                   |
| Prezzi                      | Sì (inclusi i prezzi delle porzioni) |
| Descrizioni                 | Sì (dai display record)              |
| Immagini                    | Sì (caricate su CDN)                 |
| Modificatori (Choice Group) | Sì                                   |
| Modificatori nidificati     | Sì                                   |
| Varianti di taglia/porzione | Sì (come gruppo di modificatori)     |
| Portate                     | Sì (opzionale, come modificatore)    |
| Istruzioni di produzione    | Sì                                   |
| Allergeni                   | Solo flag alcolico                   |
| Calorie                     | Sì                                   |
| Disponibilità               | Sì (stato esaurito)                  |

### 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

| Impostazione                     | Descrizione                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| **Enable Coursing**              | Importa le opzioni di portata come gruppo di modificatori sui prodotti applicabili |
| **Enable Category Merge**        | Combina categorie con lo stesso nome da diverse sales area                         |
| **Subscreens as Categories**     | Tratta le subscreen Zonal come categorie top-level separate                        |
| **Import Choices With No Price** | Includi opzioni di modificatore che non hanno un prezzo di supplemento             |

<Note>
  Le istruzioni di produzione (articoli con `divisionId` di 0 o flag `isInstruction`) vengono importate automaticamente come modificatori gratuiti, anche se non hanno un prezzo di supplemento. Questo permette ai clienti di aggiungere istruzioni di preparazione speciali come "Senza ghiaccio" o "Extra caldo" ai loro ordini.
</Note>

### 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

| Fulfillment | Service ID Zonal | Note                                     |
| ----------- | ---------------- | ---------------------------------------- |
| Dine-in     | 1                | Include il numero di tavolo              |
| Pickup      | 2                | Include timeslot e codice di ritiro      |
| Delivery    | 5                | Include indirizzo di consegna e timeslot |

### 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.

<Warning>
  Se non è impostato un **Order Note Product ID**, storekit non invia alcuna riga per la nota — la nota del cliente viene salvata sull'ordine storekit ma non raggiunge mai Zonal o i ticket di cucina/bar che stampa. Questa è la causa abituale del problema "le note sono abilitate ma la cucina non le riceve" sui siti Zonal.
</Warning>

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](/docs/it/guides/orders/advanced/order-batching#customer-notes-on-batched-tickets)

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

| Impostazione               | Descrizione                                    |
| -------------------------- | ---------------------------------------------- |
| **Discount Percentage ID** | ID sconto Zonal per gli sconti percentuali     |
| **Discount Currency ID**   | ID sconto Zonal per gli sconti a importo fisso |

<Info>
  La validazione del carrello intercetta gli articoli non disponibili prima del pagamento. Se un articolo è esaurito, il cliente viene avvisato immediatamente.
</Info>

### 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

| Impostazione                     | Descrizione                                                  |
| -------------------------------- | ------------------------------------------------------------ |
| **Payment Method ID**            | Metodo di pagamento Zonal per gli ordini online              |
| **Order Note Product ID**        | Product ID usato per le note d'ordine sui ticket             |
| **Order Note Template**          | Template personalizzato per formattare le note d'ordine      |
| **Discount Percentage ID**       | ID sconto per gli sconti percentuali                         |
| **Discount Currency ID**         | ID sconto per gli sconti a importo fisso                     |
| **Enable Coursing**              | Consenti la selezione delle portate sui prodotti applicabili |
| **Enable Category Merge**        | Fondi categorie con lo stesso nome                           |
| **Import Choices With No Price** | Includi modificatori senza prezzo di supplemento             |

### 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:

| Impostazione                             | Descrizione                                                 |
| ---------------------------------------- | ----------------------------------------------------------- |
| **Fulfillment Sales Area ID – Pickup**   | Sales area ID Zonal da usare per gli ordini click & collect |
| **Fulfillment Sales Area ID – Delivery** | Sales area ID Zonal da usare per gli ordini delivery        |

<Note>
  Gli ordini dine-in utilizzano sempre il sales area ID dell'area del locale del tavolo (sincronizzato tramite planimetria). Le impostazioni fulfillment sales area ID si applicano solo agli ordini pickup e delivery che non hanno un tavolo assegnato.
</Note>

## 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](/docs/it/getting-started/contact-support).

## Funzionalità supportate

<AccordionGroup>
  <Accordion title="Sincronizzazione del menu">
    | Funzionalità                            | Supportata |
    | --------------------------------------- | :--------: |
    | Sincronizzazione automatica del menu    |      ✓     |
    | Sync leggera (solo prezzi)              |      ✓     |
    | Immagini prodotto                       |      ✓     |
    | Allergeni                               |      ✗     |
    | Calorie                                 |      ✓     |
    | Modificatori nidificati                 |      ✓     |
    | Sottocategorie                          |      ✗     |
    | Fasce orarie di disponibilità categoria |      ✗     |
    | Porzioni / taglie                       |      ✓     |
    | Portate                                 |      ✓     |
    | Restrizioni per sales area              |      ✓     |
    | Stato di stock                          |      ✓     |
  </Accordion>

  <Accordion title="Ordini">
    | Funzionalità                  | Supportata |
    | ----------------------------- | :--------: |
    | Iniezione ordini              |      ✓     |
    | Pre-ordini                    |      ✓     |
    | Buffering ordini              |      ✗     |
    | Validazione carrello          |      ✓     |
    | Auto-snooze articoli esauriti |      ✓     |
    | Sconti                        |      ✓     |
    | Mance                         |      ✗     |
    | Service charge                |      ✗     |
    | Note d'ordine personalizzate  |      ✓     |
    | Dettagli consegna             |      ✓     |
  </Accordion>

  <Accordion title="Pay at Table">
    | Funzionalità                            | Supportata |
    | --------------------------------------- | :--------: |
    | Sync conto in tempo reale               |      ✗     |
    | Applicare pagamenti al conto            |      ✗     |
    | Pagamenti divisi                        |      ✗     |
    | Tracciamento pagamenti da terminale POS |      ✗     |
    | Aggiungere a conto esistente            |      ✗     |
  </Accordion>

  <Accordion title="Configurazione locale">
    | Funzionalità                       | Supportata |
    | ---------------------------------- | :--------: |
    | Sync della planimetria             |      ✓     |
    | Aggiornamenti stock in tempo reale |      ✗     |
    | Supporto multi-sede                |      ✓     |
  </Accordion>
</AccordionGroup>


## Related topics

- [Assegnazione delle portate](/docs/it/guides/menu/course-assignments.md)
- [Modificatori di rimozione](/docs/it/guides/menu/removal-modifiers.md)
- [Modificatori gratuiti](/docs/it/guides/menu/free-modifiers.md)
- [Panoramica sulle integrazioni](/docs/it/guides/integrations/overview.md)
- [Modificatori nidificati storekit: setup e supporto POS](/docs/it/guides/menu/nested-modifiers.md)