Construindo um Data Warehouse da Amazon com FastAPI e TimescaleDB

A SP-API da Amazon oferece acesso a um volume substancial de dados operacionais — pedidos, estoque, liquidações, publicidade, desempenho de catálogo. Mas na prática, os dados só são úteis na forma em que você consegue consultá-los. Os próprios relatórios da Amazon são transitórios, com limitação de taxa e não foram projetados para responder às perguntas operacionais que mais importam a um vendedor que gerencia um negócio em múltiplos marketplaces. Você consegue ver o que aconteceu. Não é fácil perguntar o que está acontecendo em todos os marketplaces ao mesmo tempo, nem qual foi a tendência de demanda nos últimos noventa dias para um ASIN específico em uma região de fulfillment específica.

Este artigo descreve a arquitetura que utilizamos para um data warehouse da Amazon: FastAPI como camada de API, TimescaleDB como armazenamento de séries temporais e Celery para o pipeline assíncrono de relatórios SP-API. O objetivo é um sistema em que cada dado disponível pela API da Amazon seja armazenado em uma forma consultável que você controla, com estrutura suficiente para suportar previsão de demanda e análises operacionais sem exigir uma equipe de engenharia de dados para mantê-lo.

Por que as Ferramentas Próprias da Amazon São Insuficientes

Os relatórios do Seller Central cobrem a maioria das necessidades operacionais de um único marketplace com um catálogo pequeno. As lacunas se tornam evidentes em escala. Os relatórios são gerados sob demanda e expiram. Não existe uma camada de consulta persistente — você executa um relatório, baixa um arquivo e o arquivo é o dado. Executar o mesmo relatório daqui a seis meses fornece os dados de seis meses no futuro, não de hoje.

Isso significa que qualquer análise histórica exige que alguém tenha baixado e armazenado cada relatório relevante no intervalo correto, ou que você reconstrua o histórico a partir de exportações no nível de transação — que, por sua vez, têm limitação de taxa, são paginadas em janelas limitadas e estruturadas para recuperação de registros individuais, em vez de análise em lote.

O painel de Business Reports da Amazon fornece dados de tendência agregados, mas a granularidade e a janela de retenção são definidas pelas decisões de produto da Amazon, não pelas suas necessidades analíticas. O console de publicidade tem seu próprio modelo de dados que não se une de forma limpa aos dados de fulfillment. Os dados de liquidação chegam em um ciclo de duas semanas e exigem uma análise não trivial para ser conciliados com os dados de pedidos.

Um warehouse personalizado resolve simultaneamente os problemas de persistência e de capacidade de consulta. Você controla o armazenamento, define a retenção e escreve as consultas que respondem às perguntas que seu negócio realmente precisa responder — não as perguntas para as quais os painéis da Amazon foram projetados.

Escolhas Tecnológicas

Escolhemos o TimescaleDB como armazenamento principal porque a maioria dos dados operacionais da Amazon é inerentemente de série temporal. Pedidos têm timestamps. Snapshots de estoque são registros pontuais. Períodos de liquidação têm datas de início e fim. Gastos com publicidade e impressões se acumulam ao longo do tempo. O TimescaleDB é o PostgreSQL com extensões de hypertable que tornam as consultas por intervalo de tempo em grandes conjuntos de dados substancialmente mais eficientes do que o PostgreSQL padrão, mantendo total compatibilidade com SQL. Não há nova linguagem de consulta a aprender e nenhum modelo operacional materialmente diferente de uma instalação padrão do Postgres.

O FastAPI fornece a camada de API entre os workers do Celery que extraem dados da SP-API e os consumidores internos que consultam o warehouse. Ele trata de autenticação, validação de requisições e serialização de respostas com código mínimo. Para um serviço interno que não é exposto à internet pública, a documentação automática OpenAPI do FastAPI é particularmente útil: ela fornece uma definição de interface consultável que facilita a criação de novos consumidores sem necessidade de fazer engenharia reversa do modelo de dados a partir do schema do banco de dados.

O Celery gerencia o pipeline assíncrono de relatórios SP-API. A geração de relatórios SP-API é assíncrona por design — você solicita um relatório, verifica o status periodicamente, faz o download do resultado quando está pronto e processa o arquivo. Isso se mapeia naturalmente para uma cadeia de tasks do Celery: uma task para iniciar a solicitação de relatório, uma task periódica para verificar o status, uma task para baixar e armazenar o arquivo bruto e uma task para analisar e carregar os dados estruturados no TimescaleDB. O Redis serve como broker e backend de resultados do Celery.

