Como importar produtos em massa para o WooCommerce

Opção 1: o importador de CSV integrado do WooCommerce

O WooCommerce vem com um importador e exportador de CSV de produtos. No painel do WordPress, vá para Produtos → Todos os produtos e escolha Importar. Carregue o seu CSV, associe as colunas aos campos do WooCommerce e execute a importação. Marcar “Atualizar produtos existentes” permite atualizar os produtos identificados por ID ou SKU em vez de criar duplicados.

• Exporte primeiro um produto existente e use esse arquivo como modelo — ele mostra os nomes exatos das colunas que a sua loja espera.
• As colunas típicas incluem Type, SKU, Name, Published, Short description, Description, Regular price, Categories, Tags, Images e Attribute 1 name / Attribute 1 value(s).
• As imagens são importadas a partir de URLs, por isso têm de estar acessíveis publicamente quando a importação é executada.
• Os produtos variáveis precisam de uma linha-mãe do tipo “variable” e de uma linha por variação que faça referência à linha-mãe.
• Arquivos muito grandes podem expirar em hospedagem compartilhada — divida-os em lotes de algumas centenas de linhas.

Opção 2: plugins de importação

Os plugins de importação de terceiros acrescentam recursos que faltam ao importador nativo: importações agendadas ou recorrentes a partir de um feed do fornecedor, suporte a XML, regras de transformação de campos e melhor tratamento de arquivos muito grandes. Fazem sentido quando um fornecedor envia regularmente arquivos atualizados de preços e estoque.

Os plugins continuam a esperar dados estruturados. Se o seu fornecedor fornece PDFs em vez de um feed, um plugin não elimina o trabalho de transformar esses PDFs em linhas.

Opção 3: a REST API do WooCommerce

Desenvolvedores e ferramentas de integração podem criar produtos por meio da REST API do WooCommerce, incluindo um endpoint em lote que cria ou atualiza muitos produtos numa única requisição. Isso serve para pipelines automatizados e aplicações que criam produtos diretamente, sem uma etapa de CSV.

O Doc2Shelf usa este caminho: depois da revisão, envia os produtos para o WooCommerce como produtos simples em rascunho, com descrições longas e curtas, para que você os confira no WooCommerce antes de os publicar. Os atributos globais de filtro e os produtos variáveis são configurados separadamente no WooCommerce.

Preparar os dados de produto para uma importação em massa

Seja qual for o método de importação, a qualidade dos dados decide o resultado. Antes de importar:

• Atribua a cada produto um SKU único — é assim que as atualizações posteriores encontram o produto certo.
• Crie primeiro as categorias e os atributos globais no WooCommerce e depois faça referência a eles de forma consistente.
• Normalize as especificações: mesmas unidades, mesmos nomes de atributo, um valor por célula.
• Escreva descrições de verdade em vez de colar texto do fornecedor; os marketplaces e os mecanismos de busca valorizam textos únicos.
• Importe como rascunhos numa primeira execução — defina Published como -1 (0 torna os produtos privados) — e reveja uma amostra antes de publicar tudo.

Quando o seu fornecedor só envia PDFs

Muitos fornecedores fornecem fichas técnicas e catálogos em PDF, e não feeds em CSV. Nesse caso, o gargalo é a extração: alguém tem de ler cada PDF, preencher as colunas e redigir uma descrição.

Você pode fazer isso manualmente ou extrair os dados com uma ferramenta e revisá-los. O Doc2Shelf lê os PDFs dos fornecedores, extrai as especificações para revisão, redige descrições longas e curtas para o WooCommerce e cria os produtos como rascunhos por meio da REST API — substituindo a etapa da planilha nos catálogos provenientes de PDFs.

Erros comuns de importação no WooCommerce

Se uma importação falha ou produz resultados inesperados, verifique primeiro:

• SKUs duplicados ou ausentes, que fazem com que linhas sejam ignoradas ou produtos sejam duplicados.
• Codificação de arquivo incorreta — salve o CSV em UTF-8 para que os caracteres acentuados sejam importados corretamente.
• URLs de imagens que redirecionam, exigem login ou apontam para arquivos muito grandes.
• Caminhos de categorias escritos de forma inconsistente (use “Pai > Filho” para categorias aninhadas).
• Variações cujos valores de atributo não correspondem aos valores de atributo do produto-pai.

