Cómo crear un almacén de datos de Amazon con FastAPI y TimescaleDB

La SP-API de Amazon permite acceder a un volumen considerable de datos operativos: pedidos, inventario, liquidaciones y rendimiento del catálogo. Los datos publicitarios proceden de la API independiente Amazon Ads API. Sin embargo, los datos solo son útiles si están en un formato que permita consultarlos. Los informes de Amazon son temporales, están sujetos a límites de solicitudes y no están diseñados para las preguntas operativas más importantes de un vendedor que gestiona un negocio en varios marketplaces. Es posible ver lo que ocurrió. No es fácil consultar qué está sucediendo en todos los marketplaces a la vez, o cuál fue la tendencia de demanda de los últimos noventa días para un ASIN concreto en una región específica de gestión logística de pedidos.

Este artículo describe la arquitectura que utilizamos para un almacén de datos de Amazon: FastAPI como capa de API, TimescaleDB como almacenamiento de series temporales y Celery para el pipeline asíncrono de informes de la SP-API. El objetivo es un sistema que almacene los datos que obtenemos de las API de Amazon en un formato consultable bajo su control, con suficiente estructura para permitir la previsión de demanda y la analítica operativa sin necesitar un equipo de ingeniería de datos que lo mantenga.

Por qué las herramientas de Amazon no son suficientes

Los informes de Seller Central cubren la mayoría de las necesidades operativas de un único marketplace con un catálogo pequeño. Las carencias se hacen evidentes al crecer. Los informes se generan bajo demanda y caducan. No existe una capa de consulta persistente: se ejecuta un informe, se descarga un archivo y ese archivo contiene los datos. Ejecutar el mismo informe dentro de seis meses proporciona los datos de ese momento, no los de hoy.

Esto significa que cualquier análisis histórico exige que alguien haya descargado y almacenado cada informe pertinente con la frecuencia adecuada, o que se reconstruya el historial a partir de exportaciones a nivel de transacción. Estas también están sujetas a límites de solicitudes, se paginan en ventanas acotadas y están estructuradas para recuperar registros individuales, no para el análisis masivo.

El panel Business Reports de Amazon ofrece datos de tendencias agregados, pero la granularidad y el período de conservación responden a decisiones de producto de Amazon, no a sus necesidades de análisis. La consola de publicidad tiene un modelo de datos propio que no se combina fácilmente con los datos de gestión logística de pedidos. Los datos de liquidación llegan en ciclos de dos semanas y requieren un análisis de formato complejo para conciliarlos con los datos de pedidos.

Un almacén de datos a medida resuelve al mismo tiempo los problemas de persistencia y consulta. Usted controla el almacenamiento, define la conservación y escribe las consultas que responden a las preguntas que su negocio realmente necesita resolver, no a las que los paneles de Amazon fueron diseñados para abordar.

Elección de tecnologías

Elegimos TimescaleDB como almacenamiento principal porque la mayoría de los datos operativos de Amazon son, por naturaleza, series temporales. Los pedidos tienen marcas de tiempo. Las instantáneas de inventario reflejan un momento concreto. Los períodos de liquidación tienen fechas de inicio y fin. El gasto publicitario y las impresiones se acumulan con el tiempo. TimescaleDB es PostgreSQL con extensiones de hipertablas que hacen que las consultas por intervalos de tiempo sobre grandes conjuntos de datos sean considerablemente más eficientes que en PostgreSQL estándar, manteniendo la compatibilidad total con SQL. No hay un nuevo lenguaje de consulta que aprender ni un modelo operativo que difiera sustancialmente de una instalación estándar de Postgres.

FastAPI proporciona la capa de API entre los workers de Celery que extraen datos de la SP-API y los consumidores internos que consultan el almacén. Gestiona la autenticación, la validación de solicitudes y la serialización de respuestas con muy poco código repetitivo. Para un servicio interno que no está expuesto a internet, la documentación OpenAPI automática de FastAPI resulta especialmente útil: ofrece una definición de interfaz consultable que facilita crear nuevos consumidores sin tener que deducir el modelo de datos a partir del esquema de la base de datos.

Celery gestiona el pipeline asíncrono de informes de la SP-API. La generación de informes de la SP-API es asíncrona por diseño: se solicita un informe, se consulta periódicamente su estado, se descarga el resultado cuando está listo y se procesa el archivo. Esto se adapta de forma natural a una cadena de tareas de Celery: una tarea para iniciar la solicitud del informe, una tarea periódica para consultar su estado, una tarea para descargar y almacenar el archivo sin procesar y otra para analizar y cargar los datos estructurados en TimescaleDB. Redis actúa como intermediario de mensajes y backend de resultados de Celery.

