AreaCacao Docs

Carga tu catálogo personalizado de ingredientes desde CSV/JSON (con plantilla, 3 modos y previsualización) o descárgalo para backup y migración.

Qué es

El modal Importar / Exportar ingredientes te permite cargar tu propio catálogo de ingredientes personalizados desde un archivo (en lote, sin crearlos uno a uno) o descargarlo para tenerlo fuera de la aplicación.

Importar y exportar opera únicamente sobre tu catálogo personalizado de cuenta, no sobre el catálogo público global. El propio modal lo aclara: "Catálogo personalizado de tu cuenta (no afecta al catálogo público).". El catálogo global de más de 10.000 ingredientes es de solo lectura y no se ve afectado.

Ruta de acceso

Desde el catálogo de ingredientes, pulsa el botón Importar / Exportar de la cabecera. El modal tiene dos pestañas: Importar y Exportar.

Importar

Empieza con la plantilla

Si aún no tienes un archivo, pulsa Descargar plantilla CSV (en el aviso "¿No sabes por dónde empezar? Descarga la plantilla con ejemplos y edítala."). Se descarga plantilla-ingredientes-areacacao.csv (el nombre del archivo y el texto de los ejemplos van en el idioma de la interfaz), ya con la cabecera correcta y dos filas de ejemplo (Praliné de avellana y Cobertura negra 70%) que puedes editar o borrar. Los nombres de las columnas son siempre los mismos, en inglés.