Referência das colunas do CSV de produtos do WooCommerce

O importador nativo lê um conjunto fixo de nomes de colunas. Exportar um produto da sua própria loja dá-lhe os cabeçalhos exatos que a sua versão do WooCommerce espera; a tabela abaixo explica as colunas mais importantes para um carregamento em massa. Só Name é obrigatória — todas as outras colunas são facultativas, mas um catálogo importado sem Type, SKU, preços e categorias deixa muito trabalho manual para depois.

As colunas com uma unidade no cabeçalho, como Weight e as três dimensões, mostram a unidade configurada nas definições da sua loja, pelo que deve copiar esses cabeçalhos de uma exportação em vez de os escrever. Os dados personalizados que não têm coluna própria vão para uma coluna cujo cabeçalho começa por meta: seguido da chave do campo.

Produtos variáveis num CSV: linhas do produto principal e das variações

Um produto variável distribui-se por várias linhas: uma linha principal que define o produto e os valores de atributo que oferece, e uma linha por variação que contém o preço, o SKU e o stock de uma única combinação. A linha principal tem Type “variable”; cada linha de variação tem Type “variation” e remete para o produto principal na coluna Parent, usando o SKU do produto principal ou id: seguido do respetivo ID.

As colunas de atributos ligam as linhas entre si. No produto principal, Attribute 1 value(s) lista todos os valores que o produto oferece, separados por vírgulas. Em cada variação, o mesmo Attribute 1 name aparece com exatamente um desses valores. A ortografia e as maiúsculas têm de coincidir: uma variação que diga “vermelho” sob um produto principal que ofereça “Vermelho” pode ficar sem um valor de atributo utilizável.

Defina Attribute 1 global como 1 no produto principal e nas variações quando usar um atributo de toda a loja criado em Produtos → Atributos — é com esse que funcionam a navegação por filtros e os widgets de filtragem. Desde o WooCommerce 11.1, uma importação de atualização também pode acrescentar novas variações a um produto variável já existente, pelo que pode alargar uma gama sem reconstruir o produto principal.

• Mantenha cada linha principal acima das suas variações, para que o ficheiro seja fácil de verificar e o produto principal exista quando as variações o referenciam.
• Atribua a cada variação o seu próprio SKU e preço; uma variação sem preço não pode ser comprada.
• Use Attribute 1 default no produto principal para controlar qual a opção pré-selecionada.

Adicionar imagens de produto através do CSV

A coluna Images aceita um ou mais URL de imagens separados por vírgulas. O primeiro URL passa a ser a imagem de destaque e os restantes formam a galeria do produto pela ordem indicada. Durante a importação, o WordPress descarrega cada ficheiro para a sua biblioteca de multimédia, pelo que todos os URL têm de estar acessíveis publicamente nesse momento — sem início de sessão, sem ligação de partilha que expire e sem redirecionamento para uma página web em vez do ficheiro.

As imagens são normalmente a parte mais lenta de uma importação: algumas centenas de produtos com cinco imagens cada significam mais de mil descargas. Redimensione as imagens antes de as alojar, use nomes de ficheiro descritivos (kettle-red-front.jpg, e não IMG_0042.jpg) e divida os catálogos grandes em ficheiros mais pequenos.

O importador nativo não consegue definir o texto alternativo das imagens. Acrescente-o depois na biblioteca de multimédia, através da REST API ou com uma extensão de importação que o suporte. Uma variação só tem uma imagem, pelo que deve indicar, no máximo, um URL por linha de variação.

Criar produtos em massa com a REST API do WooCommerce

A REST API é o melhor caminho quando as importações se repetem, quando os dados de produto já estão noutro sistema ou quando ninguém deveria ter de lidar com um CSV. O seu endpoint de lote de produtos (POST /wp-json/wc/v3/products/batch) aceita operações de criação, atualização e eliminação num único pedido.