Modelo de Dados

As tabelas principais refletem os domínios de dados primários da SP-API. O princípio de design é que cada tabela deve responder a uma classe específica de pergunta operacional sem exigir joins entre múltiplos tipos de relatório.

Orders é uma hypertable particionada em purchase_date. Cada linha representa um item de pedido individual, e não um pedido completo, porque a análise no nível de item — por ASIN, por canal de fulfillment, por marketplace — é a granularidade analítica mais comum. Agregados no nível de pedido são derivados de registros no nível de item. O intervalo de partição da hypertable é definido como uma semana, o que oferece bom desempenho de consulta para as consultas de janela rolante usadas na previsão de demanda.

Inventory snapshots armazena a saída dos relatórios de estoque no momento em que são extraídos. O estoque FBA não é um fluxo de eventos — é um estado que muda continuamente e não pode ser totalmente reconstruído a partir de registros de pedidos (devoluções, ajustes e transferências afetam o estoque sem pedidos correspondentes). Extraímos snapshots de estoque duas vezes ao dia e os armazenamos como registros pontuais. A funcionalidade de agregados contínuos do TimescaleDB calcula médias diárias e semanais rolantes a partir desses snapshots sem exigir que a consulta percorra todo o histórico de snapshots.

Settlements armazena relatórios de liquidação analisados com cada item de linha como uma linha. O modelo de dados de liquidação é um dos desafios de análise mais complexos no ecossistema SP-API — a Amazon usa códigos de tipo de transação diferentes entre marketplaces, e os itens de linha de tarifas usam convenções de nomenclatura que não são totalmente consistentes entre regiões. Mantemos uma tabela de mapeamento que normaliza os nomes dos tipos de tarifas entre mercados para uma taxonomia interna consistente.

Catalog armazena um snapshot do catálogo de produtos — ASINs, títulos, categorias, relacionamentos de variação — atualizado semanalmente. Esta tabela é principalmente uma referência de consulta para as outras tabelas e não usa estrutura de hypertable, pois os dados não têm características de série temporal significativas.

TimescaleDB na Prática

As hypertables são o recurso central do TimescaleDB. Criar uma hypertable a partir de uma tabela padrão do PostgreSQL requer um único comando que especifica a coluna de tempo e o intervalo de partição. Após isso, as consultas SQL padrão funcionam sem modificação, e o planejador de consultas do TimescaleDB aplica automaticamente a exclusão de chunks — ignorando partições fora do intervalo de tempo da consulta — para tornar as consultas delimitadas por tempo rápidas mesmo em grandes conjuntos de dados.

Os agregados contínuos são o segundo recurso que usamos extensivamente. Um agregado contínuo é uma view materializada que o TimescaleDB atualiza incrementalmente conforme novos dados chegam à hypertable. Para previsão de demanda, mantemos agregados contínuos para totais de vendas rolantes de 7, 30 e 90 dias por ASIN e marketplace. Esses agregados são atualizados automaticamente em um cronograma definido, e as consultas sobre eles são executadas contra dados pré-computados, em vez da hypertable completa, o que torna as análises no nível de dashboard rápidas o suficiente para uso interativo.

CREATE MATERIALIZED VIEW daily_sales_by_asin
WITH (timescaledb.continuous) AS
SELECT
  time_bucket('1 day', purchase_date) AS day,
  asin,
  marketplace_id,
  SUM(quantity_ordered) AS units_sold,
  SUM(item_price_amount) AS revenue
FROM order_items
GROUP BY day, asin, marketplace_id;

Essa view é atualizada automaticamente pela política de background do TimescaleDB, que configuramos para ser executada a cada hora. As somas rolantes de 90 dias usadas em previsões são calculadas como consultas de função de janela sobre esta view materializada, não sobre a tabela bruta de itens de pedido.

O Pipeline Celery

O pipeline de relatórios SP-API é executado como um conjunto de tasks Celery em um cronograma gerenciado pelo Celery Beat. Cada tipo de relatório tem seu próprio cronograma: pedidos são extraídos a cada hora, estoque duas vezes ao dia, liquidações em um ciclo de duas semanas que espelha os períodos de liquidação da Amazon.

O pipeline para cada tipo de relatório segue a mesma estrutura: uma task agendada inicia uma solicitação de relatório via SP-API, armazenando o ID da solicitação no Redis. Uma task de verificação é executada a cada poucos minutos, verifica o status do relatório via SP-API e, quando o relatório está pronto, enfileira uma task de download. A task de download busca o documento do relatório, armazena o arquivo bruto em disco e enfileira uma task de processamento. A task de processamento analisa o arquivo e carrega os registros estruturados no TimescaleDB.

