Automação de Flatfile: Gerenciando Anúncios de Produtos em Múltiplos Marketplaces da Amazon
O sistema de flatfile 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 template, 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 produto exige uma abordagem sistemática para a variação de templates, tradução de atributos e o ciclo de upload-validação-correção.
Este artigo descreve o fluxo de trabalho com flatfiles que utilizamos para o gerenciamento de catálogos em múltiplos marketplaces: como os templates diferem entre si, onde a automação oferece mais alavancagem e onde a intervenção manual ainda é inevitável.
O que são Flatfiles
Um flatfile é uma planilha delimitada por tabulações que a Amazon utiliza para processar criação e atualização de anúncios em lote. Cada linha representa um produto. Cada coluna representa um atributo. O template — baixado na seção Inventário > 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 flatfiles é anterior à SP-API Listings API e continua sendo a forma mais completa de gerenciar certos tipos de atributos que a API ainda não expõe completamente. Variações específicas por categoria, atribuições de browse node e determinados campos de conformidade ainda são operações exclusivas de flatfile em vários marketplaces. Para qualquer vendedor com mais de algumas dezenas de SKUs em múltiplos marketplaces, o fluxo de trabalho com flatfiles não é opcional — é a principal interface de gerenciamento de catálogos.
Na prática, porém, a documentação que a Amazon fornece para flatfiles é fragmentada e frequentemente desatualizada. A especificação mais atual para um dado template é o próprio template, baixado recentemente, para o marketplace e a categoria específicos que você está gerenciando. Utilizar templates armazenados em cache ou documentação de seis meses atrás é uma fonte confiável de erros de upload.
Diferenças de Template entre Marketplaces
As diferenças estruturais entre os templates 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 template de Vestuário dos EUA para uma determinada categoria pode ter cinquenta colunas de atributos. O template 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 template 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 contra 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 templates são atualizadas sem aviso prévio. Periodicamente, a Amazon lança novas versões de templates para uma categoria, adicionando campos obrigatórios ou descontinuando os antigos. Se você fizer upload com uma versão de template 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 templates 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 corresponde ao tamanho 6 no Reino Unido e ao tamanho 39 na UE, 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 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 será tratado como uma string não formatada e 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 é obrigatório no template japonês e não está presente nos equivalentes dos EUA ou da UE — um campo cuja ausência causa falhas silenciosas no processamento quando templates são reutilizados entre mercados.
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 dentro do limite de caracteres 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 super-otimização 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 bullet points 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
O principal insight por trás da automação de flatfiles é 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 os recursos principais não mudam. O que muda é como essas informações devem ser representadas no formato de template de cada marketplace.
Mantemos uma planilha mestre de dados do produto com todos os atributos armazenados em um formato neutro: dimensões em métrico, tamanhos no sistema nativo do fabricante, palavras-chave no idioma de origem, categorias mapeadas para uma taxonomia interna neutra. Flatfiles específicos para cada marketplace são gerados a partir desta planilha mestre 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 mestre para a coluna de flatfile correspondente em cada marketplace, aplica conversões de tamanho, traduz a taxonomia de categorias para a estrutura de browse node do marketplace e aplica validação a nível de 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 realizados 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 mestre 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 template 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 browse node 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 no storefront. Essas falhas exigem a comparação dos atributos do anúncio ao vivo com os valores enviados por meio da Catalog Items API, não por inspeção visual do storefront.
A defesa prática contra falhas silenciosas é uma etapa de verificação pós-upload: extraia os dados do anúncio ao vivo 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.
Insights Relacionados
- Expansão do Amazon FBA para Novos Marketplaces: Um Framework Orientado por Dados — o framework de seleção de mercado que precede as decisões de gerenciamento de anúncios
- Construindo um Data Warehouse da Amazon com FastAPI e TimescaleDB — como armazenamos e consultamos dados de catálogo e desempenho de anúncios para embasar decisões de atualização