Como importar produtos em Magento 2 no 2026: O Guia de Trabalho para 2.4.8 - PT

Adobe lançou Magento 2.4.8 em abril 8, 2025, e a forma como grandes catálogos se movem pela plataforma finalmente alcançou 2026. Os endpoints de importação REST nativos (/V1/importação/csv e /V1/importação/json) agora aceita cargas codificadas em base64 e compactação gzip. Isso mata o velho “divida seu CSV em 500 filas e orar” rotina. O importador de CSV administrativo no qual a maioria das lojas ainda depende? Mesma ferramenta, majoritariamente. Mas as formas como isso quebra mudaram, e também as correções. Este guia cobre ambos os caminhos, e os erros que comem um fim de semana quando você sente falta deles.

Resposta rápida: Para catálogos abaixo 5,000 SKUs, use o importador CSV de administrador em Sistema > Transferência de dados > Importar. Para qualquer coisa maior ou automatizada, acertar o Ponto de extremidade REST /V1/import/csv adicionado em 2.4.8. Mantenha arquivos UTF-8 sem BOM, coloque imagens em var/importar/imagens, e sempre corra “Verifique os dados” antes de cometer.

Última revisão: abril 2026. Pontos finais, números de versão, e comportamentos de importação verificados no Adobe Commerce 2.4.8 notas de lançamento e documentação da Experience League.

Antes de começar: O que mudou em 2.4.8

Se você importou produtos no Magento 2.4.5 ou antes, alguns padrões apanhados com a realidade. Novo 2.4.8 instala o navio com indexadores em Atualização por agendamento modo, para que as importações em massa não paralisem mais o front-end durante a reindexação. O lançamento foi encerrado 497 erros principais (vários no próprio importador) e adicionou os endpoints de importação REST que contornam o teto de upload administrativo de 2 MB.

Aqui está o que você precisa antes de tocar no importador:

• Magento 2.4.8 ou mais tarde. Correndo 2.4.5 ou mais velho? Atualize primeiro. O importador mais antigo ainda funciona, mas as correções de bugs não estão sendo retroportadas.
• PHP 8.3 mínimo, 8.4 recomendado. 2.4.8 vem com PHP nativo 8.4 Apoio, suporte. Lojas em PHP 8.1 irá importar, mas o tratamento de erros é mais barulhento.
• MySQL 8.0 ou MariaDB 10.6/11.4. 2.4.9-beta1 descarta MySQL 8.0 e MariaDB 10.6, então, se você estiver configurando um novo, ir 11.4.
• Um diretório var/import/images gravável. Permissões: 775 para diretórios, 664 para arquivos, propriedade do seu usuário da web.
• Limites de PHP suficientes. Para catálogos acima 10,000 SKUs, limite_de_memória 2G e tempo_máximo_de_execução 1800 em php.ini. Valores mais baixos matarão silenciosamente as importações a meio.

Um rápido aviso: Adobe Commerce (o nível pago) e Magento Open Source compartilham o código do importador. Os clientes da nuvem não precisam mexer no php.ini porque a pilha vem pré-ajustada, mas as regras e comportamentos do CSV abaixo se aplicam de forma idêntica.

O que você realmente pode importar

Magento 2 tem seis tipos de produtos, e as regras do CSV mudam dependendo de qual você está movendo. A versão curta:

• Produtos simples. Um SKU, uma variação. O modelo que todo tutorial usa. Importe-os primeiro se você estiver aprendendo.
• Produtos configuráveis. Um SKU pai com filho simples anexado via variações_configuráveis. Camisetas de tamanho e cor são o exemplo clássico. Os filhos devem existir antes da linha de importação pai, ou o link falha.
• Produtos virtuais. Serviços, assinaturas, cobertura de garantia. Sem cálculo de frete, nenhuma coluna de peso necessária.
• Produtos agrupados. Um wrapper que mostra vários simples em uma página (pensar “conjunto de faca de cozinha, compre individualmente”). Usos skus_associados no CSV.
• Produtos agrupados. Crie seus próprios combos onde o cliente escolhe as opções. O formato é complicado e usa valores_pacote com campos separados por tubos.
• Produtos para download. arquivos, licenças de software, e-books. Precisa links para download configurado.

