I tuoi dati
Catalogo
Ogni prodotto che l'assistente può vendere: nome, marca, prezzo dell'unità di vendita, formato netto, peso o confezione, giacenza.
A che cosa serve nella conversazione
È il listino che l'assistente legge a ogni richiesta. Cerca per nome, marca, reparto e codice a barre; legge il formato e il prezzo dell'unità di vendita; decide se un prodotto si vende a pezzi, a peso o solo a confezione intera; controlla se è disponibile. Ogni riga del carrello e ogni ordine che ti arriva porta il codice (sku) di una riga di questo file.
Il prezzo è sempre quello di ciò che il cliente mette nel carrello: la confezione, la cassa da sei, o il chilo per un prodotto a peso senza peso medio. Con «venduto a peso» e il peso medio del pezzo, «un chilo di mele» diventa il numero giusto di mele; con «pezzi per confezione» e «solo a confezione intera», «dieci bottiglie» diventano due casse da sei.
«Giacenza affidabile = no» è per il fresco a banco (carne, pesce, frutta) di cui non conti la giacenza: resta in vendita anche a giacenza zero.
Cliente: Mi aggiungi dieci bottiglie d'acqua naturale e un chilo di mele?
Assistente: Fatto! 🛒 • Acqua naturale 6x1,5l [Fonte Esempio] 2x6x1.5l – €6,60 • Mele Golden 4x250g (1kg) – €2,40 L'acqua si vende a casse da sei: per dieci bottiglie ti ho messo due casse (dodici bottiglie). Ti serve altro?
L'acqua ha «pezzi per confezione» 6 e «solo a confezione intera» sì; le mele sono a peso con peso medio del pezzo 0,25 kg. Esempio illustrativo, coi prodotti del modello e un negozio inventato.
Che cosa succede se manca
- Senza codice o senza nome la riga è scartata: per l'assistente il prodotto non esiste.
- Senza prezzo il prodotto non ha un importo: resta «da reperire» e il cliente non vede quanto costa.
- Senza marca la riga del carrello non la dice, e il cliente non riconosce il suo prodotto di sempre.
- Senza formato netto (quantità e unità) il formato viene dal nome; se il nome tace, la riga dice «conf.» e il cliente non sa quanto compra.
- Senza «venduto a peso» un prodotto a peso si vende come un pezzo: «un chilo di mele» diventa una mela.
- Senza peso medio del pezzo l'assistente non sa quanti pezzi fanno un chilo.
- Senza «pezzi per confezione» e «solo a confezione intera», «dieci bottiglie» non diventano casse.
- Senza «giacenza affidabile = no» sul fresco a banco, carne, pesce e frutta a giacenza zero risultano non disponibili.
- Senza reparto le righe del carrello non si raggruppano; senza sottoreparto non ci sono i link allo scaffale.
- Senza pagina del prodotto e immagine la risposta non ha né link né foto.
- Un prodotto che non vendi più resta in vendita finché non lo spegni («vendibile online» = no) o non mandi il file come catalogo intero.
I campi
Obbligatorio: senza, il prodotto non si vende come il cliente se l'aspetta. Consigliato: senza, c'è un ripiego dichiarato, ma l'esperienza è più povera. Facoltativo: un miglioramento.
skuobbligatorio- Colonna nel file
- Codice
- Tipo
- testo
- Esempio
000201111 · 000301555 · 000405020- Regola
- obbligatorio, unico nel file, max 128 caratteri, stabile nel tempo
titleobbligatorio- Colonna nel file
- Nome prodotto
- Tipo
- testo
- Esempio
Pasta Spaghetti n.5 500g · Acqua naturale 6x1,5l · Mele Golden- Regola
- obbligatorio, come lo legge il cliente, max 512 caratteri
brandobbligatorio- Colonna nel file
- Marca
- Tipo
- testo
- Esempio
Barilla · Fonte Esempio- Regola
- obbligatorio (vuoto = avviso, non rifiuto)
categoryconsigliato- Colonna nel file
- Reparto
- Tipo
- testo
- Esempio
Pasta e riso · Bevande · Frutta e verdura- Regola
- il reparto: raggruppa le righe del carrello
subcategoryconsigliato- Colonna nel file
- Sottoreparto
- Tipo
- testo
- Esempio
Pasta secca · Acqua · Frutta- Regola
- lo scaffale dentro il reparto
descriptionfacoltativo- Colonna nel file
- Descrizione estesa
- Tipo
- testo
- Esempio
Mele di montagna, calibro 75-80- Regola
- max 4.000 caratteri; non sostituisce il nome
gtinfacoltativo- Colonna nel file
- GTIN (EAN)
- Tipo
- testo
- Esempio
2000000000015 · 2000000000022- Regola
- 8, 12, 13 o 14 cifre con la cifra di controllo GS1
priceobbligatorio- Colonna nel file
- Prezzo di vendita
- Tipo
- numero (¤)
- Esempio
1,29 · 3,30 · 2,40- Regola
- IVA inclusa, dell'unità di vendita (la confezione, la cassa; il kg se a peso senza peso medio)
min_order_qtyobbligatorio- Colonna nel file
- Formato netto (quantità)
- Tipo
- numero
- Esempio
500 · 9 · 1- Regola
- > 0: il contenuto netto della confezione venduta; a peso, la quantità minima
min_order_unitobbligatorio- Colonna nel file
- Formato netto (unità)
- Tipo
- simbolo
- Esempio
g · l · kg- Regola
- uno di: kg g l ml cl pz
sold_by_weightobbligatorio- Colonna nel file
- Venduto a peso
- Tipo
- sì/no
- Esempio
no · sì- Regola
- sì/no: la quantità del carrello è in unità di peso medio
avg_piece_weight_kgconsigliato- Colonna nel file
- Peso medio del pezzo (kg)
- Tipo
- numero (kg)
- Esempio
0,25- Regola
- > 0, solo per i prodotti a peso: «1 kg» diventa un numero di pezzi
items_per_packobbligatorio- Colonna nel file
- Pezzi per confezione
- Tipo
- intero
- Esempio
1 · 6- Regola
- intero ≥ 1 (1 se non è un multipack)
pack_onlyconsigliato- Colonna nel file
- Solo a confezione intera
- Tipo
- sì/no
- Esempio
no · sì- Regola
- sì/no: si vende solo la confezione (acqua, birra): «10 bottiglie» diventano casse
stock_managedconsigliato- Colonna nel file
- Giacenza affidabile
- Tipo
- sì/no
- Esempio
sì · no- Regola
- sì/no: «no» per il fresco a banco, vendibile anche a giacenza 0
unit_pricefacoltativo- Colonna nel file
- Prezzo al kg o al litro
- Tipo
- numero (¤/kg ¤/l)
- Esempio
2,58 · 0,37- Regola
- > 0, come in etichetta; mai al posto del prezzo di vendita
gross_weight_kgfacoltativo- Colonna nel file
- Peso lordo (kg)
- Tipo
- numero (kg)
- Esempio
0,52 · 9,3- Regola
- > 0, collo compreso: pesa il carrello per il corriere e i colli pesanti
tare_kgfacoltativo- Colonna nel file
- Tara (kg)
- Tipo
- numero (kg)
- Esempio
0,02- Regola
- ≥ 0
vat_ratefacoltativo- Colonna nel file
- Aliquota IVA (%)
- Tipo
- numero (%)
- Esempio
4 · 10- Regola
- 0-100
linkconsigliato- Colonna nel file
- Pagina del prodotto
- Tipo
- indirizzo web
- Esempio
https://www.esempio.it/p/000201111- Regola
- https:// sul sito del negozio
image_linkconsigliato- Colonna nel file
- Immagine
- Tipo
- indirizzo web
- Esempio
https://www.esempio.it/img/000201111.jpg- Regola
- https://
diet_tagsfacoltativo- Colonna nel file
- Caratteristiche alimentari
- Tipo
- elenco
- Esempio
organic|local- Regola
- separate da |: organic vegan lactose_free gluten_free whole_grain local
is_onlineobbligatorio- Colonna nel file
- Vendibile online
- Tipo
- sì/no
- Esempio
sì- Regola
- sì/no (vuoto = sì)
stock_qtyobbligatorio- Colonna nel file
- Giacenza
- Tipo
- numero
- Esempio
120 · 40 · 0- Regola
- ≥ 0, nelle unità di vendita
Scarica il modello
La prima riga è l'intestazione; la seconda (con # in testa) descrive ogni colonna; le tre righe d'esempio cominciano anch'esse con # e non si importano. I nomi delle colonne si riconoscono in tutte e sei le lingue e col nome del campo.
Errori frequenti e il loro messaggio
SKU_MANCANTE«Manca il codice del prodotto.»
Che cosa fare: Ogni riga vuole il codice del tuo gestionale o della cassa, sempre lo stesso nel tempo.
TITLE_MANCANTE«Manca il nome del prodotto.»
Che cosa fare: Scrivi il nome come lo legge il cliente sullo scaffale.
PREZZO_NON_VALIDO«Il prezzo deve essere un numero, zero o più.»
Che cosa fare: Solo il numero, senza il simbolo della valuta: 1,29 o 1.29.
NUMERO_AMBIGUO«Questo numero si legge in due modi: scrivilo senza il punto delle migliaia, o con due decimali.»
Che cosa fare: Usa lo stesso separatore dei decimali in tutto il file e niente separatore delle migliaia.
BOOLEANO_NON_VALIDO«Qui serve sì o no.»
Che cosa fare: Scrivi sì/no (o 1/0) in «venduto a peso», «solo a confezione intera», «giacenza affidabile», «vendibile online».
UNITA_NON_AMMESSA«L'unità del formato netto deve essere una di: kg, g, l, ml, cl, pz.»(spiegazione di questa guida: Core restituisce il codice)
Che cosa fare: Le unità si scrivono col simbolo: GroceryAI non legge parole di nessuna lingua per capire un'unità.
GTIN_NON_VALIDO«Il codice a barre non è valido: controlla le cifre.»
Che cosa fare: 8, 12, 13 o 14 cifre con la cifra di controllo GS1; lascialo vuoto se non ce l'hai.
OFFERTA_SUPERIORE_AL_PREZZO«Il prezzo in offerta è più alto del prezzo: controlla le due colonne.»
Che cosa fare: Il prezzo di vendita è quello pieno; il prezzo d'offerta è quello più basso.
Come mandarli
- Dal portaleIn parte
Oggi: Prodotti → carica un file CSV; il modello della pagina ha codice, nome, prezzo, codice a barre, marca, reparto, giacenza e vendibile online, e l'anteprima mostra le righe da sistemare col numero e il motivo, prima di scrivere. In arrivo: il modello a 24 colonne di questa guida, il foglio Excel, le righe col # saltate e «il file è il catalogo intero».
- Dall'APIDisponibile
PUT /v1/products (permesso catalog:write), fino a 500 prodotti per lotto: ogni prodotto aggiorna solo i campi che porta; un campo mandato a null si toglie. DELETE /v1/products/{sku} ritira un prodotto (spento, mai cancellato). Le istantanee (POST /v1/products/snapshots) ritirano ciò che il catalogo intero non porta più.
- Feed programmatoDisponibile
PUT /v1/catalog/feed con l'indirizzo del tuo file: lo leggiamo ogni 24 ore (o ogni every_hours). Il nostro modello CSV o Excel, oppure il feed prodotti di Google Merchant / Meta Commerce (XML o TSV) così com'è.
Disponibilità misurata sul servizio vivo il 30 ottobre 2026.
Aggiorna due prodotti (cambiano solo i campi che mandi)
curl
curl -X PUT "https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/products" \
-H "Authorization: Bearer $GAI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: listino-2026-11-02" \
-d '{"products":[{"sku":"000201111","title":"Pasta Spaghetti n.5 500g","brand":"Barilla","price":1.29,"min_order_qty":500,"min_order_unit":"g","items_per_pack":1,"stock_qty":120},{"sku":"000301555","title":"Acqua naturale 6x1,5l","price":3.30,"items_per_pack":6,"pack_only":true}]}'Node.js (18+)
const risposta = await fetch("https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/products", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.GAI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
products: [
{ sku: "000201111", title: "Pasta Spaghetti n.5 500g", brand: "Barilla", price: 1.29,
min_order_qty: 500, min_order_unit: "g", items_per_pack: 1, stock_qty: 120 },
{ sku: "000301555", title: "Acqua naturale 6x1,5l", price: 3.3, items_per_pack: 6, pack_only: true },
],
}),
});
console.log(risposta.status, await risposta.json());