Automatizar la extracción de datos de Amazon Seller Central: la CLI como base

Amazon Seller Central expone una parte importante de sus datos mediante la SP-API, y una parte menor, pero relevante para las operaciones, solo a través de su propia interfaz: informes que requieren interacción con el navegador para solicitarlos, un tiempo de espera mientras se generan y un paso aparte para descargarlos. Automatizar esto de forma fiable tiene más matices de lo que parece al principio; la mayoría de los enfoques que funcionan en una demostración fallan en producción a los pocos días.

El reto no es principalmente técnico. La automatización del navegador es una tecnología madura, los endpoints de informes están documentados y los formatos de datos se conocen bien. El reto es operativo: la interfaz de Amazon cambia sin aviso, los límites de solicitudes son estrictos, la disponibilidad de informes varía según el marketplace y el tipo de cuenta, y el estado de sesión del que depende la automatización se deteriora de formas difíciles de detectar hasta que un pipeline deja de producir datos en silencio.

API frente a navegador: ventajas y desventajas reales

La SP-API cubre la mayoría de los tipos de informes relevantes para los datos operativos: pedidos, inventario, liquidaciones, gestión logística de FBA y rendimiento del catálogo. Para estos casos, un enfoque exclusivamente basado en la API es claramente preferible: es más rápido, más fiable y no depende de cambios en la interfaz. La inversión en una autenticación correcta con la SP-API —credenciales LWA, renovación de tokens y regulación de solicitudes— se amortiza rápidamente.

Sin embargo, algunas categorías de informes no están disponibles en la SP-API. Los informes publicitarios que van más allá de lo que expone la Advertising API, algunos documentos de cumplimiento normativo y varios formatos de resumen financiero requieren interacción con el navegador. La automatización del navegador debería reservarse precisamente para estos casos, con plena conciencia del costo operativo.

La alternativa de exportar manualmente cuando haga falta no es tan poco razonable como parece para informes poco frecuentes. La pregunta correcta es si la carga de automatización —mantener sesiones del navegador, gestionar el inicio de sesión, los CAPTCHA y la autenticación multifactor— es realmente menor que la carga manual en el horizonte temporal que interesa. Para datos operativos diarios, la automatización gana claramente. Para informes mensuales de cumplimiento normativo, el cálculo es menos evidente.

Los nombres de archivo deterministas como base

La decisión de diseño más importante en un pipeline de extracción de datos no es el mecanismo de extracción, sino cómo se nombran y almacenan los archivos extraídos. Los pipelines con nombres basados en marcas de tiempo o secuencias crean problemas operativos que se acumulan: no se puede saber de un vistazo si un informe cubre el intervalo esperado, la eliminación de duplicados pierde fiabilidad y los procesos posteriores que dependen de archivos concretos deben actualizarse cada vez que cambia la convención de nombres.

Una convención determinista codifica las propiedades esenciales del informe directamente en el nombre: tipo de informe, identificador del marketplace, intervalo de fechas y hash del contenido para eliminar duplicados. Un informe de liquidaciones del marketplace de la UE para un periodo concreto debe generar el mismo nombre de archivo con independencia de cuándo se solicite o descargue. Esta propiedad —la idempotencia en el sistema de archivos— elimina toda una categoría de errores del pipeline y permite que el directorio de datos se describa por sí mismo.

La implementación requiere una representación canónica de las propiedades clave de cada informe antes de escribir el archivo. Para la mayoría de los tipos de informes es sencillo. La dificultad aparece cuando Amazon no incluye todos los metadatos relevantes en el archivo: en esos casos, la convención de nombres debe obtenerlos del contexto de la solicitud, lo que obliga a mantener ese contexto durante la descarga.

Seguimiento del estado con YAML

Una herramienta de línea de comandos que extrae datos sin supervisión necesita un estado persistente: qué informes se solicitaron, cuáles están pendientes, cuáles se descargaron correctamente y cuáles fallaron, con qué error. Mantener el estado en una base de datos es la opción evidente, pero añade una dependencia que complica el despliegue y genera una carga operativa desproporcionada para el problema.

