Automação de arquivos de catálogo: gerenciando anúncios em múltiplos marketplaces da Amazon

O sistema de arquivos de catálogo da Amazon é a interface mais completa para gerenciamento de anúncios em lote em catálogos extensos, e uma das menos documentadas para operações em múltiplos marketplaces. Cada marketplace utiliza uma versão diferente do modelo, impõe requisitos de campos distintos e aplica regras de validação diferentes — muitas vezes para o mesmo produto na mesma categoria. Gerenciar anúncios em dez marketplaces a partir de uma única fonte de dados de produtos exige uma abordagem sistemática para a variação de modelos, tradução de atributos e o ciclo de upload-validação-correção.

Este artigo descreve o fluxo de trabalho com arquivos de catálogo que utilizamos para o gerenciamento de catálogos em múltiplos marketplaces: como os modelos diferem entre si, onde a automação traz mais benefícios e onde a intervenção manual ainda é inevitável.

O que são arquivos de catálogo

Um arquivo de catálogo (flat file) é uma planilha com campos separados por tabulações que a Amazon utiliza para processar a criação e a atualização de anúncios em lote. Cada linha representa um produto. Cada coluna representa um atributo. O modelo — baixado na seção Catálogo > Adicionar produtos via upload do Seller Central — define quais colunas são obrigatórias, quais são opcionais e quais são os valores válidos para cada campo.

O sistema de arquivos de catálogo é anterior à SP-API Listings Items API e continua sendo a principal interface de edição em lote dentro do Seller Central. No lado da API, a Amazon declarou obsoletos os feeds de anúncios em arquivos tabulares e XML em março de 2024, com remoção prevista para 30 de junho de 2025, em favor da Listings Items API baseada em JSON e de JSON_LISTINGS_FEED; os uploads de arquivos de catálogo pelo Seller Central não foram afetados. Para qualquer vendedor com mais de algumas dezenas de SKUs em múltiplos marketplaces, um fluxo de trabalho em lote é praticamente necessário e, na nossa configuração, o arquivo de catálogo é a principal interface de gerenciamento de catálogos.

Na prática, porém, a documentação que a Amazon fornece para arquivos de catálogo é fragmentada e frequentemente desatualizada. A especificação mais atual para um dado modelo é o próprio modelo, baixado recentemente, para o marketplace e a categoria específicos que você está gerenciando. Utilizar modelos armazenados em cache ou documentação de seis meses atrás é uma causa recorrente de erros de upload.

Diferenças de modelo entre marketplaces

As diferenças estruturais entre os modelos de cada marketplace são maiores do que a maioria dos vendedores espera quando tenta operar em múltiplos marketplaces pela primeira vez. Não se trata de simples traduções dos mesmos campos.

O modelo de Vestuário dos EUA para uma determinada categoria pode ter cinquenta colunas de atributos. O modelo equivalente alemão pode ter sessenta, incluindo campos sem equivalente nos EUA — declarações específicas de conformidade química exigidas pela regulamentação europeia ou requisitos de etiqueta energética aplicáveis a certos tipos de produto. O modelo japonês pode estruturar variações de tamanho e cor de forma diferente, usando nomes de temas de variação distintos dos reconhecidos pela versão americana.

Os valores válidos para um campo específico frequentemente diferem por marketplace, mesmo quando o nome do campo é o mesmo. O campo item_type_keyword aceita strings diferentes em .com e em .co.uk. Os valores de color_name são validados com base em uma lista específica do marketplace; um nome de cor aprovado nos EUA pode ser rejeitado na Alemanha ou no Japão por não constar no conjunto de valores aprovados para aquele mercado. Essas rejeições nem sempre são claras no relatório de erros — você recebe um erro genérico de atributo, em vez de uma indicação direta de que o valor não está na lista aprovada.

