AreaCacao Docs

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

O que é

O modal Importar / Exportar ingredientes permite carregar o seu próprio catálogo de ingredientes personalizados a partir de um arquivo (em lote, sem criá-los um a um) ou baixá-lo para tê-lo fora do app.

Importar e exportar atua somente sobre o catálogo personalizado da sua conta, não sobre o catálogo público global. O próprio modal esclarece: “Catálogo personalizado da sua conta (não afeta o catálogo público).”. O catálogo global de mais de 10.000 ingredientes é somente leitura e não é afetado.

Como acessar

No catálogo de ingredientes, clique no botão Importar / Exportar do cabeçalho. O modal tem duas abas: Importar e Exportar.

Importar

Comece pelo modelo

Se você ainda não tem um arquivo, clique em Baixar modelo CSV (no aviso “Não sabe por onde começar? Baixe o modelo com exemplos e edite.”). É baixado o arquivo modelo-ingredientes-areacacao.csv, já com o cabeçalho correto e duas linhas de exemplo (Praliné de avelã e Chocolate amargo 70%) que você pode editar ou apagar. O nome do arquivo 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, você não define o identificador; quem o gera é o sistema. (O CSV que você exporta inclui, sim, o id — veja Exportar —, mas ao reimportá-lo essa coluna é ignorada.)

Como preparar o CSV?

O modal inclui um painel expansível Como preparar o CSV? com as regras. Em detalhe:

Só name é obrigatório. Deixe em branco as colunas que você não tiver.
Os valores nutricionais são por 100 g (como na ficha).
Separador decimal: são aceitos ponto ou vírgula (18.50 ou 18,50, formato brasileiro incluído). Se você usar vírgula como decimal, o ponto é interpretado como separador de milhar (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. Veja Alergênicos UE-14.
allergens vazio = sem alergênicos. Se ainda não os conhece, escreva undeclared (também é aceito sin declarar): a ficha fica com os alergênicos não declarados, o que não é o mesmo que “sem alergênicos”.
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: são preenchidos na ficha do ingrediente. (Se você precisar deles em um arquivo, use o formato JSON, que os preserva.)

Carregar os dados

Você tem três formas de fornecer o conteúdo:

Arrastar e soltar um arquivo na área “Arraste um arquivo CSV ou JSON para cá”.
Clicar em Selecionar arquivo e escolher um .csv ou .json do seu computador.
Abrir Ou colar o texto manualmente e colar o conteúdo diretamente.

O app detecta o formato automaticamente (se o texto começa com { ou [, trata-o como JSON; caso contrário, como CSV) e o mostra no seletor Formato detectado, que você pode corrigir manualmente se necessário. Os seletores Formato detectado 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 diferenciar maiúsculas/minúsculas):

Modo	O que faz
Só criar novos (recomendado, padrão)	Adiciona os ingredientes cujo nome não existe e ignora os que você já tem (não mexe neles). Também ignora os nomes de fichas que você excluiu: elas continuam excluídas.
Criar ou atualizar (pelo nome)	Adiciona os novos e sobrescreve os existentes que coincidem pelo nome com os dados do arquivo. Se o nome coincidir com uma ficha que você excluiu, ela volta com os dados do arquivo.
Substituir tudo (apaga os existentes)	Remove todos os seus ingredientes personalizados e depois importa os do arquivo (reativando pelo nome os que voltarem a aparecer).

O modo Substituir tudo é destrutivo: remove todos os seus ingredientes personalizados antes de importar. O modal 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 extra (“replace_all vai APAGAR todos os seus ingredientes personalizados existentes antes de importar. Continuar?”). A exclusão é lógica (soft-delete), então as receitas que já usavam esses ingredientes continuam mostrando a ficha deles e não quebram; mas os que não estiverem no arquivo deixarão de aparecer em Meus ingredientes.

Pré-visualize e confirme

Pré-visualize (simulação)

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

Importe (de verdade)

Se a pré-visualização estiver certa, clique em Importar para aplicar as alterações. Ao terminar, você verá o bloco Importação concluída com o resultado real: Adicionados, Atualizados, Ignorados e Erros. A lista de Meus ingredientes é recarregada quando você abre essa aba: se já estava nela, passe para Catálogo e volte, ou recarregue a página, para ver as mudanças.

O que é importado de cada linha

São reconhecidos estes campos: name (obrigatório), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (padrã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 diferenciam maiúsculas e alguns aliases são aceitos (customCode/custom_code, baseUnit/base_unit/unit). Qualquer coluna que não esteja na lista é ignorada sem erro.

Erros que você verá:

Uma linha sem nome é ignorada e informada como “Linha N: Falta o nome”.
Um arquivo malformado é rejeitado por inteiro: “O arquivo CSV está vazio ou não tem linhas”, “JSON inválido: …” ou “JSON: o array “ingredients” não foi encontrado”.

O servidor envia essas mensagens no idioma da interface. Em “JSON inválido: …”, o detalhe técnico depois dos dois-pontos vem direto do analisador de JSON, normalmente em inglês.

Exportar

Na aba Exportar (“Baixe o seu catálogo personalizado. O formato JSON preserva estruturas complexas (macros, allergens); o CSV é ideal para editar no Excel/Sheets.”) você tem duas opções de download direto. Só são exportados os seus ingredientes ativos (os excluídos não são incluídos).

Exportar como JSON

“Formato completo para backup ou migração para outra instância.” Baixa a ficha completa de cada ingrediente tal como está salva, incluindo o que o CSV não representa: micronutrientes (que ficam dentro de macros), nomes alternativos e campos personalizados. É o formato recomendado para backup. 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 básicos, os macros e micronutrientes e os alergênicos (um "allergens": null volta como não declarados; se faltar a chave allergens, a ficha fica sem alergênicos) — mas não os nomes alternativos, os campos personalizados nem a declaração de conservante, que você teria de inserir de novo. Para um backup completo, guarde o arquivo JSON original.

Exportar como CSV

“Tabela simples para abrir no Excel/Sheets/Numbers.” Baixa uma tabela simples (arquivo custom-ingredients-AAAA-MM-DD.csv), ideal para revisar ou editar em uma planilha. O CSV inclui os macros, mas não os micronutrientes (para isso, use JSON).

Colunas do CSV

O painel Colunas do CSV do modal lista as 25 colunas do arquivo exportado, nesta 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ênicos e traz undeclared se eles não foram declarados. A única diferença em relação ao modelo de importação é a coluna id (presente ao exportar, ignorada ao importar).

Observações e limites

Ida e volta pelo nome. Exportar e importar de novo funciona: a correspondência é feita pelo nome, então a coluna id do CSV exportado não é necessária ao reimportar.
CSV vs JSON. Use CSV para edição rápida em planilha (macros, sem micronutrientes); use JSON para backup: é o único formato que inclui os micronutrientes. Ao reimportar, o JSON preserva macros e micronutrientes, mas não os nomes alternativos nem os campos personalizados.
Tamanho. Não há limite de linhas, mas a requisição é limitada a ~5 MB. Para catálogos muito grandes, divida o arquivo em várias importações.
Privacidade. Tudo atua sobre o catálogo da sua conta; nem a importação nem a exportação mexem no catálogo público.

Importar e exportar