AreaCacao Docs

Carica il tuo catalogo personalizzato di ingredienti da CSV/JSON (con modello, 3 modalità e anteprima) oppure scaricalo per backup e migrazione.

Che cos’è

La finestra Importa / Esporta ingredienti ti permette di caricare il tuo catalogo di ingredienti personalizzati da un file (in blocco, senza crearli uno per uno) oppure di scaricarlo per averlo fuori dall’applicazione.

L’importazione e l’esportazione agiscono solo sul catalogo personalizzato del tuo account, non sul catalogo pubblico internazionale. Lo precisa la finestra stessa: «Catalogo personalizzato del tuo account (non modifica il catalogo pubblico).». Il catalogo internazionale di oltre 10.000 ingredienti è in sola lettura e non viene modificato.

Percorso

Dal catalogo ingredienti, fai clic sul pulsante Importa / Esporta nell’intestazione. La finestra ha due sezioni: Importa ed Esporta.

Importa

Parti dal modello

Se non hai ancora un file, fai clic su Scarica modello CSV (nell’avviso «Non sai da dove iniziare? Scarica il modello con gli esempi e modificalo.»). Viene scaricato modello-ingredienti-areacacao.csv (il nome del file e il testo degli esempi sono nella lingua dell’interfaccia), già con l’intestazione corretta e due righe di esempio (Pralinato alla nocciola e Copertura fondente 70%) che puoi modificare o eliminare. I nomi delle colonne sono sempre gli stessi, in inglese.

Il modello include queste 24 colonne (tutte facoltative tranne name):

name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

Il modello non contiene la colonna id: in importazione non definisci l’identificativo, lo genera il sistema. (Il CSV che esporti include invece id — vedi Esporta —, ma quando lo reimporti quella colonna viene ignorata.)

Come preparare il CSV?

La finestra include una sezione espandibile Come preparare il CSV? con le regole. Nel dettaglio:

Solo name è obbligatorio. Lascia vuote le colonne per cui non hai dati.
I valori nutrizionali sono per 100 g (come nella scheda).
Separatore decimale: sono accettati punto o virgola (18.50 o 18,50, formato italiano compreso). Se usi la virgola come decimale, il punto viene interpretato come separatore delle migliaia (1.234,56 si legge milleduecentotrentaquattro virgola cinquantasei).
allergens: elenco di codici separati da ;. I codici validi sono i 14 ufficiali dell’UE: gluten, crustaceans, eggs, fish, peanuts, soy, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs. Qualsiasi codice fuori da questo elenco viene ignorato. Vedi Allergeni UE-14.
allergens vuoto = senza allergeni. Se non li conosci ancora, scrivi undeclared (è accettato anche sin declarar): nella scheda gli allergeni risultano non dichiarati, che non equivale a «senza allergeni».
alcohol: grammi di etanolo per 100 g (vini e liquori). Vuoto = dato mancante.
I micronutrienti (vitamine, minerali, colesterolo, caffeina) non si caricano tramite CSV: si compilano nella scheda dell’ingrediente. (Se ti servono in un file, usa il formato JSON, che li conserva.)

Carica i dati

Hai tre modi per fornire il contenuto:

Trascinare e rilasciare un file nell’area «Trascina qui un file CSV o JSON».
Fare clic su Scegli file e selezionare un .csv o un .json dal tuo computer.
Espandere Oppure incolla il testo manualmente e incollare direttamente il contenuto.