La plantilla incluye estas 24 columnas (todas opcionales salvo 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

La plantilla no trae la columna id: al importar no defines el identificador, lo genera el sistema. (El CSV que exportas sí incluye id —ver Exportar—, pero al reimportarlo esa columna se ignora.)

¿Cómo preparar el CSV?

El modal incluye un desplegable ¿Cómo preparar el CSV? con las reglas. En detalle:

Solo name es obligatorio. Deja en blanco las columnas que no tengas.
Los valores nutricionales son por 100 g (igual que en la ficha).
Separador decimal: se acepta punto o coma (18.50 o 18,50, formato español incluido). Si usas coma como decimal, el punto se interpreta como separador de miles (1.234,56 se lee como mil doscientos treinta y cuatro con cincuenta y seis).
allergens: lista de códigos separados por ;. Los códigos válidos son los 14 oficiales de la UE: gluten, crustaceans, eggs, fish, peanuts, soy, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs. Cualquier código fuera de esta lista se ignora. Ver Alérgenos UE-14.
allergens vacío = sin alérgenos. Si todavía no los conoces, escribe undeclared (también se acepta sin declarar): la ficha queda con los alérgenos sin declarar, que no es lo mismo que «sin alérgenos».
alcohol: gramos de etanol por 100 g (vinos y licores). Vacío = sin dato.
Los micronutrientes (vitaminas, minerales, colesterol, cafeína) no se cargan por CSV: se rellenan en la ficha del ingrediente. (Si los necesitas en un archivo, usa el formato JSON, que sí los conserva.)

Cargar los datos

Tienes tres formas de aportar el contenido:

Arrastrar y soltar un archivo en la zona "Arrastra un archivo CSV o JSON aquí".
Pulsar Seleccionar archivo y elegir un .csv o .json de tu equipo.
Desplegar O pegar texto manualmente y pegar el contenido directamente.

La aplicación detecta el formato automáticamente (si el texto empieza por { o [ lo trata como JSON; si no, como CSV) y lo muestra en el selector Formato detectado, que puedes corregir a mano si hiciera falta. Los selectores Formato detectado y Modo y los botones aparecen en cuanto hay contenido cargado.

Elige el modo

El selector Modo decide cómo se aplica la importación. El emparejamiento con tus ingredientes existentes se hace por nombre (sin distinguir mayúsculas/minúsculas):

Modo	Qué hace
Solo crear nuevos (recomendado, por defecto)	Añade los ingredientes cuyo nombre no exista y salta los que ya tienes (no los toca). También salta los nombres de fichas que eliminaste: siguen eliminadas.
Crear o actualizar (por nombre)	Añade los nuevos y sobrescribe los existentes que coincidan por nombre con los datos del archivo. Si el nombre coincide con una ficha que eliminaste, la recupera con los datos del archivo.
Reemplazar todo (borra existentes)	Retira todos tus ingredientes personalizados y luego importa los del archivo (reactivando por nombre los que vuelvan a aparecer).

El modo Reemplazar todo es destructivo: retira todos tus ingredientes personalizados antes de importar. El modal avisa ("Cuidado: esta opción borrará TODOS tus ingredientes custom existentes antes de importar. Acción irreversible.") y, al pulsar Importar, pide una confirmación extra ("replace_all BORRARÁ todos tus ingredientes custom existentes antes de importar. ¿Continuar?"). El borrado es suave (soft-delete), así que las recetas que ya usaban esos ingredientes siguen mostrando su ficha y no se rompen; pero los que no estén en el archivo dejarán de aparecer en Mis ingredientes.

Previsualiza y confirma

Previsualiza (simulación)

Pulsa Previsualizar para hacer una simulación sin guardar nada. Verás los contadores Total, Nuevos, Actualizados, Saltados y Errores, y el detalle de las cinco primeras filas con error si las hay ("Fila N: …"). Una vez hecha la previsualización, el botón pasa a llamarse Recalcular vista previa, por si cambias el contenido o el modo.

Importa (real)

Si la previsualización cuadra, pulsa Importar para aplicar los cambios. Al terminar verás el bloque Import completado con el resultado real: Añadidos, Actualizados, Saltados y Errores. La lista de Mis ingredientes se vuelve a cargar al entrar en esa pestaña: si ya estabas en ella, cambia a Catálogo y vuelve, o recarga la página, para ver los cambios.

Qué se importa de cada fila

Se reconocen estos campos: name (obligatorio), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (por defecto g), densityGPerMl, weightPerUnitG, los 12 valores nutricionales (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol), allergens y notes. Las cabeceras no distinguen mayúsculas y se aceptan algunos alias (customCode/custom_code, baseUnit/base_unit/unit). Cualquier columna que no esté en la lista se ignora sin error.

Errores que verás:

Una fila sin nombre se salta y se reporta como "Fila N: Falta el nombre".
Un archivo mal formado se rechaza entero: "CSV vacío o sin filas", "JSON inválido: …" o "JSON: no se encontró el array 'ingredients'".

Estos mensajes los envía el servidor en el idioma de la interfaz. En "JSON inválido: …", el detalle técnico que sigue a los dos puntos sale tal como lo da el analizador de JSON, normalmente en inglés.

Exportar

En la pestaña Exportar ("Descarga tu catálogo personalizado. El formato JSON preserva estructuras complejas (macros, allergens); CSV es ideal para edición en Excel/Sheets.") tienes dos opciones de descarga directa. Solo se exportan tus ingredientes activos (los eliminados no se incluyen).

Exportar como JSON

"Formato completo para backup o migración a otra instancia." Descarga la ficha completa de cada ingrediente tal como está guardada, incluyendo lo que el CSV no representa: micronutrientes (que viven dentro de macros), nombres alternativos y campos personalizados. Es el formato recomendado para copia de seguridad. La estructura es:

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

Cada objeto de ingredients es la ficha completa del ingrediente (aquí abreviada).

Al reimportar un JSON (por ejemplo, para migrar a otra cuenta en modo Crear o actualizar) se restauran los datos base, los macros y micronutrientes y los alérgenos (un "allergens": null vuelve como sin declarar; si falta la clave allergens, la ficha queda como sin alérgenos) — pero no los nombres alternativos, los campos personalizados ni la declaración de conservantes, que tendrías que reintroducir. Para un backup íntegro, conserva el archivo JSON original.

Exportar como CSV

"Tabla plana para abrir en Excel/Sheets/Numbers." Descarga una tabla plana (archivo custom-ingredients-AAAA-MM-DD.csv) ideal para revisar o editar en una hoja de cálculo. El CSV incluye los macros pero no los micronutrientes (para eso, usa JSON).

Columnas del CSV

El despliegue Columnas CSV del modal lista las 25 columnas del archivo exportado, en este orden:

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 columna allergens es una lista separada por punto y coma (por ejemplo gluten;milk); queda vacía si la ficha no tiene alérgenos y lleva undeclared si están sin declarar. La única diferencia con la plantilla de importación es la columna id (presente al exportar, ignorada al importar).

Notas y límites

Round-trip por nombre. Exportar y volver a importar funciona: el emparejamiento es por nombre, así que la columna id del CSV exportado no es necesaria al reimportar.
CSV vs JSON. Usa CSV para edición rápida en hoja de cálculo (macros, sin micros); usa JSON para copia de seguridad: es el único formato que incluye los micronutrientes. Al reimportar, el JSON conserva macros y micros, pero no los nombres alternativos ni los campos personalizados.
Tamaño. No hay un tope de filas, pero la petición está limitada a ~5 MB. Para catálogos muy grandes, divide el archivo en varias importaciones.
Privacidad. Todo opera sobre tu catálogo de cuenta; ni la importación ni la exportación tocan el catálogo público.

Importar y exportar