Pipelines de dados para múltiplos marketplaces: contas de vendedor entre regiões

Escalar um pipeline de dados da Amazon de um marketplace para três não é questão de executar o mesmo código três vezes. Os marketplaces dos EUA, do Japão e da Alemanha diferem de maneiras mais fundamentais do que fusos horários: os formatos de relatório variam por marketplace para o mesmo tipo de relatório, o tratamento de moedas requer decisões explícitas sobre onde ocorre a conversão (e a qual taxa), as convenções de data são inconsistentes tanto nas respostas da API quanto nos arquivos baixados, e as estruturas de conta — unificada versus regional — afetam quais credenciais fornecem acesso a quais dados.

A maioria das equipes descobre essas diferenças sequencialmente: elas constroem para um marketplace e depois encontram cada discrepância individualmente ao estender para o próximo. A abordagem mais produtiva é projetar para múltiplos marketplaces desde o início, mesmo que a implantação inicial use apenas um. O custo marginal de uma arquitetura orientada por configuração é baixo. O custo de refatorar uma implementação para um único marketplace com valores embutidos no código para suportar regiões adicionais é alto.

Onde os marketplaces realmente diferem

A disponibilidade de relatórios varia mais do que a documentação da SP-API sugere. Certos tipos de relatório estão disponíveis em todos os marketplaces; outros são exclusivos da América do Norte, apenas da UE, ou disponíveis apenas em endpoints regionais específicos. Os relatórios que cobrem conformidade com IVA, por exemplo, são específicos para marketplaces da UE e não têm equivalente na América do Norte. Por outro lado, alguns relatórios de estoque FBA têm estruturas de colunas diferentes na Amazon.co.jp em comparação com a Amazon.com — o mesmo ID de tipo de relatório retorna esquemas diferentes dependendo do endpoint do marketplace.

O tratamento de datas e horas é uma fonte persistente de bugs sutis. A API da Amazon retorna timestamps em UTC, mas os arquivos de relatório baixados frequentemente usam o fuso horário local do marketplace para colunas de data sem declarar isso explicitamente. Quando um relatório usa a hora local, um arquivo para o marketplace japonês terá datas em JST e o mesmo relatório para a Alemanha usará CET ou CEST dependendo da época do ano; outras colunas, como posted-date-time do relatório de liquidação V2, são documentadas como estando em UTC. Código que trata todas as colunas de data como UTC produzirá erros de deslocamento de um dia nas agregações de data que são difíceis de detectar porque os dados parecem superficialmente corretos.

A moeda é a diferença com maior impacto operacional. A Amazon faz a liquidação na moeda local do marketplace: USD para os Estados Unidos, JPY para o Japão, EUR para a Alemanha. Um pipeline que armazena valores monetários brutos sem marcação de moeda explícita cria um problema de qualidade de dados que se acumula ao longo do tempo — quando o erro é percebido, meses de dados podem precisar ser corrigidos. O design correto armazena o código de moeda ao lado de cada valor monetário e adia a conversão para o momento da análise em vez de fixá-la no código da camada de extração.

Arquitetura orientada por configuração

O núcleo de um pipeline de múltiplos marketplaces fácil de manter é uma camada de configuração que captura todas as propriedades específicas de cada marketplace em um único lugar, em vez de dispersar lógica condicional por todo o código de extração. Cada marketplace recebe um bloco de configuração que especifica seu endpoint, referências de credenciais, fuso horário local, código de moeda, tipos de relatório suportados e quaisquer substituições de formato para relatórios que diferem do esquema base.

O próprio código de extração se torna agnóstico ao marketplace: ele lê a configuração para o marketplace de destino, seleciona as credenciais apropriadas, aplica o fuso horário correto aos campos de data e marca todos os valores monetários com o código de moeda configurado. Adicionar um novo marketplace requer adicionar um bloco de configuração e registrar quaisquer variações de formato — não modificar a lógica de extração.

Essa abordagem tem um benefício secundário: ela torna o modelo de dados explícito. Quando o código de moeda, o fuso horário e as variações de formato de relatório estão documentados em um arquivo de configuração em vez de embutidos em comentários de código, eles ficam visíveis para todos que trabalham com o pipeline — não apenas para o desenvolvedor que originalmente lidou com cada caso excepcional.