O pedido de importação é importante. Simples primeiro, em seguida, configuráveis ​​que os referenciam, então agrupado e agrupado por último. Importar um configurável cujos SKUs filhos ainda não existem é o erro autoinfligido mais comum, e o validador nem sempre irá capturá-lo antes da importação ser executada.

Importação de CSV: O passo a passo do administrador

O importador CSV administrativo lida com catálogos de até cerca de 5,000 SKUs sem reclamação. Vale a pena saber, mesmo se você planeja migrar para a API mais tarde, porque as regras de coluna a seguir se aplicam a ambos os caminhos.

Degrau 1: Exportar um arquivo de amostra (Não pule isso)

Vamos para Sistema > Transferência de dados > Importar. Definir Tipo de entidade para Produtos, então clique Baixar arquivo de amostra. A amostra corresponde exatamente à sua instalação do Magento, incluindo quaisquer atributos personalizados que sua loja adicionou. Usar um modelo CSV genérico de uma postagem de blog é como os erros de incompatibilidade de coluna começam.

Salve a amostra, abra-o no Notepad++ ou VS Code. Não use Microsoft Excel. Excel adiciona uma marca de ordem de bytes aos arquivos UTF-8, e o importador rejeita arquivos com prefixo BOM sem uma mensagem de erro clara. Se o Excel for sua única opção, exportar como “CSVUTF-8” e execute o arquivo através de um removedor de BOM, ou mude para o Planilhas Google (Arquivo > Baixar > CSV, que salva UTF-8 limpo).

Degrau 2: Preencha as linhas do seu produto

Colunas obrigatórias para um produto simples: sku, store_view_code, atributo_set_code, tipo_produto, categorias, sites_de_produtos, nome, descrição, preço, quantidade, peso, produto_online, nome_da_classe_taxa, visibilidade.

Mantenha as descrições abaixo ~255 caracteres por linha se você estiver no importador administrativo. Descrições HTML mais longas funcionam, mas eles aumentam o tamanho do arquivo rapidamente e aproximam o limite padrão de 2 MB. As categorias usam barras para construir hierarquia: Categoria padrão/vestuário/camisetas. O separador é uma barra, não é uma barra invertida. Um alívio: Magento cria automaticamente caminhos de categorias que ainda não existem, então você não precisa pré-construir todas as categorias antes de importar.

Para configuráveis, a variações_configuráveis coluna carrega uma string delimitada por barras verticais como:
sku = CAMISA-VERMELHA-S,tamanho=S,cor=Vermelho|sku = CAMISA-VERMELHA-M,tamanho=M,cor=Vermelho

Complicado, sim. Evite problemas exportando primeiro um configurável feito à mão, em seguida, use essa linha como modelo para o próximo 5,000.

Degrau 3: Configurar o comportamento de importação

O que acontece quando um SKU do seu CSV já existe no catálogo? Três opções de comportamento decidem, e escolher o errado pode apagar dados:

• Adicionar/atualizar. O padrão e a escolha segura. Adiciona novos SKUs, atualiza os correspondentes, deixa produtos não listados em paz.
• Substituir. Exclui primeiro os SKUs correspondentes, em seguida, recria-os a partir do CSV. Limpa URLs, avaliações, e histórico de movimentação de estoque desses produtos. Use raramente.
• Excluir entidades. Remove SKUs correspondentes do catálogo. Irreversível sem restauração do banco de dados.

Também definido Separador de campos para vírgula, Separador de vários valores para vírgula, e verifique Contagem de erros permitidos. O padrão é 10. Aumente para um número maior se você espera que algumas linhas falhem e deseja que o importador continue em vez de abortar.

Degrau 4: Valide antes de importar

