Importação de produtos no Magento 2: boas práticas de CSV sem perder dados

A importação nativa de produtos do Magento é rápida e trata bem a maioria das atualizações de catálogo, desde que você saiba como ela lida com células vazias, store views e behaviors. A maioria dos desastres de importação que me pediram para limpar veio de um desses três pontos. Este artigo é um conjunto de regras que sigo em importações no Magento Open Source e no Adobe Commerce 2.4.8, pelo admin em System, Data Transfer, Import, ou por código que usa o mesmo import model.

Comece por uma exportação

Nunca monte um arquivo de importação do zero a partir da documentação. Exporte alguns produtos de cada tipo da mesma loja, abra o arquivo e use-o como template. A exportação mostra os nomes exatos das colunas, o separador dos valores de multi select, como o additional_attributes é formatado e como as variações de configuráveis são escritas. Mostra também as linhas de store view, se você exportar com elas.

Mantenha o arquivo em UTF-8 sem byte order mark e abra com uma ferramenta que não reformate SKUs. Programas de planilha adoram transformar SKUs numéricos longos em notação científica e remover zeros à esquerda. Um SKU que muda no caminho cria um produto novo em vez de atualizar o existente.

Escolha o behavior com cuidado

Behavior	O que faz	Quando usar
Add/Update	Cria SKUs novos e atualiza as colunas presentes nos existentes	Quase sempre
Replace	Apaga os produtos existentes com esses SKUs e os cria de novo	Raramente, com backup
Delete	Apaga os produtos com esses SKUs	Remoção em massa

O Replace merece um aviso. Como os produtos são apagados e recriados, eles ganham novos entity IDs. Tudo o que estava ligado ao ID antigo é afetado: URL rewrites, reviews, itens de wishlist, links de outros sistemas que guardaram o ID. Use Add/Update, a menos que tenha um motivo específico para não usar.

Envie só as colunas que você quer mudar

Com Add/Update, o Magento só toca nas colunas presentes no arquivo. Um arquivo com sku e price muda só o preço. É o jeito mais seguro de fazer atualizações em massa. Arquivos grandes com todas as colunas exportadas e reimportadas correm o risco de gravar de volta valores desatualizados que alguém mudou no admin nesse meio tempo.

sku,price,special_price
ABC-001,49.90,
ABC-002,59.90,44.90

Células vazias não limpam valores

No exemplo acima, o special_price vazio do ABC-001 não remove um special price existente. Células vazias são ignoradas. Para limpar um valor de propósito, use a constante __EMPTY__VALUE__, que o Magento reconhece durante a importação:

sku,special_price
ABC-001,__EMPTY__VALUE__

Essa única regra explica muitos relatos de "a importação não funcionou". A importação funcionou, só não fez o que as pessoas esperavam de uma célula vazia.

Linhas de store view

Valores por store view, como nomes ou descrições traduzidos, vão em linhas extras com o mesmo SKU e a coluna store_view_code preenchida. A primeira linha de um SKU, com o store view code vazio, guarda os valores padrão. As linhas de store view devem conter só as colunas que diferem, senão você cria overrides de store view para todo atributo, e mudanças feitas depois no scope padrão deixam de aparecer nessa store view.

sku,store_view_code,name,description
ABC-001,,Blue cotton shirt,Default description
ABC-001,pt_br,Camisa azul de algodao,Descricao em portugues

Valores de store view indesejados são um dos problemas de catálogo mais comuns que vejo em lojas antigas. Se você encontrá-los, dá para removê-los das tabelas EAV pelo store ID, depois de um backup e antes em staging.

Valores de atributos

• As opções de dropdown e multi select precisam existir. A importação do core não cria opções novas. Um valor que não casa com o label de uma opção existente falha na validação daquela linha. Crie as opções antes, com um data patch ou pelo admin.
• Atributos customizados podem ser colunas separadas ou ir no additional_attributes como pares code=value separados por vírgula. Colunas separadas são mais fáceis de ler e de comparar.
• Attribute set e tipo de produto são obrigatórios para produtos novos. Para produtos existentes podem ser omitidos.
• URL keys precisam ser únicas por store. Quando uma URL key colide com outro produto ou categoria, a linha falha com erro de URL key. Corrija o dado em vez de gerar sufixos aleatórios, porque essas URLs vão parar nos buscadores.

