Quer atualizar produtos WooCommerce por GTIN usando um CSV, sem cadastrar o mesmo item de novo? As notas oficiais da versão 11.2.0 confirmam uma nova correspondência por identificador global quando a opção Atualizar produtos existentes está ativa e não há ID nem SKU na linha. É uma possibilidade para testar, não uma garantia de que qualquer planilha estará livre de duplicatas.
Atenção à versão: o WooCommerce 11.2.0 foi lançado em 07/10/2026. Este checklist trata de teste em staging, com backup restaurável, antes de qualquer uso operacional; não instale uma versão beta na loja que recebe pedidos. Atualizar o plugin envolve também atualização de banco de dados: confira o guia de atualização e a compatibilidade das extensões da sua instalação antes de mudar a versão em produção.
O que o importador CSV da 11.2 promete — e o que não promete
Com Atualizar produtos existentes marcada, a ordem anunciada para encontrar um produto é ID → SKU → identificador global (GTIN, UPC, EAN ou ISBN). Portanto, um GTIN não tem prioridade sobre um ID ou SKU da linha. Para isolar a correspondência por GTIN no teste, use um CSV pequeno cuja linha de teste não tenha ID nem SKU, mas contenha o identificador global mapeado e já cadastrado no item de destino. Não altere os identificadores do catálogo real para conseguir fazer esse teste.
Segundo o PR que implementa a regra na 11.2, se um identificador global não vazio não encontrar produto, a linha é pulada em vez de criar um produto; se o tipo do item encontrado não corresponder ao tipo da linha, a atualização é recusada. Isso vale para o cenário descrito, não para toda importação, extensão ou versão. Identificador vazio não oferece essa proteção; o PR também documenta a possibilidade de códigos iguais em produtos distintos. Antes de testar, confira se o identificador aponta para um único item esperado no staging. Não tente atualizar uma base com códigos duplicados ou com mapeamento incerto.
Há outra ressalva: a documentação oficial do importador CSV informa que, desde a 11.1, algumas linhas de variações sem correspondência podem criar uma nova variação quando pai, atributos e identificador atendem às condições documentadas. Portanto, não aplique a regra de “linha pulada” indiscriminadamente às variações. O procedimento principal abaixo usa produtos simples.
Antes de importar: backup, staging e amostra
- Faça backup restaurável de arquivos e banco de dados antes de atualizar o WooCommerce ou mexer no catálogo. Guarde também a exportação anterior do conjunto de produtos testados. Veja como preparar o backup do WordPress.
- Use uma cópia de staging isolada, sem pedidos reais, envios de email, webhooks ou sincronizações com ERP ativos. Não copie o banco de staging por cima da loja em produção após o teste: isso pode substituir pedidos recentes. Se não conseguir isolar integrações e recuperar a cópia, não execute a importação.
- Anote a versão exata do WooCommerce no staging. Escolha poucos produtos simples cuja identidade você consiga confirmar por ID, SKU e identificador global; registre tipo, descrição, preço, estoque e status antes do teste. Se um plugin armazena EAN em metadado próprio, não presuma que o importador nativo usa esse campo.
Se ainda estiver estruturando o cadastro, o guia de criação de loja WooCommerce apresenta os conceitos gerais; este teste não substitui a organização do catálogo.
Como preparar um CSV de teste por GTIN
- Em Produtos > Todos os produtos > Exportar no staging (nomes podem variar pela tradução), exporte somente os produtos escolhidos, com as colunas necessárias. Preserve o CSV original intacto e compare-o com o estado dos produtos no painel.
- Crie uma cópia em CSV UTF-8 com uma ou poucas linhas de produto simples. Para testar especificamente GTIN, retire ID e SKU apenas dessas linhas na cópia, mantendo um identificador global válido, não vazio, já salvo no produto de destino e sem duplicidade conhecida. Não use um cabeçalho “EAN” vindo de fornecedor como prova de mapeamento: confira em tela o campo reconhecido na instalação. A documentação geral não estabelece um cabeçalho universal aplicável a toda extensão.
- Altere somente um campo informativo controlado, como uma descrição de teste, após conferir que ele é importável. Evite mexer em preço, estoque, publicação, tipo, pai ou atributos. Confira na tela de mapeamento se não há colunas indesejadas que possam sobrescrever dados.
- Prepare lotes separados para cada hipótese: identificador existente; identificador não correspondente e não vazio; e, se houver técnico responsável, casos de prioridade ID/SKU e conflito de tipo. Para o caso não correspondente, use um código controlado, verifique o catálogo de staging antes e depois e não o leve à produção. Não provoque conflitos em loja real.
Passo a passo: importar e verificar sem presumir o resultado
- Confirme o ambiente de staging, a versão, o backup e o produto-alvo único. Anote ID, SKU, identificador, tipo, preço, estoque e descrição.
- Em Produtos > Todos os produtos > Importar, selecione o arquivo pequeno e marque Atualizar produtos existentes. Sem essa opção, você não está testando a correspondência anunciada para atualização.
- Avance até Mapeamento de colunas. Confira que o identificador está ligado ao campo correto, não a “Não importar” nem a um metadado desconectado do identificador nativo; valide os outros campos. Se o mapeamento não puder ser comprovado na versão testada, cancele. Ver a prévia de colunas não é fazer uma simulação da importação.
- Só então execute o importador. Aguarde o resultado sem iniciar importações simultâneas nem interromper o processamento. Examine o relatório de itens atualizados, pulados ou com erro.
- Reabra o produto-alvo e exporte o mesmo recorte. Compare por ID: mudou apenas a descrição esperada no produto correto? Surgiu outra linha com o mesmo identificador? Permaneceram iguais tipo, preço, estoque e status? Registre a diferença e investigue qualquer desvio antes de ampliar o lote.
Se também for atualizar a versão do plugin na loja, siga separadamente o checklist de atualização segura do WooCommerce.
Matriz de cenários para conferir no staging
| Linha do CSV com atualização marcada | Comportamento descrito para a 11.2 | O que verificar |
|---|---|---|
| Produto simples sem ID/SKU, identificador global mapeado e único no catálogo | Atualiza o produto correspondente | Mesmo ID antes/depois; apenas campo planejado mudou; nenhum item adicional. |
| ID ou SKU presente junto com identificador global | ID/SKU têm precedência na correspondência | Qual item foi alterado; não use dados conflitantes em produção. |
| Sem ID/SKU, identificador global não vazio e não correspondente | Linha pulada, segundo as notas | Relatório e contagem de produtos; interrompa se houver criação inesperada. |
| Identificador encontra item de tipo diferente do tipo da linha | Atualização recusada, segundo as notas | Erro no relatório e tipo inalterado. |
| Linha de variação com pai e atributos elegíveis | A exceção documentada desde a 11.1 pode criar variação | Teste isolado com responsável técnico; confira pai, atributos e contagem de variações. |
Não generalize: identificador em branco, códigos repetidos, campos de plugin e importadores de terceiros precisam de verificação própria. Para entender por que uma variação não é equivalente a uma opção personalizada, veja variações e opções extras de produtos.
Se houver duplicata, linha pulada ou alteração indevida
Pare antes do próximo lote. Salve o relatório, localize a linha do CSV e compare a exportação anterior à posterior. Confira opção de atualização, versão, mapeamento, unicidade do identificador, ID/SKU e tipo. Importações interrompidas não devem ser repetidas cegamente: a discussão técnica sobre marcadores de importação registra diferenças entre retomar o mesmo arquivo e enviar outro arquivo com IDs reutilizados. Não faça importações concorrentes.
Não exclua produtos em massa para “corrigir” o teste. Se necessário, restaure somente o staging com o responsável técnico e compare novamente. Se algum dado da loja publicada já tiver sido alterado, peça avaliação ao administrador/hospedagem antes de restaurar um backup antigo, que poderia apagar pedidos posteriores. Um plano de produção exige backup atual, janela, amostra, responsável pelo catálogo e reversão definida; não decorre automaticamente de um teste bem-sucedido no staging.
Perguntas frequentes
GTIN e SKU são a mesma coisa?
Não. SKU identifica o item na organização da loja; GTIN, UPC, EAN e ISBN são tipos de identificadores globais. Na ordem anunciada para a 11.2, SKU vem antes do identificador global.
Posso importar apenas o GTIN e deixar ID e SKU em branco?
Para isolar a correspondência de atualização da versão compatível, é possível testar uma linha sem ID/SKU, desde que o identificador esteja mapeado e já cadastrado no produto único esperado, a opção de atualização esteja marcada e o resultado seja auditado. Não é receita para importar catálogo novo nem para presumir que variações não serão criadas.
Um GTIN que não existe cria produto?
Conforme o PR incorporado à 11.2, com atualização de existentes ativa, um identificador global não vazio sem correspondência faz a linha ser pulada. A afirmação não cobre importação de novos produtos, células vazias, extensões ou todas as variações.
Conclusão
Para testar a atualização de produtos WooCommerce por GTIN na 11.2, use staging e backup, uma amostra de produtos simples, CSV derivado da exportação, campo corretamente mapeado e Atualizar produtos existentes ativado. Confira relatório e diferenças por ID, preço, estoque e tipo antes de decidir qualquer operação maior. Revalide a versão instalada, suas extensões e o plano de atualização antes de usar o procedimento numa loja ativa.
