Erros do CSV de produtos Shopify: cabeçalho inválido e linhas ignoradas

O CSV de produtos da Shopify é implacável de uma forma muito particular: aceita o ficheiro, anuncia a importação concluída, e deixa-o com produtos sem variantes, preços a zero ou metade do catálogo em falta. Os erros que assinala são lacónicos.

Eis o que cada um significa.

«Invalid header» — um nome de coluna não reconhecido

A Shopify identifica as colunas pelo texto exato do cabeçalho. Variant price, variant_price e Price estão todos errados; a coluna chama-se Variant Price. As maiúsculas e os espaços contam.

A correção. Exporte um produto existente em Produtos → Exportar e use a linha de cabeçalho desse ficheiro como modelo. É sempre o conjunto de nomes correto e atual para a sua loja.

O handle é o que liga as linhas de variantes

URL handle é o slug de URL do produto: minúsculas, números e hífenes. Se o omitir num produto novo, a Shopify deduz-lo do Title, pelo que um handle vazio não é o que faz desaparecer produtos.

Onde decide tudo é nas variantes. Cada linha de variante tem de repetir o mesmo handle do produto pai, porque é a única coisa que as liga. Uma linha de variante com o handle vazio ou mal escrito torna-se um produto separado — a verdadeira causa do «o produto foi importado, mas cada tamanho é um artigo à parte».

E quando atualiza produtos existentes em vez de os criar, a documentação da Shopify é explícita: URL handle e Title são as colunas obrigatórias.

Variantes não criadas, ou fundidas num único produto

Esta é a parte do formato que apanha quase toda a gente. As variantes não são colunas: são linhas adicionais.

Um produto com três tamanhos ocupa quatro linhas no ficheiro:

• Linha 1 leva o produto completo: Handle, Title, Body (HTML), Vendor, Type, Tags, mais Option1 Name (Tamanho), Option1 Value (S), e o preço e o SKU dessa variante.
• Linhas 2 a 4 repetem o mesmo Handle, deixam Title e todas as outras colunas de nível produto vazias, e preenchem apenas Option1 Value (M, L) com o seu próprio preço, SKU e stock.

Daqui resultam duas formas de falhar:

• Repetir o Title em cada linha faz com que a Shopify trate cada uma como um produto distinto.
• Preencher Option1 Value deixando Option1 Name vazio na primeira linha faz ignorar as opções por completo.

Preços importados a 0, ou rejeitados

Variant Price e Variant Compare At Price têm de ser números puros com ponto como separador decimal. Sem símbolo monetário, sem separador de milhares, sem espaços.

1 299,00 € falha. 1299.00 funciona.

É um problema sistemático com exportações de ferramentas europeias, onde 1.299,00 é a forma normal de escrever o montante — e o Excel voltará a aplicar esse formato sempre que abrir o ficheiro.

A correção. Ponha a coluna de preço em formato Texto e escreva o valor em bruto, ou faça a conversão no momento da exportação. Atenção: mudar a forma como o Excel apresenta o número não chega — o que conta é o que fica no CSV guardado.

Acentos estragados

O ficheiro tem de estar em UTF-8. Um CSV guardado a partir de um Excel em português está em Windows-1252, por isso Café chega como Café.

A correção. Guardar como → CSV UTF-8 (delimitado por vírgulas) — a entrada separada na lista de formatos do Excel. O CSV simples não serve.

Imagens não importadas

Image Src tem de ser um URL completo e acessível publicamente — https://…, não um caminho local nem uma ligação atrás de autenticação. A Shopify descarrega cada imagem durante a importação; tudo o que não conseguir obter é ignorado em silêncio.

Para um produto com várias imagens, acrescente linhas extra que partilham o Handle, preenchendo apenas Image Src e Image Position.

Outros pontos úteis

• Published aceita TRUE ou FALSE; Status aceita active, draft ou archived.
• Variant SKU deve ser único em toda a loja — os duplicados tornam a gestão de stock imprevisível.
• Importar um Handle que já existe atualiza esse produto em vez de criar um novo. Muito prático de propósito, destrutivo por acidente.

Lista de verificação antes de importar

• Linha de cabeçalho copiada de uma exportação real da Shopify
• URL handle indicado ao atualizar produtos existentes (para os novos a Shopify deduz)
• As linhas de variante repetem o handle e deixam as colunas de produto vazias
• Option1 Name preenchido na primeira linha de cada produto
• Preços em números puros com ponto decimal
• Ficheiro guardado em CSV UTF-8
• URLs de imagem públicos e absolutos

Quando é o mesmo ficheiro de fornecedor todas as semanas

Montar isto à mão uma vez, para migrar um catálogo, é uma tarde razoável.

Refazê-lo todas as semanas sobre uma tabela de preços de fornecedor, não. A Importly pega na exportação em bruto, renomeia as colunas para os nomes da Shopify (Title, Variant SKU, Variant Price, Variant Grams, Image Src…), retira os símbolos monetários e converte os separadores decimais, normaliza pesos, quantidades e códigos de barras, corrige a codificação e elimina as linhas vazias. Guarde-o como perfil e o ficheiro da semana seguinte passa pelas mesmas regras — o Handle e as linhas de variantes continuam a seu cargo, porque a Importly limpa nomes de colunas e valores, não reestrutura linhas.

Limpar a sua primeira exportação gratuitamente →