Construindo um data warehouse de dados da Amazon com FastAPI e TimescaleDB

A SP-API da Amazon oferece acesso a um volume substancial de dados operacionais — pedidos, estoque, liquidações, desempenho de catálogo —, e a API separada Amazon Ads API fornece os dados de publicidade. Mas, na prática, os dados só são úteis quando estão em um formato que permite consultas. Os próprios relatórios da Amazon são temporários, sujeitos a limites de requisições 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 específica de processamento e envio de pedidos.

Este artigo descreve a arquitetura que utilizamos para um data warehouse de dados 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 os dados que obtemos das APIs da Amazon sejam armazenados 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 daquele momento, 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, estão sujeitas a limites de requisições, têm paginação limitada a determinadas janelas de tempo e são 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 integra facilmente aos dados de processamento e envio de pedidos. Os dados de liquidação chegam em um ciclo de duas semanas e exigem um processamento complexo para serem conciliados com os dados de pedidos.

Um data 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 é composta, por natureza, de séries temporais. Pedidos têm marcas de tempo. Snapshots de estoque representam o estado em um momento específico. 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 substancialmente 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 data 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 esquema 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 definição — você solicita um relatório, verifica o status periodicamente, faz o download do resultado quando está pronto e processa o arquivo. Isso se traduz naturalmente em uma cadeia de tarefas do Celery: uma tarefa para iniciar a solicitação de relatório, uma tarefa periódica para verificar o status, uma tarefa para baixar e armazenar o arquivo bruto e uma tarefa para analisar e carregar os dados estruturados no TimescaleDB. O Redis serve como intermediário de mensagens 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.

A tabela Pedidos (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 processamento e envio de pedidos, 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 móvel usadas na previsão de demanda.

A tabela Snapshots de estoque (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 móveis diárias e semanais a partir desses snapshots sem exigir que a consulta percorra todo o histórico de snapshots.

A tabela Liquidações (Settlements) armazena relatórios de liquidação analisados com cada lançamento em 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 lançamentos 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.

A tabela Catálogo (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 visão materializada que o TimescaleDB atualiza incrementalmente conforme novos dados chegam à hypertable. Para previsão de demanda, mantemos um agregado contínuo diário de vendas por ASIN e marketplace, a partir do qual são calculados os totais de vendas em janelas móveis de 7, 30 e 90 dias. Esse agregado é atualizado automaticamente em um cronograma definido, e as consultas sobre ele são executadas sobre dados pré-computados, em vez da hypertable completa, o que torna as análises no nível de painel 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 visão é atualizada automaticamente pela política de atualização em segundo plano do TimescaleDB, que configuramos para ser executada a cada hora. As somas em janelas móveis de 90 dias usadas em previsões são calculadas como consultas de função de janela sobre esta visão materializada, não sobre a tabela de dados brutos dos itens de pedido.

O pipeline Celery

O pipeline de relatórios SP-API é executado como um conjunto de tarefas 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 tarefa agendada inicia uma solicitação de relatório via SP-API, armazenando o ID da solicitação no Redis. Uma tarefa 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 tarefa de download. A tarefa de download busca o documento do relatório, armazena o arquivo bruto em disco e enfileira uma tarefa de processamento. A tarefa 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 data warehouse ao longo do tempo, desde que cada tipo de relatório seja processado sequencialmente; o processamento concorrente também exigiria uma restrição de unicidade no banco de dados.

O tratamento de erros segue uma política simples: erros transitórios da SP-API (respostas de limite de requisições, indisponibilidade temporária do serviço) acionam uma nova tentativa do Celery com espera progressiva exponencial (backoff). Erros persistentes — documentos de relatório malformados, mudanças inesperadas de esquema, 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: séries temporais de vendas com dados limpos na granularidade de ASIN-marketplace-dia, com histórico suficiente para identificar padrões sazonais e calcular estimativas de tendência estatisticamente significativas.

O agregado contínuo diário descrito acima alimenta os sinais de demanda em janelas móveis 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 suavização exponencial de Holt-Winters para produtos com ciclos sazonais claros e regressão simples com sinais externos (gastos com publicidade, mudanças de preço) para produtos em que essas variáveis são fatores relevantes para a demanda. 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 a extensão do histórico importam mais do que a complexidade do modelo.

O que se torna possível

As capacidades específicas que o data warehouse viabiliza merecem ser explicitadas, 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, ressarcimentos incorretos ou erros de liquidação que, de outra forma, seriam visíveis apenas para vendedores que conciliam manualmente os lançamentos individuais. Essa verificação é executada como um relatório semanal no data warehouse, sem necessidade de trabalho manual.

A análise de publicidade se torna possível no nível de ASIN. Ao unir dados de publicidade com dados de pedidos em identificadores compartilhados, podemos acompanhar como os gastos com publicidade e as vendas orgânicas variam em conjunto 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 as vendas orgânicas em torno delas. Os dados combinados mostram correlação; atribuir mudanças de posicionamento orgânico à publicidade exigiria também dados de posicionamento e uma comparação controlada.