I tuoi dati
Clienti e storico degli ordini
Chi sono i tuoi clienti e che cosa hanno comprato: il «solito» dell'assistente.
A che cosa serve nella conversazione
Dallo storico degli ordini l'assistente conosce il «solito» di ogni cliente: i prodotti che compra, nella quantità dell'ultimo acquisto. Quando il cliente scrive «il latte», aggiunge quello di sempre e lo dice, invece di chiedergli di scegliere; «il solito» riordina in un colpo; un cliente che ha già ordinato non è trattato come nuovo (gli sconti di benvenuto e di bentornato ne dipendono).
Gli ordini confermati nella chat entrano da soli nello stesso storico. Lo storico che carichi si abbina al cliente solo dove l'identità è garantita: su WhatsApp (il canale verifica il numero) e, nella chat del tuo sito, solo per i clienti entrati nel tuo sito, con un gettone che il tuo server chiede (POST /v1/chat_identity_tokens). In una chat anonima un telefono scritto dal cliente non apre nessuno storico: altrimenti chiunque leggerebbe gli acquisti di un altro digitando il suo numero.
L'anagrafica dei clienti (codice, nome, telefono, email, indirizzo) lega lo storico ai tuoi clienti e permette al tuo server di aprire la chat a loro nome.
Cliente: Mettimi la solita pasta
Assistente: Ho messo il tuo solito: • Pasta Spaghetti n.5 500g [Barilla] 2x500g – €2,58 Ti serve altro?
Due confezioni, come nell'ultimo ordine del cliente nello storico. Esempio illustrativo, coi prodotti del modello e un negozio inventato.
Che cosa succede se manca
- Senza lo storico l'assistente non conosce il solito dei tuoi clienti e propone sempre una scelta.
- Un cliente che compra da te da anni è trattato come nuovo: sconto di benvenuto al posto del bentornato.
- Senza il codice cliente il tuo server non può aprire la chat del sito a nome del cliente.
- Gli ordini annullati non diventano abitudini: segnali «cancelled».
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.
order_refobbligatorio- Colonna nel file
- Codice ordine
- Tipo
- testo
- Esempio
ORD-1001 · ORD-1002- Regola
- obbligatorio, max 128 caratteri; le righe dello stesso ordine hanno lo stesso codice
customer_refconsigliato- Colonna nel file
- Codice cliente
- Tipo
- testo
- Esempio
CLI-0042- Regola
- il codice del cliente nel tuo gestionale (quello del file clienti); serve questo o il telefono
phoneconsigliato- Colonna nel file
- Telefono
- Tipo
- testo
- Esempio
+39 000 000 0001 · +39 000 000 0002- Regola
- internazionale, col prefisso del paese (+39…); serve questo o il codice cliente
order_dateobbligatorio- Colonna nel file
- Data ordine
- Tipo
- data
- Esempio
2026-10-01 · 15/10/2026- Regola
- AAAA-MM-GG o GG/MM/AAAA; consigliati gli ultimi 12 mesi
skuobbligatorio- Colonna nel file
- Codice
- Tipo
- testo
- Esempio
000201111 · 000301555- Regola
- il codice della referenza, lo stesso del catalogo; un codice che il catalogo non ha più vale per le abitudini, non per il carrello
titleconsigliato- Colonna nel file
- Nome prodotto
- Tipo
- testo
- Esempio
Pasta Spaghetti n.5 500g · Acqua naturale 6x1,5l- Regola
- max 512 caratteri
quantityobbligatorio- Colonna nel file
- Quantità
- Tipo
- numero
- Esempio
2 · 1 · 3- Regola
- maggiore di zero, nell’unità di vendita (le confezioni, le casse; i kg a peso)
unit_pricefacoltativo- Colonna nel file
- Prezzo unitario
- Tipo
- numero (¤)
- Esempio
1,29 · 3,30- Regola
- IVA inclusa, non negativo
statusfacoltativo- Colonna nel file
- Stato
- Tipo
- testo
- Esempio
delivered · cancelled- Regola
- delivered o cancelled; un ordine annullato non diventa abitudine
store_codefacoltativo- Colonna nel file
- Punto vendita
- Tipo
- testo
- Regola
- solo se hai più punti vendita, max 64 caratteri
delivery_datefacoltativo- Colonna nel file
- Data consegna
- Tipo
- data
- Esempio
2026-10-02- Regola
- AAAA-MM-GG o GG/MM/AAAA, una volta per ordine
delivery_slotfacoltativo- Colonna nel file
- Fascia consegna
- Tipo
- testo
- Esempio
09-13- Regola
- max 64 caratteri, una volta per ordine
order_totalfacoltativo- Colonna nel file
- Totale ordine
- Tipo
- numero (¤)
- Esempio
12,48 · 3,87- Regola
- IVA inclusa, una volta per ordine
payment_methodfacoltativo- Colonna nel file
- Pagamento
- Tipo
- testo
- Esempio
carta · contanti- Regola
- max 64 caratteri, una volta per ordine
Anagrafica dei clienti (PUT /v1/customers)
external_refobbligatorio- Tipo
- testo
- Esempio
CLI-0042- Regola
- Il codice del cliente nel tuo sistema: lo stesso «codice cliente» dello storico.
display_nameconsigliato- Tipo
- testo
- Esempio
Anna Esempio- Regola
- Nome e cognome.
phoneconsigliato- Tipo
- E.164
- Esempio
+39 000 000 0001- Regola
- Internazionale, col prefisso del paese.
emailfacoltativo- Tipo
- Esempio
anna@esempio.it- Regola
- —
addressfacoltativo- Tipo
- oggetto
- Esempio
{"street":"Via Prova 1","city":"Borgo Prova"}- Regola
- Via, numero, città, codice postale.
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
TELEFONO_NON_E164«Il telefono vuole il prefisso internazionale (+39…).»(spiegazione di questa guida: Core restituisce il codice)
Che cosa fare: Scrivilo come +, prefisso del paese e numero.
ORDINE_SENZA_CLIENTE«La riga non ha né il codice cliente né il telefono.»(spiegazione di questa guida: Core restituisce il codice)
Che cosa fare: Ogni riga ne vuole uno dei due.
QUANTITA_NON_VALIDA«La quantità deve essere maggiore di zero.»(spiegazione di questa guida: Core restituisce il codice)
Che cosa fare: Nell'unità di vendita: confezioni, casse, o chili per i prodotti a peso.
DATA_NON_VALIDA«La data non si legge.»(spiegazione di questa guida: Core restituisce il codice)
Che cosa fare: Scrivi AAAA-MM-GG o GG/MM/AAAA.
Come mandarli
- Dal portaleIn arrivo
In arrivo: il file dello storico (CSV o Excel) dal portale.
- Dall'APIIn parte
Oggi: PUT /v1/customers (customers:write) per l'anagrafica e POST /v1/chat_identity_tokens (chat:write) per i clienti entrati nel tuo sito. PUT /v1/order_history esiste, ma il permesso history:write non si può ancora dare a una chiave dal portale.
Disponibilità misurata sul servizio vivo il 30 ottobre 2026.
Manda due clienti
curl
curl -X PUT "https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/customers" \
-H "Authorization: Bearer $GAI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: clienti-2026-11-02" \
-d '{"customers":[{"external_ref":"CLI-0042","display_name":"Anna Esempio","phone":"+390000000001"},{"external_ref":"CLI-0043","display_name":"Luca Esempio","phone":"+390000000002"}]}'Node.js (18+)
const risposta = await fetch("https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/customers", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.GAI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
customers: [
{ external_ref: "CLI-0042", display_name: "Anna Esempio", phone: "+390000000001" },
{ external_ref: "CLI-0043", display_name: "Luca Esempio", phone: "+390000000002" },
],
}),
});
console.log(risposta.status, await risposta.json());