AreaCacao Docs

Carregue o seu catálogo personalizado de ingredientes a partir de CSV/JSON (com modelo, 3 modos e pré-visualização) ou transfira-o para cópia de segurança e migração.

O que é

A janela Importar / Exportar ingredientes permite-lhe carregar o seu próprio catálogo de ingredientes personalizados a partir de um ficheiro (em lote, sem os criar um a um) ou transferi-lo para o ter fora da aplicação.

A importação e a exportação funcionam apenas sobre o catálogo personalizado da sua conta, não sobre o catálogo público global. A própria janela esclarece-o: «Catálogo personalizado da sua conta (não afeta o catálogo público).». O catálogo global de mais de 10 000 ingredientes é só de leitura e não é afetado.

Como aceder

A partir do catálogo de ingredientes, clique no botão Importar / Exportar do cabeçalho. A janela tem dois separadores: Importar e Exportar.

Importar

Comece pelo modelo

Se ainda não tiver um ficheiro, clique em Transferir modelo CSV (no aviso «Não sabe por onde começar? Transfira o modelo com exemplos e edite-o.»). É transferido o ficheiro modelo-ingredientes-areacacao.csv, já com o cabeçalho correto e duas linhas de exemplo (Praliné de avelã e Chocolate de cobertura negro 70%) que pode editar ou apagar. O nome do ficheiro e o texto dos exemplos seguem o idioma da interface; os nomes das colunas são sempre os mesmos, em inglês.