As versões dos modelos são atualizadas sem aviso prévio. Periodicamente, a Amazon lança novas versões de modelos para uma categoria, adicionando campos obrigatórios ou descontinuando os antigos. Se você fizer upload com uma versão de modelo que não é mais atual, o upload pode ser concluído com sucesso, mas o anúncio pode não ser indexado corretamente — ou determinados atributos podem ser silenciosamente ignorados. Baixamos modelos atualizados no início de qualquer atualização significativa de catálogo, em vez de reutilizar versões salvas.

Conversões de sistemas de tamanhos

Para vestuário e calçados, a conversão de sistemas de tamanhos é um dos aspectos mais trabalhosos do gerenciamento de catálogos em múltiplos marketplaces. Os sistemas de tamanhos dos EUA, da UE, do Reino Unido e do Japão não são diretamente equivalentes, e as tabelas de conversão não são uniformes entre os tipos de produto.

Um sapato feminino que é tamanho 8 nos EUA geralmente corresponde ao tamanho 6 no Reino Unido e ao tamanho 39 na UE nas tabelas de conversão comuns (as tabelas das marcas podem diferir em meio número), mas uma blusa feminina tamanho M dos EUA pode ser equivalente ao tamanho 38 ou 40 na UE, dependendo das convenções de tamanho da marca. Não existe uma tabela de conversão universal. A abordagem correta é manter um mapeamento mestre de tamanhos por tipo de produto por marca, validado com base no guia de medidas específico do fabricante.

Os campos size_name e size_system da Amazon devem ser preenchidos corretamente em conjunto para que o anúncio seja exibido adequadamente nos filtros de navegação do marketplace. Um anúncio enviado com um tamanho americano no campo size_name sem uma declaração de size_system pode ser tratado como uma string não formatada e, na nossa experiência, pode não aparecer nos resultados de busca filtrados por tamanho. Isso nem sempre é evidente na confirmação do upload — o anúncio é criado com sucesso, mas a filtragem por tamanho não funciona.

Para o marketplace japonês especificamente, o sistema de tamanhos difere tanto das convenções europeias quanto das americanas em muitas categorias de produtos. Os tamanhos de roupas japonesas usam um sistema numérico separado. Os tamanhos de calçados utilizam um sistema baseado em centímetros. O campo size_map_unit_of_measure era obrigatório nos modelos japoneses com os quais trabalhamos e não estava presente nos equivalentes dos EUA ou da UE — um campo cuja ausência causava falhas silenciosas no processamento quando modelos eram reutilizados entre mercados. Os nomes dos campos variam conforme o tipo de produto e a versão do modelo, então verifique os cabeçalhos de coluna e os valores válidos no modelo que você realmente baixar.

Limites de palavras-chave de backend

As palavras-chave de backend — os termos de busca enviados no campo generic_keyword — diferem em limites de caracteres entre marketplaces, e o tipo de limite também varia.

Amazon.com impõe um limite de 249 bytes no campo generic_keyword combinado. Amazon.de também impõe um limite baseado em bytes, mas o texto em alemão contém mais caracteres multibyte do que o inglês, o que significa que uma string de palavras-chave que cabe em inglês dentro do limite de bytes dos EUA pode ultrapassar o limite de bytes alemão quando traduzida. Amazon.co.jp impõe limites que interagem com a codificação de caracteres japoneses — um único caractere kanji ocupa três bytes em UTF-8, portanto a capacidade efetiva de palavras-chave em japonês é substancialmente menor do que o limite em bytes implica ao ser medido em caracteres latinos.

Na prática, porém, o limite de palavras-chave é uma das variáveis de menor impacto no desempenho de anúncios em múltiplos marketplaces. Observamos que a otimização excessiva de palavras-chave de backend — preencher o campo até o limite exato de bytes — produz retornos decrescentes em comparação com a otimização do título visível, dos tópicos de destaque e da descrição para o comportamento de busca em linguagem natural. Os limites de bytes são uma restrição a ser respeitada, não uma alavanca de desempenho a ser maximizada.

