Passa al contenuto principale

Catalogo Prodotti: Creazione e Gestione

Il catalogo prodotti e gestito dal servizio products sul backend e sincronizzato con le casse Flutter tramite il meccanismo di sync delta. Ogni prodotto appartiene al database del tenant (t_{tenantId}) e viene identificato univocamente dal campo sku.

Tipologie di Prodotto​

Il sistema utilizza un modello universale (Universal Item Model) con diverse tipologie:

TipoCodiceDescrizione
PiattoDISHArticolo vendibile con possibile ricetta
MerceMERCHANDISEArticolo di rivendita (bottiglie, gadget)
Materia primaRAW_MATERIALIngrediente per ricette, non vendibile direttamente
ServizioSERVICEArticolo senza gestione magazzino (coperto, consegna)
KitKITComposizione di piu articoli venduta come unita

Ogni prodotto ha dei flag che ne determinano il comportamento:

  • isSaleable: visibile e vendibile in cassa
  • isStockable: movimentato a magazzino
  • isPurchasable: ordinabile ai fornitori
  • hasRecipe: ha una distinta base (BOM)

Creazione di un Prodotto​

Dalla Console Admin​

  1. Accedere a Catalogo > Prodotti > Nuovo Prodotto
  2. Compilare i campi obbligatori:
    • Nome (name): denominazione visualizzata in cassa
    • SKU (sku): codice univoco (es. PIZZA-MARG, BIRRA-66CL)
    • Prezzo (price): prezzo di vendita IVA inclusa
    • Aliquota IVA (vatRate): percentuale IVA (es. 10, 22)
    • Categoria (categoryId): slug della categoria (es. pizze, bevande)
    • Tipo (type): selezionare tra DISH, MERCHANDISE, SERVICE, etc.
  3. Campi opzionali consigliati:
    • Descrizione: testo descrittivo per app cliente e kiosk
    • Reparto fiscale (fiscalDepartmentId): per stampanti fiscali
    • Ordine visualizzazione (displayOrder): posizione nel catalogo
  4. Salvare. Il prodotto viene automaticamente sincronizzato con le casse.

Dati di Vendita (salesData)​

Il blocco salesData contiene informazioni avanzate per la vendita:

  • price: prezzo base
  • priceListId: listino prezzi associato
  • vatRate: aliquota IVA
  • barcodes: array di codici a barre (EAN-13, Code128) per la scansione in cassa

Dati Inventario (inventoryData)​

Per articoli con isStockable: true:

  • trackStock: abilita il tracciamento giacenze
  • valuationMethod: metodo di valutazione (FIFO, media ponderata)
  • reorderPoint: soglia per il riordino automatico

Immagini Prodotto​

Ogni prodotto puo avere un'immagine associata tramite il campo mediaId, che referenzia la collection media del tenant. Le immagini vengono sincronizzate sulle casse in formato compresso.

Per associare un'immagine:

  1. Dalla scheda prodotto, cliccare Carica immagine
  2. Selezionare il file (formati supportati: JPG, PNG, WebP)
  3. Il sistema genera automaticamente le varianti thumb (miniatura) e tablet (alta risoluzione)
  4. L'immagine appare sui tasti della cassa se productImageSettings.enabled e attivo nel layout

Disponibilita per Canale​

I prodotti possono essere visibili su canali diversi:

  • POS: vendita in cassa (default: attivo)
  • Comanda: ordini tavolo dal cameriere
  • Asporto: ordini takeaway/delivery
  • Kiosk: totem self-service
  • App cliente (Impronto You): ordinazione da app

La visibilita per canale si controlla tramite le impostazioni delle pagine nel layout cassa (PageSettings) e i flag displayInMenu e displayInKiosk nella categoria.

Ricerca e Filtri​

Il catalogo supporta ricerca full-text su nome, SKU e descrizione. I filtri disponibili sono:

  • categoryId: filtra per categoria (espande automaticamente alle sotto-categorie)
  • type: filtra per tipologia (DISH, MERCHANDISE, etc.)
  • active: mostra solo prodotti attivi o anche disattivati
  • search: ricerca testo libero

La paginazione usa i parametri page e pageSize (default: 50 articoli per pagina).

Import Massivo​

Per importare prodotti in blocco, utilizzare l'endpoint batch:

  1. Preparare un file CSV o Excel con le colonne: sku, name, price, vatRate, categoryId, type
  2. Dalla console admin, accedere a Catalogo > Import
  3. Caricare il file e mappare le colonne
  4. Il sistema esegue un upsert: aggiorna i prodotti esistenti (per SKU) e crea quelli nuovi

L'API products.batch accetta un array di oggetti e restituisce lo stato per ogni articolo (created, updated, error).

Traduzioni (i18n)​

Per ambienti multilingua, ogni prodotto supporta il campo translations:

{
  "translations": {
    "en": { "name": "Margherita Pizza", "description": "Tomato, mozzarella, basil" },
    "de": { "name": "Pizza Margherita", "description": "Tomate, Mozzarella, Basilikum" }
  },
  "defaultLocale": "it"
}

FAQ​

Come disattivo un prodotto senza eliminarlo? Impostare il campo active: false. Il prodotto non apparira piu in cassa ne nelle ricerche, ma resta nel database per lo storico ordini.

Come aggiungo un codice a barre per la scansione? Nel campo salesData.barcodes, aggiungere il codice EAN-13 o Code128. La cassa riconosce automaticamente il formato alla scansione.

Il catalogo si sincronizza in tempo reale? La sincronizzazione avviene tramite il meccanismo delta sync. Le casse scaricano solo i prodotti modificati dopo l'ultimo sync, minimizzando il traffico di rete.

Vedi Anche​

Questa pagina ti è stata utile?