Carregue seu CSV, clique Verifique os dados, e espere. Isso executa a mesma validação que a importação real faz, mas sem gravar no banco de dados. A saída lista cada erro de linha por número com a coluna específica que falhou. Corrija o CSV, reenviar, verificar novamente. Enxaguar até ficar verde.

Se a validação disser “O arquivo é válido” mas alguns avisos aparecem, leia-os de qualquer maneira. Os avisos geralmente estão faltando caminhos de categoria ou visualizações de loja que o Magento irá ignorar silenciosamente, criando produtos com árvores de categorias incompletas.

Degrau 5: Execute a importação

Clique Importar. A barra de progresso é honesta para arquivos pequenos e otimista para arquivos grandes. Não feche a guia do navegador. Não atualize. O importador executa um único processo PHP longo, e em hospedagem mais lenta, fechar a guia no meio da gravação torna o processo órfão e deixa dados parciais para trás. Assistir var/log/import.log por SSH se você quiser progresso ao vivo, ou verifique Sistema > Histórico de importação assim que terminar.

Imagens e Mídia

As imagens confundem mais importações do que qualquer outro campo. A regra é simples, uma vez que você a tenha visto uma vez.

FTP ou SFTP seus arquivos de imagem em <Raiz Magento>/var/importar/imagens. Subpastas são permitidas: var/importar/imagens/2026-primavera trabalho. No CSV, referenciar cada imagem por seu caminho em relação a var/importar/imagens:

• imagem_base coluna: imagem principal do produto (mostrado na página do produto)
• pequena imagem coluna: miniatura para páginas de categoria
• imagem_miniatura coluna: carrinho e miniaturas de pedidos
• imagens_adicionais coluna: imagens da galeria, separados por vírgula

Uma linha importando um produto com quatro fotos de galeria pode parecer: /2026-primavera/tshirt-red-main.jpg no imagem_base, então /2026-primavera/tshirt-red-back.jpg,/2026-primavera/tshirt-red-detail.jpg,/2026-primavera/tshirt-tecido-vermelho.jpg no imagens_adicionais.

Observe a nomenclatura do arquivo. Guloseimas Magento Camisa.jpg e camisa.jpg como arquivos diferentes em hosts Linux, e o importador não corrige automaticamente o caso. Compacte para WebP antes de fazer upload, se puder; fotos de heróis em JPEG de 300-400 KB irão diminuir seus Core Web Vitals no momento em que o tráfego real chegar. Nosso Manual de velocidade do Magento cobre conversão WebP e AVIF para catálogos existentes.

Importação de API REST: o 2.4.8 Caminho para grandes catálogos

O importador administrativo termina rapidamente. Depois que você passar 10,000 SKUs ou você precisa de sincronizações automatizadas de um ERP, os endpoints REST fornecidos pela Adobe 2.4.8 são a ferramenta certa. Dois pontos finais são importantes:

• POSTAR /descansar/<código_da_loja>/V1/importação/csv para cargas CSV
• POSTAR /descansar/<código_da_loja>/V1/importação/json para cargas JSON

Ambos aceitam uma string codificada em base64 no corpo da solicitação. Para CSV, a regra é: Codifique seu arquivo em UTF-8, gzip-compacte-o (opcional, mas inteligente para qualquer coisa acima de 1 MB), então base64 o resultado. A resposta retorna uma contagem de entidades importadas. Massa assíncrona via /V1/em massa/ funciona também se você quiser disparar e esquecer.

O fluxo, em ordem:

• Autenticar com um token de administrador (POSTAR para /V1/integração/admin/token)
• Compacte seus produtos.csv, codifique-o em base64, coloque-o em uma carga JSON com fonte, entidade: “catálogo_produto”, e comportamento: “acrescentar”
• POST para o endpoint de importação com o token no cabeçalho de autorização
• Enquete /V1/em massa/{Uuid em massa}/status se você fosse assíncrono

Os documentos do desenvolvedor da Adobe apresentam o formato exato da carga útil e são atualizados por versão, então puxe de lá em vez de copiar threads antigos do StackOverflow. o 2.4.8 Pague: o caminho assíncrono não mantém uma solicitação PHP aberta por até 30 minutos da mesma forma que o importador administrativo faz. Sua carga de 50.000 linhas é executada em segundo plano, e a vitrine permanece responsiva aos compradores reais.

