Automação da extração de dados do Amazon Seller Central: uma abordagem centrada na CLI

O Amazon Seller Central expõe uma parte significativa de seus dados através da SP-API, e uma parte menor, mas operacionalmente significativa, apenas através da própria interface do Seller Central — relatórios que precisam ser solicitados pelo navegador, levam algum tempo para ser gerados e exigem uma etapa separada de download. Automatizar isso de forma confiável é mais complexo do que parece inicialmente, e a maioria das abordagens que funcionam em demonstração falha em produção em dias.

O desafio não é principalmente técnico. A automação de navegador é madura, os endpoints de relatório são documentados e os formatos de dados são bem compreendidos. O desafio é operacional: a interface da Amazon muda sem aviso, os limites de requisições são agressivos, a disponibilidade de relatórios varia por marketplace e tipo de conta, e o estado da sessão do qual a automação de navegador depende degrada de maneiras difíceis de detectar até que um pipeline silenciosamente pare de produzir dados.

API ou navegador: uma avaliação franca das vantagens e limitações

A SP-API cobre a maioria dos tipos de relatório que importam para dados operacionais: pedidos, estoque, liquidações, processamento e envio de pedidos pelo FBA e desempenho de catálogo. Para esses, uma abordagem de API pura é claramente preferível — é mais rápida, mais confiável e não está sujeita a mudanças de interface. O investimento na autenticação adequada da SP-API (credenciais LWA, atualização de tokens, controle do ritmo de requisições) se paga rapidamente.

Mas na realidade, certas categorias de relatório não estão disponíveis através da SP-API. Relatórios de publicidade além do que a Advertising API expõe, alguns documentos de conformidade e vários formatos de resumo financeiro requerem interação com o navegador. A decisão de usar automação de navegador deve ser tomada com relutância, exatamente para esses casos, com plena consciência do custo operacional.

A alternativa — exportar manualmente quando necessário — não é tão irracional quanto parece para relatórios de baixa frequência. A pergunta certa é se o esforço adicional da automação (manter sessões de navegador, lidar com fluxos de login, gerenciar CAPTCHAs e MFA) é genuinamente menor do que o esforço manual ao longo do período relevante para você. Para dados operacionais diários, a automação vence claramente. Para relatórios de conformidade mensais, o cálculo é menos óbvio.

Nomenclatura determinística de arquivos como base

A decisão de projeto de maior impacto em um pipeline de extração de dados não é o mecanismo de extração — é como os arquivos extraídos são nomeados e armazenados. Pipelines que usam nomes de arquivo baseados em registro de data e hora ou sequenciais criam problemas operacionais que se acumulam ao longo do tempo: você não consegue identificar de imediato se um determinado relatório cobre o intervalo de datas que você espera, a deduplicação se torna não confiável e os processos posteriores que dependem de arquivos específicos devem ser atualizados sempre que a convenção de nomenclatura mudar.

Uma convenção de nomenclatura determinística codifica as propriedades relevantes de cada relatório diretamente no nome do arquivo: tipo de relatório, identificador de marketplace, intervalo de datas e um hash de conteúdo para deduplicação. Um relatório de liquidações para o marketplace da UE cobrindo um período específico deve produzir o mesmo nome de arquivo independentemente de quando foi solicitado ou baixado. Essa propriedade — idempotência no sistema de arquivos — elimina uma categoria inteira de bugs de pipeline e torna o diretório de dados autodocumentado.

A implementação requer uma representação canônica das propriedades principais de cada relatório antes que o arquivo seja escrito. Para a maioria dos tipos de relatório, isso é simples. A complicação surge com relatórios onde a Amazon não inclui todos os metadados relevantes no próprio arquivo — nesses casos, a convenção de nomenclatura deve derivar os metadados do contexto da solicitação, o que requer acompanhar esse contexto até a etapa de download.

Rastreamento de estado com YAML

Uma CLI de extração de dados que funciona sem supervisão precisa de estado persistente: quais relatórios foram solicitados, quais estão pendentes, quais foram baixados com sucesso e quais falharam com qual erro. O rastreamento de estado baseado em banco de dados é a abordagem óbvia, mas introduz uma dependência que complica a implantação e cria custo operacional adicional desproporcional ao problema.

