Come caricare e aggiornare i dati

Gli stessi campi, con gli stessi nomi e le stesse regole, valgono nel file che carichi nel portale, nell'API e nel feed programmato. Le intestazioni si riconoscono in sei lingue e col nome del campo: lo stesso file funziona in qualunque lingua lavori il tuo personale. Quale via è disponibile oggi, famiglia per famiglia, lo dice la tabella in fondo a questa pagina e ogni pagina di famiglia.

Dal portale: carichi un file CSV o Excel, vedi l'anteprima (righe valide, righe da sistemare col numero e il motivo, che cosa cambierà) e confermi. Dall'API: il tuo sistema manda lotti fino a 500 elementi con una Idempotency-Key, così una chiamata ripetuta non fa niente due volte. Feed programmato: ci dai l'indirizzo del tuo file e lo leggiamo ogni giorno.

Ogni file, lotto o feed aggiorna ciò che porta e non cancella niente: un file con solo codice e prezzo cambia i prezzi e lascia formato, confezioni e offerte com'erano. Nell'API un campo mandato a null si toglie.

«Questo file è il catalogo intero»: i prodotti in vendita che il file non porta si ritirano (spenti, mai cancellati: gli ordini che li citano restano leggibili). L'anteprima ti dice prima quanti sono, e confermi con quel numero. Cancello di sicurezza: se il file porta meno del 90% dei prodotti in vendita non si ritira niente e la risposta lo dice: un file troncato non svuota il catalogo. Un prodotto ritirato che torna in un file successivo torna in vendita.

Freschezza: dichiara ogni quante ore aggiorni prezzi e giacenze (declared_refresh_hours); oltre il doppio senza aggiornamenti il catalogo risulta fermo (GET /v1/catalog/freshness).

Prodotti → prezzi e giacenze → offerte → zone → fasce → chiusure → clienti → storico degli ordini. Un file che rimanda a un codice non ancora caricato dà un errore su quella riga, non su tutto il file.

CSV col punto e virgola, UTF-8 (i modelli hanno il BOM, così Excel apre bene gli accenti); oppure il foglio Excel. Decimali con la virgola o col punto, uguali in tutto il file. Unità solo coi simboli: kg, g, l, ml, cl, pz. Sì/no: sì, no, 1, 0. Date AAAA-MM-GG o GG/MM/AAAA. Le righe che cominciano con # non si importano: sono le descrizioni e gli esempi del modello.

Ogni errore dice la riga, la colonna, il campo, un codice stabile (lo stesso fra file, API e portale) e un messaggio nella tua lingua. Le righe sbagliate non fermano le buone: le buone si scrivono, le altre si elencano col motivo, e sistemi solo quelle.

Le chiavi API sono di prova o del negozio aperto, e separano i dati: una chiave test vede solo il catalogo, i clienti e gli ordini di prova. Carica e controlla tutto in prova; il portale porta i prodotti di prova nel negozio aperto quando apri ai clienti.