Erros comuns de importação e o que realmente os corrige

Estas são as falhas que queimam mais tempo. Cada um tem uma causa raiz específica que nem sempre é óbvia no texto do erro.

“Tamanho de memória permitido de X bytes esgotado”

PHP ficou sem memória no meio da importação. Elevação limite_de_memória em php.ini para 2G, reinicie o PHP-FPM, tente novamente. Se você não consegue tocar em php.ini (Hospedagem Compartilhada), divida o CSV em arquivos de 1,000-5,000 linhas cada e importar sequencialmente. Extensões de terceiros como Firebear e Amasty adicionam um “Importar sem limite de memória” alternar, mas isso é um recurso de extensão, não é Magento nativo.

“Tempo máximo de execução de 30 segundos excedidos”

Seu PHP tempo_máximo_de_execução é muito baixo. Bata para 1800 segundos. No Nginx, você também precisará aumentar fastcgi_read_timeout combinar, caso contrário, o Nginx mata o upstream antes que o PHP termine.

“Sequência de colunas errada” ou “O cabeçalho tem colunas inválidas”

Marca de ordem de bytes. Seu CSV foi salvo do Excel, que precede uma BOM aos arquivos UTF-8 que o importador lê como uma primeira coluna ilegível. Exporte novamente do Planilhas Google ou salve novamente por meio do Notepad ++ como UTF-8 sem BOM. Se você verificar apenas uma coisa antes de importar, verifique isso.

“Conjunto de atributos inválido” ou “Valor de atributo inválido para X”

Seu CSV faz referência a um conjunto de atributos ou valor suspenso que não existe nesta instalação do Magento. Verificar Lojas > Atributos. Os valores suspensos diferenciam maiúsculas de minúsculas e espaços em branco. “Vermelho ” com um espaço à direita não é “Vermelho”.

Importar “completa” mas os produtos não aparecem no frontend

A reindexação não foi executada, ou o cache está obsoleto. SSH e execute indexador bin/magento:reindexar Seguido por cache bin/magento:liberar. Em 2.4.8 com indexadores Update by Schedule isso é mais raro, mas ainda acontece com URLs de produtos e indexadores de ações.

“A chave de URL da loja especificada já existe”

Você está importando um produto cujo url_key colide com um existente. Altere a chave de URL no seu CSV ou defina o comportamento como “Adicionar/atualizar” em vez de um fresco “Anexar dados complexos” correr.

Requisitos de hospedagem para grandes importações

Hospedagem compartilhada mata mais importações de Magento do que CSVs ruins. Se você estiver executando uma produção 2.4.8 loja, o chão honesto é 4 GB de RAM e 2-4 vCPUs; catálogos reais (10k+ SKUs, reimportações frequentes) precisar 8-16 GB. O disco deve ser SSD NVMe, não girando unidades ou SSDs SATA antigos, porque as operações de reindexação e redimensionamento de imagem martelam E/S aleatória.

Coisas específicas que um host pronto para Magento deve permitir que você faça:

• Edite php.ini (ou equivalente por domínio) para aumentar o limite de memória e o tempo de execução
• Instale e execute o cron (A importação em massa assíncrona do Magento usa a fila de consumidores)
• Acesso SSH para bin/magento Comandos CLI
• Espaço de disco suficiente para var/importar/imagens pode armazenar seu maior lote duas vezes (Cópias Magento, não se move)

Se o seu host atual não puder entregá-los, o importador não é o seu verdadeiro problema. Nosso Resumo de hospedagem Magento VPS detalha quais provedores enviam uma pilha pronta para 2.4.8 sem sobretaxas, e a ferramenta de busca de hospedagem filtros por versão do PHP, RAM, e painel de controle se você quiser comparar planos lado a lado. Para comerciantes que executam WooCommerce junto com Magento (isso acontece mais do que você imagina), a Guia de hospedagem de comércio eletrônico WordPress cobre a pilha cruzada.