Imagens

As colunas base_image, small_image, thumbnail_image e additional_images recebem nomes de arquivo relativos ao diretório de imagens definido no formulário de importação. Por padrão é o pub/media/import. URLs também funcionam, mas o Magento baixa cada uma durante a importação, o que é lento e falha em silêncio com links quebrados. Em importações grandes, copie os arquivos para o servidor antes e referencie por caminho relativo.

Importar imagens de novo para produtos que já as têm adiciona cópias novas à galeria. Só inclua colunas de imagem quando as imagens realmente mudarem. Mais sobre o lado de armazenamento e resize em otimização de imagens de produto.

Produtos configuráveis

Importe os filhos simples primeiro, ou coloque-os antes no mesmo arquivo. A linha do configurável então os liga pelo configurable_variations, com cada filho como sku=...,attribute=value e os filhos separados por pipe:

sku,product_type,configurable_variations
SHIRT,configurable,"sku=SHIRT-S,size=S|sku=SHIRT-M,size=M|sku=SHIRT-L,size=L"

Os filhos precisam ter os valores do atributo configurável definidos, e o atributo precisa ter scope global com input dropdown ou swatch. Confira a exportação de um configurável existente para ver o formato exato que a sua versão grava, incluindo a coluna configurable_variation_labels.

Validação e erros

Sempre clique em Check Data antes do Import e leia os erros. A estratégia de validação decide o que acontece quando linhas falham. Stop on Error aborta a importação inteira, Skip error entries importa as linhas válidas e pula o resto, até o número de erros permitido. Em produção eu prefiro Stop on Error com um arquivo pequeno que já validei em staging. Pular linhas em silêncio é como surgem catálogos atualizados pela metade.

O Magento mantém um histórico das importações com o arquivo e o relatório de erros em System, Data Transfer, Import History. Guarde esses arquivos quando algo der errado, eles mostram exatamente o que foi enviado.

Arquivos grandes

• Divida. Arquivos com dezenas de milhares de linhas podem bater nos limites de tempo e memória do PHP no admin. Divida em blocos de alguns milhares de linhas e importe em sequência.
• Indexers em schedule. Com Update on Save, a importação dispara a reindexação conforme avança. Em schedule, as mudanças são pegas pelo cron depois. Veja modos de indexer: save vs schedule.
• Use a CLI ou código para importações recorrentes. O formulário do admin serve para trabalho ocasional. Para feeds diários de um ERP, um cron que chama o import model, ou uma biblioteca construída sobre ele como o FireGento FastSimpleImport, é mais confiável. O lado de integração está em padrões de integração com ERP.

O Adobe Commerce adiciona jobs agendados de importação e exportação no admin, que podem buscar arquivos em um local remoto em um agendamento. Esse recurso não existe no Magento Open Source.

Um checklist antes de toda importação

1. Backup do banco, ou pelo menos um dump das tabelas do catálogo.
2. Rode o mesmo arquivo em staging com uma cópia recente dos dados de produção.
3. Só as colunas que precisam mudar, com a coluna SKU exatamente como está armazenada.
4. Opções de dropdown e attribute sets criados antes.
5. Check Data sem erros, ou com erros que você entende.
6. Importe fora do horário de pico e depois confirme que indexers e cron alcançaram.
7. Confira alguns produtos no storefront e no admin, incluindo uma store view.

FAQ

Como limpo o valor de um atributo com uma importação do Magento?

Coloque __EMPTY__VALUE__ na célula. Uma célula vazia é ignorada com Add/Update e mantém o valor existente.

Por que minha importação cria produtos duplicados?

O SKU no arquivo não bate exatamente com o SKU armazenado. Ferramentas de planilha que mudam formatos de número, zeros à esquerda removidos e espaços perdidos são as causas usuais.

A importação do Magento cria opções de atributo automaticamente?

Não. A importação do core espera que os valores de dropdown e multi select já existam. Crie-os antes de importar, ou as linhas falham na validação.

O behavior Replace é seguro?

Ele apaga e recria os produtos, que ganham IDs novos e perdem dados ligados aos antigos. Use Add/Update para atualizações e deixe o Replace para casos raros, com backup.

Atendo como freelancer em Magento e Adobe Commerce, incluindo importações de catálogo e migrações de dados. Se precisar de ajuda com isso, fale comigo.