Por predefinição, um pedido em lote está limitado a 100 objetos entre criações, atualizações e eliminações. O mesmo limite aplica-se aos endpoints de lote de variações, categorias, atributos e termos de atributos. Um catálogo de 1000 produtos exige, por isso, pelo menos dez pedidos, e mais quando se acrescentam variações.

1. Crie uma chave da REST API com permissão de leitura/escrita em WooCommerce → Definições → Avançado → REST API, ou deixe uma aplicação pedi-la através do ecrã de autorização do WooCommerce.
2. Crie primeiro as categorias, os atributos globais e os termos de atributos, e anote os respetivos IDs.
3. Envie os produtos simples e os produtos principais em lotes de até 100, com o estado definido como rascunho.
4. Crie as variações de cada produto variável através do endpoint de lote de variações desse produto.
5. Verifique o resultado de cada item na resposta e repita apenas os itens que falharam.
6. Verifique por amostragem alguns rascunhos no painel de administração e depois publique-os.

Escolher um plugin ou um método de carregamento em massa de produtos para o WooCommerce

Se o importador nativo não chegar, avalie um plugin ou extensão de importação pela forma como trata os seus dados, e não pela extensão da lista de funcionalidades, e teste-o numa cópia de teste da loja com um ficheiro real de um fornecedor antes de se comprometer. A tabela compara os quatro métodos, seguida das perguntas que vale a pena fazer a qualquer plugin.

• Formatos de origem: apenas CSV, ou também XML, folhas de cálculo e feeds remotos obtidos por URL.
• Agendamento: se consegue repetir uma importação de acordo com um calendário para captar novos preços e stock.
• Mapeamento e transformações: renomear colunas, dividir valores, converter unidades e aplicar regras de preços durante a importação.
• Produtos variáveis: se cria de forma fiável produtos principais, variações e atributos globais.
• Imagens: como as descarrega, se deteta duplicados e se define o texto alternativo.
• Ficheiros grandes: processamento em segundo plano ou por partes, para que as importações longas não excedam o tempo limite.
• Regras de atualização: por que chave faz a correspondência (ID, SKU ou GTIN) e que campos pode substituir.

Checklist pré-importação e correção de erros

A maioria das importações falhadas remonta a um passo de preparação que foi saltado. Percorra a checklist antes de cada importação grande e use a tabela para diagnosticar os problemas que ainda surjam.

1. Faça uma cópia de segurança da base de dados, ou execute a importação numa cópia de teste da loja.
2. Exporte um produto existente e copie a respetiva linha de cabeçalhos para o seu ficheiro.
3. Crie as categorias, os atributos globais e os termos de atributos a que o ficheiro faz referência.
4. Verifique se todos os SKU são únicos e se o valor de Parent de cada variação corresponde ao SKU de um produto principal existente.
5. Use números simples nas colunas de preço, stock, peso e dimensões.
6. Abra uma amostra de URL de imagens numa janela de navegação privada para confirmar que carregam sem início de sessão.
7. Defina Published como -1 para que os produtos cheguem como rascunhos.
8. Guarde o ficheiro como CSV em UTF-8.
9. Importe um ficheiro de teste de dez linhas, reveja os resultados e só depois importe o resto em lotes.

Testar com produtos fictícios antes da importação real

Um pequeno ficheiro fictício apanha erros de mapeamento antes de chegarem a centenas de produtos. Crie-o a partir do seu modelo real, para que os cabeçalhos sejam idênticos, e dê a cada produto de teste um sinal evidente — um prefixo “TEST-” no SKU e uma etiqueta “test” — para poder encontrar e eliminar os produtos depois.

Cubra cada caso que o seu ficheiro real contém, e não apenas o mais fácil. Cerca de dez linhas costumam bastar:

• Um produto simples com todas as colunas que planeia usar preenchidas.
• Um produto variável com dois atributos e, pelo menos, três variações.
• Um produto com uma galeria de várias imagens e um sem imagens.
• Um produto numa categoria aninhada que ainda não existe.
• Um produto com caracteres acentuados, aspas e uma vírgula dentro da descrição.
• Uma linha que atualiza um produto existente através do SKU.
• Verifique os resultados no painel de administração e na loja — preços, menus pendentes das variações, ordem das imagens e páginas de categoria — e depois elimine os produtos de teste antes da importação real.