Estado YAML por marketplace

O rastreamento de estado em YAML descrito para pipelines de um único marketplace se estende naturalmente à operação de múltiplos marketplaces, mas a estrutura do arquivo de estado requer uma escolha deliberada: um arquivo de estado por marketplace, ou um arquivo com seções com escopo de marketplace.

Arquivos de estado separados por marketplace são claramente preferíveis. Eles permitem que o pipeline de cada marketplace seja executado independentemente sem contenção no arquivo de estado, facilitam a redefinição ou repetição da extração de um marketplace sem afetar os outros, e correspondem naturalmente a uma estrutura de diretório que organiza os arquivos extraídos por marketplace. Um diretório de estado com um arquivo YAML por marketplace — state/us.yaml, state/jp.yaml, state/de.yaml — é autoexplicativo de uma forma que um único arquivo combinado com seções aninhadas não é.

O esquema do arquivo de estado deve incluir explicitamente o identificador do marketplace, mesmo que seja implícito pelo nome do arquivo. Quando os arquivos de estado são inspecionados durante a depuração ou auditoria, a redundância elimina a ambiguidade sobre os dados de qual marketplace estão sendo revisados.

Definições de relatório baseadas em registro

Um registro de relatórios — uma definição estruturada de cada tipo de relatório suportado, com seu ID, disponibilidade no marketplace, esquema esperado e quaisquer variações de formato — é o investimento de maior impacto em um pipeline de múltiplos marketplaces. Sem ele, o conhecimento de quais relatórios existem, como diferem entre marketplaces e o que seus nomes de coluna significam fica apenas na memória dos desenvolvedores que construíram o pipeline.

O registro serve a vários propósitos simultaneamente. Ele fornece uma única fonte de referência para IDs de tipos de relatório, que a Amazon ocasionalmente altera ou descontinua. Ele documenta variações de esquema por marketplace, tornando simples lidar com as diferenças programaticamente em vez de por meio de condicionais espalhadas. Ele permite validar os dados: cada arquivo baixado pode ser verificado em relação ao seu esquema esperado, com discrepâncias sinalizadas para investigação em vez de gravadas silenciosamente no disco.

O registro também torna a análise de lacunas viável. Dada uma lista de tipos de relatório esperados e os arquivos de estado YAML para cada marketplace, um script simples pode identificar quais relatórios estão faltando, quais estão desatualizados e quais encontraram erros repetidos — em todos os marketplaces de uma vez. Sem o registro, essa análise requer entender o código de extração em vez de apenas consultar uma estrutura de dados.

Considerações operacionais em escala

Executar extração paralela em três marketplaces introduz questões de agendamento que pipelines para um único marketplace não enfrentam. O fluxo de trabalho de duas etapas — solicitar à noite, baixar de manhã — precisa levar em conta o fato de que “noite” e “manhã” significam coisas diferentes em UTC para os marketplaces dos EUA, do Japão e da Alemanha. Uma única execução agendada que funciona para a Alemanha solicitará relatórios em um horário inconveniente para o Japão e pode não coincidir com a virada do dia útil para os EUA.

A solução prática é o agendamento local por marketplace: o pipeline de cada marketplace é executado em um cronograma alinhado ao seu próprio dia útil, em vez de um único cronograma global. Isso adiciona complexidade operacional, mas elimina as condições de corrida causadas por fusos horários que criam lacunas de dados intermitentes.

O limite de requisições é a outra consideração operacional que se torna mais relevante com múltiplos marketplaces. A SP-API aplica limites de requisições por operação para cada par de vendedor e aplicativo, e uma conta de vendedor pode abranger vários marketplaces em uma região. Um pipeline que solicita relatórios agressivamente para três marketplaces em paralelo pode esgotar cotas compartilhadas de maneiras que um pipeline para um único marketplace não faz. O rastreamento explícito do limite de requisições — por vendedor, aplicativo e operação, não por marketplace — previne os erros de limitação de requisições que de outra forma são difíceis de diagnosticar.