Modelo de datos

Las tablas principales reflejan los dominios de datos fundamentales de la SP-API. El principio de diseño es que cada tabla debe responder a una clase específica de preguntas operativas sin necesitar combinaciones entre varios tipos de informes.

La tabla Pedidos es una hipertabla particionada por purchase_date. Cada fila representa un artículo de un pedido, no un pedido completo, porque el análisis a nivel de artículo —por ASIN, canal de gestión logística de pedidos o marketplace— es el nivel de detalle más habitual. Los agregados a nivel de pedido se derivan de los registros de artículos. El intervalo de partición de la hipertabla se establece en una semana, lo que ofrece un buen rendimiento para las consultas con ventanas móviles utilizadas en la previsión de demanda.

La tabla Instantáneas de inventario almacena los resultados de los informes de inventario en el momento de su extracción. El inventario FBA no es un flujo de eventos: es un estado que cambia continuamente y no puede reconstruirse por completo solo a partir de los registros de pedidos, ya que las devoluciones, los ajustes y las transferencias afectan al inventario sin pedidos correspondientes. Extraemos instantáneas de inventario dos veces al día y las almacenamos como registros de momentos concretos. La función de agregados continuos de TimescaleDB calcula promedios móviles diarios y semanales a partir de estas instantáneas sin que la consulta tenga que recorrer todo el historial.

La tabla Liquidaciones almacena los informes de liquidación procesados, con cada partida en una fila. El modelo de datos de liquidación plantea uno de los análisis de formato más complejos del ecosistema de la SP-API: Amazon utiliza distintos códigos de tipo de transacción según el marketplace, y las partidas de comisiones emplean convenciones de nombres que no son totalmente consistentes entre regiones. Mantenemos una tabla de correspondencias que normaliza los nombres de los tipos de comisiones entre mercados según una clasificación interna uniforme.

La tabla Catálogo almacena una instantánea del catálogo de productos —ASIN, títulos, categorías y relaciones entre variantes— que se actualiza semanalmente. Esta tabla sirve principalmente como referencia de consulta para las demás y no utiliza una estructura de hipertabla, ya que los datos no presentan características relevantes de series temporales.

TimescaleDB en la práctica

Las hipertablas son la función central de TimescaleDB. Crear una hipertabla a partir de una tabla estándar de PostgreSQL requiere un solo comando que especifique la columna temporal y el intervalo de partición. Después, las consultas SQL estándar funcionan sin modificaciones y el planificador de consultas de TimescaleDB aplica automáticamente la exclusión de particiones que quedan fuera del intervalo temporal consultado. Así, las consultas acotadas en el tiempo son rápidas incluso con grandes conjuntos de datos.

Los agregados continuos son la segunda función que utilizamos ampliamente. Un agregado continuo es una vista materializada que TimescaleDB actualiza de forma incremental a medida que llegan nuevos datos a la hipertabla. Para la previsión de demanda, mantenemos un agregado continuo diario de ventas por ASIN y marketplace, a partir del cual se calculan los totales de ventas en ventanas móviles de 7, 30 y 90 días. Este agregado se actualiza automáticamente según una programación definida, y las consultas se ejecutan sobre datos precalculados en lugar de sobre toda la hipertabla, lo que hace que la analítica de los paneles sea suficientemente rápida para un uso interactivo.

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;

TimescaleDB actualiza esta vista automáticamente mediante una política en segundo plano que configuramos para ejecutarse cada hora. Las sumas móviles de 90 días utilizadas en la previsión se calculan mediante consultas con funciones de ventana sobre esta vista materializada, no sobre la tabla de artículos de pedidos sin procesar.

El pipeline de Celery

El pipeline de informes de la SP-API se ejecuta como un conjunto de tareas de Celery con una programación gestionada por Celery Beat. Cada tipo de informe tiene su propia frecuencia: los pedidos se extraen cada hora, el inventario dos veces al día y las liquidaciones en un ciclo de dos semanas que coincide con los períodos de liquidación de Amazon.