A abordagem prática é manter um conjunto de palavras-chave específico para cada marketplace por produto, dimensionado para caber dentro dos limites daquele mercado, e verificar a contagem de bytes programaticamente, e não por inspeção visual. Uma simples função Python que codifica a string de palavras-chave e mede o comprimento em bytes em relação ao limite do marketplace captura erros de truncamento antes de chegarem à etapa de upload.

O fluxo de automação

A principal conclusão por trás da automação de arquivos de catálogo é que a variação entre marketplaces é principalmente estrutural, não semântica. O produto é o mesmo — as dimensões, os materiais, o uso pretendido e as principais características não mudam. O que muda é como essas informações devem ser representadas no formato de modelo de cada marketplace.

Mantemos uma planilha de dados mestres de dados do produto com todos os atributos armazenados em um formato neutro: dimensões no sistema métrico, tamanhos no sistema nativo do fabricante, palavras-chave no idioma de origem, categorias mapeadas para uma taxonomia interna neutra. Arquivos de catálogo específicos para cada marketplace são gerados a partir desta planilha de dados mestres mediante a aplicação de uma camada de transformação que trata as diferenças estruturais para cada mercado-alvo.

A camada de transformação é um script — no nosso caso escrito em Python — que mapeia cada atributo dos dados mestres para a coluna do arquivo de catálogo correspondente em cada marketplace, aplica conversões de tamanho, traduz a taxonomia de categorias para a estrutura de nós de navegação do marketplace e aplica validação no nível de cada campo antes de gerar o arquivo de saída. Campos que requerem revisão manual — textos traduzidos, declarações de conformidade específicas do marketplace, atributos regulatórios por país — são sinalizados na saída em vez de ser preenchidos automaticamente.

O próprio ciclo de download-edição-upload é semiautomatizado. Os downloads são executados por scripts via SP-API Reports API, que expõe os tipos de relatório GET_FLAT_FILE_OPEN_LISTINGS_DATA e correlatos. O processamento do download, a comparação com a planilha de dados mestres e a geração do arquivo de upload são automatizados. O próprio upload e a revisão do relatório de processamento do upload são etapas manuais — não porque a automação seja impossível, mas porque o custo de um erro em um upload em grande escala é alto o suficiente para justificar uma revisão humana antes de os arquivos serem enviados à Amazon.

Modos comuns de falha

Os erros de upload se dividem em três categorias: falhas de validação, falhas de processamento e falhas silenciosas.

As falhas de validação são as mais diretas — o relatório de upload retorna mensagens de erro explícitas identificando a linha e o campo que falharam. As causas mais comuns são valores inválidos para campos de vocabulário controlado (size_name, color_name, item_type_keyword), campos obrigatórios ausentes para a versão específica do modelo e violações do limite de bytes em campos de palavras-chave ou descrição.

As falhas de processamento ocorrem quando o upload passa na validação, mas o anúncio não é atualizado conforme esperado. As causas comuns incluem erros de relacionamento de variação — um ASIN filho enviado sem um pai correspondente, ou um pai enviado com um tema de variação que não corresponde aos atributos do filho — e conflitos de nós de navegação em que o nó enviado não coincide com a classificação existente de um ASIN já estabelecido.

As falhas silenciosas são as mais difíceis de detectar. O upload é bem-sucedido, o relatório de processamento não mostra erros, mas o anúncio se comporta incorretamente. Um tamanho que não aparece nos filtros de navegação. Um termo de busca que não é indexado. Um relacionamento de variação que aparece no backend, mas não é renderizado corretamente na loja online. Essas falhas exigem a comparação dos atributos do anúncio publicado com os valores enviados por meio da Catalog Items API, não por inspeção visual da loja online.

A defesa prática contra falhas silenciosas é uma etapa de verificação pós-upload: extraia os dados do anúncio publicado via API para cada ASIN afetado dentro de vinte e quatro horas após o upload, compare com os valores enviados e sinalize discrepâncias. Essa etapa não é complexa, mas é o que separa um processo de gerenciamento de catálogos confiável de um que exige auditorias manuais constantes para detectar mudanças inexplicadas em anúncios que nenhum relatório de erros jamais anunciou.