L’applicazione rileva il formato automaticamente (se il testo inizia con { o [ lo tratta come JSON, altrimenti come CSV) e lo mostra nel selettore Formato rilevato, che puoi correggere a mano se necessario. I selettori Formato rilevato e Modalità e i pulsanti compaiono non appena è stato caricato del contenuto.

Scegli la modalità

Il selettore Modalità stabilisce come viene applicata l’importazione. L’abbinamento con i tuoi ingredienti esistenti avviene per nome (senza distinguere tra maiuscole e minuscole):

Modalità	Che cosa fa
Crea solo nuovi (consigliata, predefinita)	Aggiunge gli ingredienti il cui nome non esiste e salta quelli che hai già (senza modificarli). Salta anche i nomi delle schede che hai eliminato: restano eliminate.
Crea o aggiorna (per nome)	Aggiunge i nuovi e sovrascrive con i dati del file gli esistenti che corrispondono per nome. Se il nome corrisponde a una scheda che hai eliminato, la recupera con i dati del file.
Sostituisci tutto (elimina gli esistenti)	Rimuove tutti i tuoi ingredienti personalizzati e poi importa quelli del file (riattivando per nome quelli che ricompaiono).

La modalità Sostituisci tutto è distruttiva: rimuove tutti i tuoi ingredienti personalizzati prima di importare. La finestra ti avvisa («Attenzione: questa opzione eliminerà TUTTI i tuoi ingredienti personalizzati esistenti prima dell’importazione. Azione irreversibile.») e, quando fai clic su Importa, chiede un’ulteriore conferma («replace_all ELIMINERÀ tutti i tuoi ingredienti personalizzati esistenti prima dell’importazione. Vuoi continuare?»). L’eliminazione è logica (soft-delete), quindi le ricette che già usavano quegli ingredienti continuano a mostrarne la scheda e a funzionare; però quelli che non sono nel file non compariranno più in I miei ingredienti.

Visualizza l’anteprima e conferma

Anteprima (simulazione)

Fai clic su Anteprima per eseguire una simulazione senza salvare nulla. Vedrai i contatori Totale, Nuovi, Aggiornati, Ignorati ed Errori e, se presenti, il dettaglio delle prime cinque righe con errori («Riga N: …»). Dopo l’anteprima il pulsante diventa Ricalcola anteprima, nel caso tu modifichi il contenuto o la modalità.

Importa (reale)

Se l’anteprima è corretta, fai clic su Importa per applicare le modifiche. Al termine vedrai il riquadro Importazione completata con il risultato reale: Aggiunti, Aggiornati, Ignorati ed Errori. L’elenco I miei ingredienti viene ricaricato quando entri in quella sezione: se ci eri già, passa a Catalogo e torna indietro, oppure ricarica la pagina, per vedere le modifiche.

Che cosa viene importato da ogni riga

Vengono riconosciuti questi campi: name (obbligatorio), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (predefinito g), densityGPerMl, weightPerUnitG, i 12 valori nutrizionali (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol), allergens e notes. Le intestazioni non distinguono tra maiuscole e minuscole e sono accettati alcuni alias (customCode/custom_code, baseUnit/base_unit/unit). Qualsiasi colonna non presente nell’elenco viene ignorata senza errori.

Errori che potresti vedere:

Una riga senza nome viene saltata e segnalata come «Riga N: Manca il nome».
Un file malformato viene rifiutato per intero: «CSV vuoto o senza righe», «JSON non valido: …» o «JSON: array “ingredients” non trovato».

Questi messaggi sono inviati dal server nella lingua dell’interfaccia. In «JSON non valido: …», il dettaglio tecnico dopo i due punti è riportato così come lo fornisce il parser JSON, di solito in inglese.

Esporta

Nella sezione Esporta («Scarica il tuo catalogo personalizzato. Il formato JSON conserva le strutture complesse (macronutrienti, allergeni); il CSV è ideale per modificarlo in Excel/Sheets.») hai due opzioni di download diretto. Vengono esportati solo i tuoi ingredienti attivi (quelli eliminati non sono inclusi).

Esporta in JSON

«Formato completo per backup o migrazione su un’altra istanza.» Scarica la scheda completa di ogni ingrediente così come è salvata, compreso ciò che il CSV non rappresenta: micronutrienti (contenuti in macros), nomi alternativi e campi personalizzati. È il formato consigliato per il backup. La struttura è:

{
  "version": 1,
  "exportedAt": "2026-06-01T…Z",
  "count": 12,
  "ingredients": [
    { "id": "ci_…", "name": "…", "macros": { "fat": 42, "vitaminE": 5 }, "allergens": ["nuts"], "altNames": [], "customFields": {} }
  ]
}

Ogni oggetto di ingredients è la scheda completa dell’ingrediente (qui abbreviata).

Quando reimporti un JSON (per esempio per migrare su un altro account in modalità Crea o aggiorna) vengono ripristinati i dati di base, i macronutrienti e micronutrienti e gli allergeni (un "allergens": null torna come non dichiarati; se manca la chiave allergens, la scheda risulta senza allergeni), ma non i nomi alternativi, i campi personalizzati né la dichiarazione dei conservanti, che dovrai reinserire. Per un backup integrale, conserva il file JSON originale.

Esporta in CSV

«Tabella semplice da aprire in Excel/Sheets/Numbers.» Scarica una tabella semplice (file custom-ingredients-AAAA-MM-GG.csv) ideale da controllare o modificare in un foglio di calcolo. Il CSV include i macronutrienti ma non i micronutrienti (per quelli usa il JSON).

Colonne del CSV

La sezione espandibile Colonne CSV della finestra elenca le 25 colonne del file esportato, in questo ordine:

id, name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

La colonna allergens è un elenco separato da punto e virgola (per esempio gluten;milk); resta vuota se la scheda non ha allergeni e contiene undeclared se non sono dichiarati. L’unica differenza rispetto al modello di importazione è la colonna id (presente in esportazione, ignorata in importazione).

Note e limiti

Andata e ritorno per nome. Esportare e reimportare funziona: l’abbinamento avviene per nome, quindi la colonna id del CSV esportato non serve in reimportazione.
CSV o JSON. Usa il CSV per modifiche rapide in un foglio di calcolo (macronutrienti, senza micronutrienti); usa il JSON per il backup: è l’unico formato che include i micronutrienti. In reimportazione il JSON conserva macro e micronutrienti, ma non i nomi alternativi né i campi personalizzati.
Dimensioni. Non c’è un limite di righe, ma la richiesta è limitata a circa 5 MB. Per cataloghi molto grandi, dividi il file in più importazioni.
Privacy. Tutto agisce sul catalogo del tuo account; né l’importazione né l’esportazione toccano il catalogo pubblico.

Importa ed esporta