O modelo inclui estas 24 colunas (todas opcionais, exceto 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

O modelo não traz a coluna id: ao importar, não define o identificador; é o sistema que o gera. (O CSV que exporta inclui id — ver Exportar —, mas ao reimportá-lo essa coluna é ignorada.)

Como preparar o CSV?

A janela inclui um painel expansível Como preparar o CSV? com as regras. Em pormenor:

Apenas name é obrigatório. Deixe em branco as colunas que não tiver.
Os valores nutricionais são por 100 g (tal como na ficha).
Separador decimal: é aceite ponto ou vírgula (18.50 ou 18,50, formato europeu incluído). Se usar a vírgula como separador decimal, o ponto é interpretado como separador de milhares (1.234,56 é lido como mil duzentos e trinta e quatro vírgula cinquenta e seis).
allergens: lista de códigos separados por ;. Os códigos válidos são os 14 oficiais da UE: gluten, crustaceans, eggs, fish, peanuts, soy, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs. Qualquer código fora desta lista é ignorado. Ver Alergénios UE-14.
allergens vazio = sem alergénios. Se ainda não os conhecer, escreva undeclared (também é aceite sin declarar): a ficha fica com os alergénios por declarar, o que não é o mesmo que «sem alergénios».
alcohol: gramas de etanol por 100 g (vinhos e licores). Vazio = sem dado.
Os micronutrientes (vitaminas, minerais, colesterol, cafeína) não são carregados por CSV: preenchem-se na ficha do ingrediente. (Se precisar deles num ficheiro, use o formato JSON, que os conserva.)

Carregar os dados

Tem três formas de fornecer o conteúdo:

Arrastar e largar um ficheiro na zona «Arraste um ficheiro CSV ou JSON para aqui».
Clicar em Selecionar ficheiro e escolher um .csv ou .json do seu computador.
Expandir Ou colar o texto manualmente e colar o conteúdo diretamente.

A aplicação deteta o formato automaticamente (se o texto começar por { ou [, trata-o como JSON; caso contrário, como CSV) e mostra-o no seletor Formato detetado, que pode corrigir manualmente se for necessário. Os seletores Formato detetado e Modo e os botões aparecem assim que há conteúdo carregado.

Escolha o modo

O seletor Modo define como a importação é aplicada. A correspondência com os seus ingredientes existentes é feita pelo nome (sem distinguir maiúsculas/minúsculas):

Modo	O que faz
Apenas criar novos (recomendado, predefinido)	Adiciona os ingredientes cujo nome não exista e ignora os que já tem (não lhes toca). Também ignora os nomes de fichas que eliminou: continuam eliminadas.
Criar ou atualizar (pelo nome)	Adiciona os novos e substitui os existentes que coincidam pelo nome com os dados do ficheiro. Se o nome coincidir com uma ficha que eliminou, recupera-a com os dados do ficheiro.
Substituir tudo (apaga os existentes)	Retira todos os seus ingredientes personalizados e depois importa os do ficheiro (e reativa, pelo nome, os que voltarem a aparecer).

O modo Substituir tudo é destrutivo: retira todos os seus ingredientes personalizados antes de importar. A janela avisa («Atenção: esta opção vai apagar TODOS os seus ingredientes personalizados existentes antes de importar. Ação irreversível.») e, ao clicar em Importar, pede uma confirmação adicional («replace_all vai APAGAR todos os seus ingredientes personalizados existentes antes de importar. Continuar?»). A eliminação é suave (soft-delete), por isso as receitas que já usavam esses ingredientes continuam a mostrar a sua ficha e a funcionar; mas os que não estiverem no ficheiro deixarão de aparecer em Os meus ingredientes.

Pré-visualize e confirme

Pré-visualize (simulação)

Clique em Pré-visualizar para fazer uma simulação sem guardar nada. Verá os contadores Total, Novos, Atualizados, Ignorados e Erros, e o detalhe das cinco primeiras linhas com erro, se as houver («Linha N: …»). Depois da primeira pré-visualização, o botão passa a chamar-se Recalcular pré-visualização, caso altere o conteúdo ou o modo.

Importe (definitivo)

Se a pré-visualização estiver correta, clique em Importar para aplicar as alterações. No fim verá o bloco Importação concluída com o resultado real: Adicionados, Atualizados, Ignorados e Erros. A lista de Os meus ingredientes volta a ser carregada quando abre esse separador: se já estava nele, passe para Catálogo e volte, ou recarregue a página, para ver as alterações.

O que é importado de cada linha

São reconhecidos estes campos: name (obrigatório), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (por predefinição g), densityGPerMl, weightPerUnitG, os 12 valores nutricionais (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol), allergens e notes. Os cabeçalhos não distinguem maiúsculas e são aceites alguns alias (customCode/custom_code, baseUnit/base_unit/unit). Qualquer coluna que não esteja na lista é ignorada sem erro.

Erros que verá:

Uma linha sem nome é ignorada e reportada como «Linha N: Falta o nome».
Um ficheiro mal formado é rejeitado na totalidade: «O ficheiro CSV está vazio ou não tem linhas», «JSON inválido: …» ou «JSON: não foi encontrada a lista «ingredients»».

O servidor envia estas mensagens no idioma da interface. Em «JSON inválido: …», o detalhe técnico depois dos dois pontos vem diretamente do analisador de JSON, normalmente em inglês.

Exportar

No separador Exportar («Transfira o seu catálogo personalizado. O formato JSON preserva estruturas complexas (macros, allergens); o CSV é ideal para editar no Excel/Sheets.») tem duas opções de transferência direta. Só são exportados os seus ingredientes ativos (os eliminados não são incluídos).

Exportar como JSON

«Formato completo para cópia de segurança ou migração para outra instância.» Transfere a ficha completa de cada ingrediente tal como está guardada, com tudo o que o CSV não representa: micronutrientes (que estão dentro de macros), nomes alternativos e campos personalizados. É o formato recomendado para cópias de segurança. A estrutura é:

{
  "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 é a ficha completa do ingrediente (aqui abreviada).

Ao reimportar um JSON (por exemplo, para migrar para outra conta no modo Criar ou atualizar), são restaurados os dados base, os macros e micronutrientes e os alergénios (um "allergens": null volta como por declarar; se faltar a chave allergens, a ficha fica sem alergénios) — mas não os nomes alternativos, os campos personalizados nem a declaração de conservante, que teria de voltar a introduzir. Para uma cópia de segurança integral, conserve o ficheiro JSON original.

Exportar como CSV

«Tabela simples para abrir no Excel/Sheets/Numbers.» Transfere uma tabela simples (ficheiro custom-ingredients-AAAA-MM-DD.csv), ideal para rever ou editar numa folha de cálculo. O CSV inclui os macros, mas não os micronutrientes (para isso, use JSON).

Colunas do CSV

O painel expansível Colunas do CSV da janela lista as 25 colunas do ficheiro exportado, por esta ordem:

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

A coluna allergens é uma lista separada por ponto e vírgula (por exemplo, gluten;milk); fica vazia se a ficha não tem alergénios e traz undeclared se estão por declarar. A única diferença em relação ao modelo de importação é a coluna id (presente ao exportar, ignorada ao importar).

Notas e limites

Ida e volta pelo nome. Exportar e voltar a importar funciona: a correspondência é feita pelo nome, por isso a coluna id do CSV exportado não é necessária ao reimportar.
CSV vs JSON. Use CSV para edição rápida numa folha de cálculo (macros, sem micronutrientes); use JSON para cópias de segurança: é o único formato que inclui os micronutrientes. Ao reimportar, o JSON conserva os macros e os micronutrientes, mas não os nomes alternativos nem os campos personalizados.
Tamanho. Não há um limite de linhas, mas o pedido está limitado a ~5 MB. Para catálogos muito grandes, divida o ficheiro em várias importações.
Privacidade. Tudo funciona sobre o catálogo da sua conta; nem a importação nem a exportação tocam no catálogo público.

Importar e exportar