A importação de dados em lote no Magento 2 é o processo que permite transferir grandes volumes de informações para uma loja virtual de forma estruturada e eficiente, sem a necessidade de cadastros manuais um a um. Para e-commerces com catálogos extensos, migrações de plataforma ou atualizações frequentes de estoque, esse recurso não é opcional. É infraestrutura.
Principais pontos do artigo
- O Magento 2 oferece importação nativa via painel administrativo e via linha de comando (CLI)
- Os formatos suportados incluem CSV e XML, com estrutura de colunas específica por entidade
- É possível importar produtos, clientes, endereços, estoque, imagens e dados de categorias
- O comportamento de importação pode ser configurado para adicionar, substituir ou excluir registros
- Erros de validação são reportados antes da execução, permitindo correção sem impacto na loja
- Importações grandes exigem ajustes de configuração de servidor para evitar timeout e limite de memória
O que é a importação em lote e para que serve
No Magento 2, importação em lote significa processar um arquivo com centenas ou milhares de registros de uma só vez. O sistema lê o arquivo, valida as entradas linha por linha e aplica as alterações conforme o comportamento selecionado.
Esse processo é usado em situações como migração de outra plataforma, atualização massiva de preços, carregamento de novo catálogo de fornecedor, sincronização com ERP e cadastro inicial de base de clientes. Qualquer operação que exigiria horas de trabalho manual no admin pode ser convertida num arquivo e executada em minutos.
Entidades que suportam importação
O Magento 2 permite importar os seguintes tipos de entidade pelo painel nativo:
Produtos é a entidade mais usada. Suporta simples, configuráveis, agrupados, virtuais e downloadable. Cada tipo tem colunas obrigatórias específicas no CSV.
Clientes e endereços de clientes são tratados separadamente. O arquivo de clientes importa dados de conta. O de endereços importa os endereços vinculados, usando o e-mail como chave de relação.
Estoque avançado permite atualizar quantidades por SKU sem reimportar o produto inteiro. Útil para sincronização com sistemas de armazenagem.
Imagens de produtos podem ser importadas por URL externa ou caminho de arquivo no servidor. O Magento baixa e vincula automaticamente durante a importação.
Dados de categorias permitem criar e estruturar a árvore de categorias via arquivo, com suporte a hierarquias múltiplas.
Formatos de arquivo aceitos
O formato principal é CSV com codificação UTF-8. Para produtos, o separador padrão é vírgula, mas o painel permite configurar separador alternativo, incluindo ponto e vírgula, para arquivos exportados de sistemas europeus que usam vírgula como decimal.
O Magento também suporta importação via XML para alguns módulos de terceiros e integrações com ERPs específicos, mas o fluxo nativo do admin trabalha exclusivamente com CSV.
O tamanho máximo do arquivo no upload pelo painel depende da configuração do PHP (upload_max_filesize e post_max_size). Para arquivos acima de 50 MB, a importação via CLI é mais confiável.
Comportamentos de importação disponíveis
Ao configurar uma importação, o Magento oferece três comportamentos:
Add/Update cria registros novos e atualiza os existentes com base na chave primária (SKU para produtos, e-mail para clientes). É o comportamento mais usado no dia a dia.
Replace substitui o registro completo. Se um campo não está no arquivo, ele retorna ao valor padrão. Usado quando se quer garantir que nenhum dado antigo persista.
Delete remove os registros identificados no arquivo. Útil para limpeza de catálogo ou desativação em massa.
Existe ainda a opção de validação sem execução, que processa o arquivo inteiro e retorna todos os erros sem aplicar nenhuma alteração na loja.
Como importar pelo painel administrativo
O caminho no admin é System > Data Transfer > Import. O fluxo segue esta sequência:
- Selecionar a entidade (produto, cliente, estoque etc.)
- Escolher o comportamento de importação
- Configurar separador de campos e de múltiplos valores
- Fazer upload do arquivo CSV
- Clicar em “Check Data” para validar sem executar
- Revisar os erros reportados e corrigir o arquivo se necessário
- Clicar em “Import” para executar
O Magento processa as linhas em blocos e exibe um log de resultado ao final, indicando quantos registros foram criados, atualizados ou ignorados.
Importação via linha de comando
Para volumes maiores ou execução automatizada, o Magento 2 oferece importação via Magento CLI:
bashbin/magento import:run --entity=catalog_product --behavior=append --source=var/import/produtos.csv
A importação via CLI não sofre limitações de timeout do servidor web e consome memória de forma mais controlada. É o método recomendado para arquivos acima de 10 mil linhas ou em rotinas agendadas via cron.
O arquivo deve estar em var/import/ por padrão, mas o caminho pode ser configurado. Erros são registrados em var/log/import.log.
Estrutura do CSV de produtos
O arquivo de produtos exige algumas colunas obrigatórias para que o Magento identifique e processe cada linha corretamente:
- sku: identificador único do produto, chave primária da importação
- product_type: simple, configurable, grouped, virtual ou downloadable
- attribute_set_code: nome do conjunto de atributos
- name: nome do produto
- price: preço base
- status: 1 para habilitado, 2 para desabilitado
- visibility: 1 (não visível), 2 (catálogo), 3 (pesquisa), 4 (catálogo e pesquisa)
- _root_category e _category: estrutura de categorias, separadas por barra
Para produtos configuráveis, o arquivo precisa conter tanto a linha do produto pai quanto as linhas dos produtos simples vinculados, com a coluna _super_products_sku indicando as associações.
Erros comuns e como evitá-los
- Encoding incorreto é o problema mais frequente. O arquivo deve estar em UTF-8 sem BOM. Excel costuma salvar com BOM ou em Latin-1, o que quebra caracteres especiais no Magento.
- Coluna obrigatória ausente impede a validação de toda a linha. O log do Magento indica qual coluna está faltando e em qual linha do arquivo.
- Valor inválido em atributo de seleção ocorre quando o arquivo usa um label que não existe no atributo (por exemplo, “Vermelho” em vez de “Red” se o atributo foi criado em inglês). O Magento exige o valor exato cadastrado.
- Imagem não encontrada acontece quando o arquivo referencia um caminho de imagem que não existe no servidor ou uma URL externa inacessível. O produto é importado sem a imagem, mas sem erro fatal.
- Timeout no upload afeta arquivos grandes via admin. A solução é aumentar
max_execution_timeememory_limitnophp.ini, ou migrar para importação via CLI.
Boas práticas para importações em produção
Sempre validar o arquivo antes de executar. O botão “Check Data” existe exatamente para isso e reporta todos os problemas sem modificar nada.
Exportar uma amostra do catálogo existente antes de qualquer importação. O arquivo exportado serve de template correto para o ambiente específico, com os atributos e valores reais da loja.
Fazer backup do banco antes de importações com comportamento Replace ou Delete. Esses comportamentos são irreversíveis no fluxo nativo.
Usar ambiente de staging para testar importações de grande volume antes de executar em produção. Erros que passaram na validação ainda podem gerar inconsistências de dados em escala.
Agendar importações grandes para períodos de baixo tráfego. O processo consome recursos do servidor e pode impactar performance da loja se executado em horário de pico.
A Trezo trabalha com e-commerces Magento que operam catálogos complexos, integrações com ERP e processos de importação recorrentes. Se sua operação envolve volumes que estão na borda do que o Magento nativo suporta com estabilidade, fale com nossos especialistas. A análise da sua arquitetura de dados é o primeiro passo.
FAQ
Sim. O arquivo pode conter linhas específicas por store view usando a coluna store_view_code. Quando essa coluna está vazia, o registro é aplicado à store view padrão. Quando preenchida com o código da loja, o Magento aplica os valores daquela linha apenas naquele contexto. Isso permite, por exemplo, importar traduções de nome e descrição para inglês e espanhol no mesmo arquivo.
Não existe um limite fixo no código do Magento. O limite real depende da configuração do servidor, especialmente memory_limit e max_execution_time do PHP. Em servidores padrão de produção, arquivos com até 50 mil linhas via CLI são processados sem problemas. Acima disso, o recomendado é dividir o arquivo em lotes menores ou configurar workers dedicados para o processo de importação.
Sim. Após a importação, os indexadores relacionados ficam com status “Reindex Required”. O Magento não faz reindex automático durante o processo para não impactar a performance. O reindex deve ser executado manualmente via CLI (bin/magento indexer:reindex) ou configurado para rodar por cron. O cache de página também precisa ser limpo para que as alterações fiquem visíveis na loja para os consumidores finais.