Los archivos YAML por tipo de informe —o por marketplace, en configuraciones con varios marketplaces— ofrecen casi toda la funcionalidad necesaria con una infraestructura mínima. El archivo de estado registra cada solicitud con sus parámetros, la marca de tiempo, la hora prevista de disponibilidad, el estado de descarga y los errores encontrados. Esto basta para reanudar pipelines desde el último estado correcto, mantener trazas de auditoría de qué datos se recopilaron y cuándo, y detectar intervalos de fechas que faltan.

La limitación práctica del estado en YAML es el acceso concurrente: si el pipeline se ejecuta desde varios procesos o máquinas, el estado basado en archivos crea condiciones de carrera. En pipelines de una sola máquina con ejecución secuencial, esto no supone un problema. En configuraciones distribuidas, la opción adecuada es una base de datos ligera; la estructura YAML se adapta fácilmente a un esquema cuando la migración se vuelve necesaria.

El flujo de dos fases para informes nocturnos

Varios tipos de informes de Amazon se generan de forma asíncrona: se solicita el informe, Amazon lo pone en cola y queda disponible entre unos minutos y varias horas después. El patrón más fiable es un flujo de dos fases: una de solicitud, que envía todas las solicitudes pendientes, y otra de descarga, que recupera los informes disponibles desde la última comprobación.

La fase de solicitud se ejecuta a una hora definida, normalmente al final de la tarde, y solicita todos los tipos de informes del último periodo completo. El archivo YAML registra cada ID de solicitud y su marca de tiempo. La fase de descarga se ejecuta a la mañana siguiente, consulta el estado de todas las solicitudes pendientes, descarga los informes listos y los marca como completados. Los que aún no están disponibles permanecen pendientes y se vuelven a comprobar en la siguiente fase de descarga.

Esta separación tiene una propiedad operativa importante: desacopla la latencia de generación de informes de las objetivos de disponibilidad del pipeline. En vez de bloquearse hasta que estén disponibles —lo que introduce retrasos variables y complejidad en los tiempos de espera máximos—, el pipeline tiene como objetivo una ventana definida al día siguiente para los informes solicitados antes de una hora de corte; los informes que Amazon no haya terminado para entonces permanecen pendientes para la siguiente fase. La hora exacta dentro de esa ventana depende de la cola de Amazon, no del comportamiento del pipeline.

Hay que prever la caducidad de los informes —la API de informes los conserva durante un máximo de 90 días, por lo que se deben detectar las descargas retrasadas— y la eliminación de solicitudes duplicadas: pedir varias veces el mismo periodo genera archivos redundantes y consume cuota de la API. El archivo YAML resuelve ambos casos: registra los periodos con solicitudes activas e impide volver a solicitarlos hasta que la solicitud existente caduque o falle definitivamente.

Qué falla en producción

El fallo más habitual en producción no es la extracción, sino la gestión de credenciales. La SP-API utiliza tokens de acceso LWA (Login With Amazon) que caducan cada hora y deben renovarse mediante un token de renovación con una vida más larga, pero finita. Los pipelines que gestionan correctamente la renovación en desarrollo suelen fallar en producción cuando se ejecutan sin supervisión durante periodos prolongados y el token de renovación caduca sin sustituirse.

La extracción mediante navegador falla de otra forma: caducan las cookies de sesión, Amazon introduce nuevos pasos de verificación y la interfaz cambia de maneras que rompen los selectores CSS o los flujos de navegación. Estos fallos son silenciosos salvo que el pipeline valide explícitamente que el archivo descargado contiene la estructura de datos esperada, y no solo que se descargó un archivo.

La disciplina operativa que evita la mayoría de los fallos es validar cada paso. Verifique que las credenciales sean válidas antes de iniciar el pipeline. Compruebe que cada informe solicitado devuelve el esquema esperado y que los intervalos de fechas de los archivos descargados coinciden con los solicitados. Los pipelines con validaciones rigurosas fallan de inmediato y de forma visible. Los que confían en sus entradas fallan en silencio y con un costo elevado.