A deduplicação é tratada na etapa de processamento, e não no nível do banco de dados. A SP-API ocasionalmente retorna registros duplicados em janelas de relatórios sobrepostas. Mantemos um hash dos campos identificadores de cada registro e verificamos a existência de registros antes da inserção, o que impede o acúmulo de linhas duplicadas no warehouse ao longo do tempo.

O tratamento de erros segue uma política simples: erros transitórios da SP-API (respostas de limite de taxa, indisponibilidade temporária do serviço) acionam uma nova tentativa do Celery com backoff exponencial. Erros persistentes — documentos de relatório malformados, mudanças inesperadas de schema, falhas de análise — são registrados com o contexto completo e interrompem o processamento para aquele tipo de relatório sem afetar outros pipelines. Revisamos o log de erros como parte da revisão operacional semanal, em vez de tratar esses casos como incidentes urgentes, a menos que afetem dados de conciliação de liquidação.

Base para Previsão de Demanda

O data warehouse não implementa previsão de demanda diretamente. Ele fornece a base de dados que torna a previsão possível: dados de vendas em série temporal limpos na granularidade de ASIN-marketplace-dia, com histórico suficiente para identificar padrões sazonais e calcular estimativas de tendência estatisticamente significativas.

Os agregados contínuos descritos acima produzem os sinais de demanda rolantes de 7, 30 e 90 dias. Esses sinais alimentam modelos de previsão simples — médias móveis ponderadas e extrapolação de tendência linear para produtos estáveis, com fatores de ajuste manual para produtos com sazonalidade conhecida. Os modelos são executados como endpoints FastAPI que consultam os agregados contínuos e retornam previsões pontuais com intervalos de confiança.

Abordagens de previsão mais sofisticadas se tornam viáveis uma vez que a base de dados está estabelecida. Experimentamos o suavizamento exponencial de Holt-Winters para produtos com ciclos sazonais claros e regressão simples contra sinais externos (gastos com publicidade, mudanças de preço) para produtos em que essas variáveis são drivers de demanda significativos. Na prática, porém, a melhoria na precisão da previsão dessas abordagens mais complexas em relação às médias móveis ponderadas bem ajustadas é modesta para a maioria dos produtos — a qualidade dos dados e o comprimento do histórico importam mais do que a complexidade do modelo.

O que se Torna Possível

As capacidades específicas que o warehouse viabiliza merecem ser nomeadas, pois representam uma mudança qualitativa no que pode ser feito operacionalmente, em vez de apenas uma melhoria incremental na velocidade de geração de relatórios.

O planejamento de estoque entre marketplaces se torna viável. Com dados de velocidade de vendas no nível de ASIN-marketplace e o estoque FBA atual da tabela de snapshots, podemos calcular os dias de estoque disponível para cada SKU em cada marketplace e gerar recomendações de reabastecimento automaticamente, em vez de por meio de revisão manual por marketplace.

A conciliação de liquidações se torna auditável. Com dados de pedidos e dados de liquidação armazenados no mesmo sistema, torna-se possível verificar se cada item de pedido foi liquidado à taxa esperada — identificando discrepâncias de tarifas, reembolsos incorretos ou erros de liquidação que, de outra forma, seriam visíveis apenas para vendedores que conciliam manualmente os itens de linha. Essa verificação é executada como um relatório semanal no warehouse, sem necessidade de trabalho manual.

A atribuição de publicidade se torna possível no nível de ASIN. Ao unir dados de publicidade com dados de pedidos em identificadores compartilhados, podemos calcular a contribuição dos gastos com publicidade para as melhorias de posicionamento orgânico ao longo do tempo — uma pergunta que o console de publicidade da Amazon não responde diretamente, pois mostra as vendas atribuídas à publicidade, mas não o efeito das mudanças de posicionamento orgânico que a publicidade impulsionou nas vendas orgânicas subsequentes.

---

Insights Relacionados

• Automação de Flatfile: Gerenciando Anúncios de Produtos em Múltiplos Marketplaces da Amazon — a camada de gerenciamento de catálogos que opera ao lado do data warehouse
• Engenharia de Distribuição: Construindo Sistemas que Vendem por Você — o framework estratégico que o data warehouse suporta
• Mais de Cem Containers Docker: Nossa Rotina Mensal de Verificação de Saúde — a disciplina de manutenção de infraestrutura que mantém essa stack saudável