Arquivos YAML por tipo de relatório — ou por marketplace, para configurações de múltiplos marketplaces — fornecem a maior parte da funcionalidade necessária com infraestrutura mínima. O arquivo de estado registra cada solicitação de relatório com seus parâmetros, o registro de data e hora da solicitação, o horário previsto de disponibilização, o status de download e qualquer erro encontrado. Isso é suficiente para suportar pipelines que podem ser retomados (reiniciar a partir do último estado bem-sucedido), trilhas de auditoria (quais dados foram coletados e quando) e detecção de lacunas (quais intervalos de datas estão faltando).

A limitação prática do estado YAML é o acesso concorrente: se o pipeline for executado a partir de múltiplos processos ou máquinas, o estado baseado em arquivo cria condições de corrida. Para pipelines de máquina única com execução sequencial, isso não é uma preocupação. Para configurações distribuídas, um banco de dados leve é a escolha certa, e a estrutura YAML pode ser convertida diretamente em um esquema quando a migração se torna necessária.

O fluxo de trabalho em duas etapas para relatórios gerados durante a noite

Vários tipos de relatório da Amazon são gerados de forma assíncrona: você solicita o relatório, a Amazon o enfileira e o relatório fica disponível em algum momento entre minutos e horas depois. O padrão mais confiável para esses relatórios é um fluxo de trabalho de duas etapas — uma etapa de solicitação que envia todas as solicitações de relatório pendentes, e uma etapa de download que recupera os relatórios que ficaram disponíveis desde a última verificação.

A etapa de solicitação é executada em um horário definido — normalmente tarde da noite — e envia solicitações para todos os tipos de relatório cobrindo o período completo mais recente. O arquivo de estado YAML registra cada ID de solicitação e o registro de data e hora de envio. A etapa de download é executada na manhã seguinte, consulta o status de todas as solicitações pendentes, baixa os relatórios que estiverem prontos e os marca como concluídos no arquivo de estado. Os relatórios que ainda não estão disponíveis permanecem em estado pendente e são buscados novamente na próxima etapa de download.

Essa separação tem uma propriedade operacional importante: ela desacopla a latência da geração de relatórios das metas de disponibilidade do pipeline. Em vez de bloquear na disponibilidade do relatório (o que introduz atrasos variáveis e complexidade no tratamento de tempos limite), o pipeline tem como meta uma janela definida no dia seguinte para os relatórios solicitados antes de um horário de corte; os relatórios que a Amazon ainda não tiver concluído permanecem pendentes para a próxima etapa. O momento exato de disponibilização dentro dessa janela depende da fila da Amazon, não do comportamento do pipeline.

Os modos de falha para os quais projetar são a expiração de relatórios (a API de relatórios retém relatórios por no máximo 90 dias, portanto atrasos no download devem ser detectados) e a deduplicação de solicitações (enviar solicitações duplicadas para o mesmo período gera arquivos redundantes e desperdiça cota de API). O arquivo de estado YAML lida com ambos: ele registra quais períodos têm solicitações ativas e impede a nova solicitação até que a solicitação existente expire ou falhe definitivamente.

O que quebra em produção

O padrão de falha mais comum em produção não é a extração do relatório em si — é o gerenciamento de credenciais. A SP-API usa tokens de acesso LWA (Login With Amazon) que expiram de hora em hora e devem ser atualizados usando um token de atualização que tem uma vida útil mais longa, mas finita. Pipelines que lidam corretamente com a atualização de tokens em desenvolvimento frequentemente falham em produção quando são executados sem supervisão por períodos prolongados e o token de atualização expira sem ser renovado.

A extração baseada em navegador tem um modo de falha diferente: os cookies de sessão expiram, a Amazon introduz novas etapas de verificação e a interface muda de maneiras que quebram seletores CSS ou fluxos de navegação. Essas falhas são silenciosas a menos que o pipeline valide explicitamente que o arquivo baixado contém a estrutura de dados esperada, não apenas que um arquivo foi baixado.

A disciplina operacional que previne a maioria das falhas de produção é a validação em cada etapa. Verifique se as credenciais de autenticação são válidas antes do início do pipeline. Verifique se cada relatório solicitado retorna o esquema esperado. Verifique se os intervalos de datas nos arquivos baixados correspondem aos intervalos de datas que foram solicitados. Pipelines que validam agressivamente falham de forma visível e imediata. Pipelines que confiam em suas entradas falham de forma silenciosa e cara.