perguntas frequentes

Qual é o tamanho máximo de arquivo CSV que posso importar no Magento 2.4.8?

O importador administrativo limita os uploads em 2MB por padrão, controlado por PHP upload_max_filesize e post_max_size. Aumente ambos para 64M no php.ini para arquivos maiores. Para qualquer coisa além de 50 MB compactados, mude para REST /V1/importação/csv ponto final, que lida com cargas gzipadas e não causa gargalos no upload do navegador.

Posso importar produtos no Magento 2 sem usar CSV?

sim. A API REST do Magento 2.4.8 aceita CSV e JSON via /V1/importação/json. Extensões de terceiros (Urso de fogo, Amasty, Magmi para instalações mais antigas) suporte XML, Sincronização do Planilhas Google, e conectores ERP diretos. O administrador nativo ainda requer CSV, então escolha seu caminho com base nas necessidades de automação.

Quanto tempo leva uma importação de 10.000 produtos?

Em um sintonizado 2.4.8 pilha (8 GB de RAM, NVMe, PHP 8.4, MariaDB 11.4), esperar 15-25 minutos para uma importação de 10 mil linhas com imagens. A hospedagem compartilhada leva isso para 60+ minutos se for concluído. O caminho em massa REST assíncrono é executado em segundo plano, para que as páginas voltadas para o comprador permaneçam responsivas durante a importação.

Por que minha importação é bem-sucedida, mas mostra preços ou estoque errados?

Duas causas comuns. Primeiro, seu CSV tem espaço em branco ou formatação decimal europeia (1,99 em vez de 1.99) na coluna de preço; Magento os analisa como inválidos e mantém o valor antigo. Segundo, inventário de várias fontes (MSI) no 2.4.8 armazena quantidade por fonte, não por produto globalmente, então você precisa do código_fonte coluna ou a importação atualiza apenas a fonte padrão.

Preciso desabilitar o catálogo simples do Magento antes de importar?

O catálogo simples foi descontinuado em 2.3 e removido dos fluxos de trabalho padrão por 2.4.5. Se de alguma forma sua loja ainda estiver habilitada, desative-o em Lojas > Configuração > Catálogo > Loja antes de grandes importações. Sempre foi uma responsabilidade de desempenho e 2.4.8 deixa isso explícito no admin.

Posso automatizar a importação de produtos de um ERP ou PIM?

É exatamente isso que 2.4.8 Os pontos de extremidade REST são para. Ferramentas como Akeneo, Pimcore, e Salsify têm Magento nativo 2 conectores. Para compilações personalizadas, cron um script que extrai seu feed ERP, transforma para CSV, gzip, e POSTs para /V1/importação/csv. Programe-se para horários fora de pico se a importação for pesada.

Notas Finais

Duas regras decidem se sua próxima importação funcionará. Um: salve o CSV como UTF-8 sem BOM. Sempre. Dois: aumentar PHP limite_de_memória e tempo_máximo_de_execução antes que você comece, não depois do primeiro acidente. Todo o resto é detalhe.

Em termos de caminho, a chamada é simples. Debaixo 5,000 SKUs e execução de importações ocasionalmente? Use a ferramenta CSV de administração. Passado 10,000 SKUs ou sincronização de um ERP todas as noites? Utilize o REST /V1/importação/csv ponto de extremidade adicionado em 2.4.8 e pare de cuidar do processo. Faça backup do banco de dados antes de qualquer execução de substituição ou exclusão. Nunca feche a guia do navegador durante a importação. E se a pilha embaixo não aguentar, nenhuma tática de importador o resgata. Corrija o host primeiro.

Para leitura relacionada: a Resumo do tema Magento cobre o desempenho do front-end após o carregamento do seu catálogo, o manual de velocidade vinculado acima lida com a pilha de cache, e os guias de hospedagem cobrem como executar tudo. As enfadonhas escolhas de infraestrutura aumentam mais rapidamente do que qualquer sinalizador de recurso único.