El pipeline de cada tipo de informe sigue la misma estructura: una tarea programada inicia una solicitud de informe mediante la SP-API y guarda su identificador en Redis. Una tarea de consulta periódica se ejecuta cada pocos minutos, comprueba el estado del informe mediante la SP-API y, cuando está listo, añade una tarea de descarga a la cola. La tarea de descarga obtiene el documento del informe, guarda el archivo sin procesar en disco y añade una tarea de procesamiento a la cola. Esta última analiza el archivo y carga los registros estructurados en TimescaleDB.

La eliminación de duplicados se gestiona en la etapa de procesamiento, no en la base de datos. La SP-API devuelve ocasionalmente registros duplicados entre ventanas de informes que se solapan. Mantenemos un hash de los campos identificativos de cada registro y comprobamos si ya existe antes de insertarlo, lo que evita que se acumulen filas duplicadas en el almacén de datos con el tiempo, siempre que cada tipo de informe se procese de forma secuencial; el procesamiento concurrente también requeriría una restricción de unicidad en la base de datos.

La gestión de errores sigue una política sencilla: los errores transitorios de la SP-API —respuestas por límite de solicitudes o indisponibilidad temporal del servicio— activan un reintento de Celery con espera exponencial entre reintentos. Los errores persistentes —documentos de informe mal formados, cambios inesperados del esquema o fallos de análisis— se registran con todo el contexto y detienen el procesamiento de ese tipo de informe sin afectar a otros pipelines. Revisamos el registro de errores como parte de la revisión operativa semanal, en lugar de tratar estos fallos como incidentes urgentes, salvo que afecten a los datos de conciliación de liquidaciones.

Base para la previsión de demanda

El almacén de datos no implementa directamente la previsión de demanda. Proporciona la base de información necesaria para hacerla posible: series temporales de ventas limpias con un nivel de detalle por ASIN, marketplace y día, y suficiente historial para identificar patrones estacionales y calcular estimaciones de tendencias estadísticamente significativas.

El agregado continuo diario descrito anteriormente sirve de base para las señales de demanda en ventanas móviles de 7, 30 y 90 días. Estas señales alimentan modelos de previsión sencillos: medias móviles ponderadas y extrapolación lineal de tendencias para productos estables, con factores de ajuste manual para productos con estacionalidad conocida. Los modelos se ejecutan como endpoints de FastAPI que consultan los agregados continuos y devuelven previsiones puntuales con intervalos de confianza.

Una vez establecida esta base de información, resulta viable utilizar métodos de previsión más sofisticados. Hemos experimentado con el suavizado exponencial de Holt-Winters para productos con ciclos estacionales claros y con regresiones sencillas basadas en señales externas —gasto publicitario o cambios de precios— para productos en los que esas variables impulsan significativamente la demanda. Sin embargo, para la mayoría de los productos, la mejora en la precisión de estos métodos más complejos frente a medias móviles ponderadas bien ajustadas es modesta: la calidad de los datos y la longitud del historial importan más que la complejidad del modelo.

Qué pasa a ser posible

Conviene enumerar las capacidades concretas que permite el almacén de datos, porque representan un cambio cualitativo en las posibilidades operativas, no solo una mejora incremental en la velocidad de generación de informes.

La planificación del inventario entre marketplaces se vuelve viable. Con datos de ritmo de ventas por ASIN y marketplace y el inventario FBA actual de la tabla de instantáneas, podemos calcular los días de cobertura para cada SKU en cada marketplace y generar recomendaciones de reposición automáticamente, en lugar de revisar manualmente cada marketplace.

La conciliación de liquidaciones se vuelve auditable. Al almacenar los datos de pedidos y liquidaciones en el mismo sistema, es posible verificar que cada artículo de pedido se liquidó según la tarifa esperada e identificar discrepancias en las comisiones, reembolsos incorrectos o errores de liquidación que, de otro modo, solo detectan los vendedores que concilian las partidas manualmente. Esta comprobación se ejecuta como un informe semanal sobre el almacén de datos, sin requerir trabajo manual.

El análisis publicitario pasa a ser posible a nivel de ASIN. Al combinar los datos publicitarios con los de pedidos mediante identificadores compartidos, podemos seguir cómo evolucionan conjuntamente el gasto publicitario y las ventas orgánicas a lo largo del tiempo. La consola de publicidad de Amazon no responde directamente a esa pregunta, porque muestra las ventas atribuidas a publicidad, pero no las ventas orgánicas en torno a ellas. Los datos combinados muestran correlación; atribuir los cambios de posicionamiento orgánico a la publicidad requeriría además datos de posicionamiento y una comparación controlada.