Pipelines de datos en varios marketplaces: cuentas de vendedor en distintas regiones

Ampliar un pipeline de datos de Amazon de un marketplace a tres no consiste en ejecutar el mismo código tres veces. Los marketplaces de Estados Unidos, Japón y Alemania difieren en aspectos más fundamentales que el desfase horario: los formatos varían entre marketplaces para un mismo tipo de informe; el manejo de divisas exige decidir explícitamente dónde se realiza la conversión y a qué tipo de cambio; las convenciones de fecha son inconsistentes tanto en las respuestas de la API como en los archivos descargados; y las estructuras de las cuentas —unificadas o regionales— determinan qué credenciales permiten acceder a cada conjunto de datos.

La mayoría de los equipos descubre estas diferencias de forma sucesiva: desarrolla para un marketplace y encuentra cada discrepancia al ampliar la solución al siguiente. Es más productivo diseñar desde el principio para varios marketplaces, aunque el despliegue inicial solo utilice uno. El costo marginal de una arquitectura basada en configuración es bajo. El costo de refactorizar una implementación con un único marketplace definido directamente en el código para admitir otras regiones es alto.

En qué difieren realmente los marketplaces

La disponibilidad de informes varía más de lo que sugiere la documentación de SP-API. Algunos tipos de informe están disponibles en todos los marketplaces; otros, solo en Norteamérica, en la UE o en determinados endpoints regionales. Los informes sobre cumplimiento del IVA, por ejemplo, son específicos de los marketplaces de la UE y no tienen equivalente en Norteamérica. A su vez, algunos informes de inventario de FBA tienen estructuras de columnas distintas en Amazon.co.jp y Amazon.com: el mismo identificador de tipo de informe devuelve esquemas diferentes según el endpoint del marketplace.

El manejo de fechas y horas es una fuente persistente de errores sutiles. La API de Amazon devuelve marcas de tiempo en UTC, pero los informes descargados suelen usar la zona horaria local del marketplace en las columnas de fecha sin indicarlo explícitamente. Cuando un informe usa la hora local, un archivo del marketplace japonés tendrá fechas en JST y el mismo informe para Alemania usará CET o CEST según la época del año; en cambio, otras columnas, como posted-date-time del informe de liquidación V2, están documentadas en UTC. El código que trata todas las columnas de fecha como UTC producirá desfases de un día en las agregaciones por fecha, difíciles de detectar porque los datos parecen correctos a primera vista.

La divisa es la diferencia con mayores consecuencias operativas. Amazon liquida en la divisa local del marketplace: USD en Estados Unidos, JPY en Japón y EUR en Alemania. Un pipeline que almacena importes sin identificar explícitamente su divisa genera un problema de calidad de datos que se agrava con el tiempo: cuando se detecta el error, puede ser necesario corregir meses de datos. El diseño adecuado almacena el código de divisa junto a cada importe y pospone la conversión hasta el análisis, en lugar de incorporarla de forma fija en la capa de extracción.

Arquitectura basada en configuración

La base de un pipeline mantenible para varios marketplaces es una capa de configuración que reúne todas las propiedades específicas de cada marketplace, en lugar de dispersar la lógica condicional por el código de extracción. Cada marketplace tiene un bloque de configuración que especifica su endpoint, referencias a credenciales, zona horaria local, código de divisa, tipos de informe admitidos y cualquier ajuste de formato para los informes que difieran del esquema de referencia.

El código de extracción pasa a ser independiente del marketplace: lee la configuración del marketplace objetivo, selecciona las credenciales apropiadas, aplica la zona horaria correcta a los campos de fecha y etiqueta todos los importes con el código de divisa configurado. Para añadir un marketplace basta con agregar un bloque de configuración y registrar las variaciones de formato; no es necesario modificar la lógica de extracción.

Este enfoque tiene una ventaja adicional: hace explícito el modelo de datos. Cuando el código de divisa, la zona horaria y las variaciones de formato de los informes se documentan en un archivo de configuración, en lugar de quedar en comentarios del código, son visibles para todas las personas que trabajan con el pipeline, no solo para quien resolvió originalmente cada caso particular.

Estado en YAML por marketplace

El seguimiento del estado en YAML descrito para pipelines de un solo marketplace se extiende de forma natural a varios marketplaces, pero la estructura de los archivos de estado requiere una elección deliberada: un archivo por marketplace o un único archivo con secciones para cada uno.

Es claramente preferible separar los archivos de estado por marketplace. Esto permite ejecutar cada pipeline de forma independiente sin competir por el archivo de estado, facilita reiniciar o repetir la extracción de un marketplace sin afectar a los demás y encaja con una estructura de directorios que organiza los archivos extraídos por marketplace. Un directorio de estado con un archivo YAML por marketplace —state/us.yaml, state/jp.yaml, state/de.yaml— explica su propia estructura de una manera que un archivo combinado con secciones anidadas no consigue.

El esquema del archivo de estado debe incluir explícitamente el identificador del marketplace, aunque ya se deduzca del nombre del archivo. Al inspeccionar archivos de estado durante una depuración o auditoría, esta redundancia elimina cualquier duda sobre el marketplace al que pertenecen los datos revisados.

Definiciones de informes basadas en un registro

Un registro de informes —una definición estructurada de cada tipo de informe admitido, con su identificador, disponibilidad por marketplace, esquema esperado y variaciones de formato— es la inversión que más valor aporta a un pipeline para varios marketplaces. Sin él, el conocimiento de qué informes existen, cómo varían entre marketplaces y qué significan sus columnas queda en la cabeza de quienes desarrollaron el pipeline.

El registro cumple varias funciones a la vez. Proporciona una fuente de referencia única para los identificadores de tipos de informe, que Amazon modifica o retira ocasionalmente. Documenta las variaciones de esquema por marketplace y facilita gestionarlas mediante código, en lugar de condiciones dispersas. También permite validar: cada archivo descargado puede comprobarse frente al esquema esperado y las discrepancias pueden señalarse para su investigación, en lugar de escribir el archivo en disco sin advertencia alguna.

El registro también facilita el análisis de carencias. A partir de una lista de tipos de informe esperados y los archivos de estado YAML de cada marketplace, un script sencillo puede identificar los informes que faltan, los que están desactualizados y los que han sufrido errores repetidos en todos los marketplaces a la vez. Sin el registro, este análisis exige entender el código de extracción en vez de consultar una estructura de datos.

Consideraciones operativas a escala

La extracción en paralelo en tres marketplaces introduce consideraciones de horario que no existen con uno solo. El flujo de trabajo de dos pasadas —solicitar por la tarde y descargar por la mañana— debe tener en cuenta que «tarde» y «mañana» corresponden a horas UTC distintas en los marketplaces de Estados Unidos, Japón y Alemania. Una ejecución programada que funciona para Alemania solicitará informes a una hora poco conveniente en Japón y puede no coincidir con el cierre del día hábil en Estados Unidos.

La solución práctica es programar las ejecuciones según la hora local de cada marketplace: cada pipeline sigue un horario alineado con su propio día hábil, en lugar de un horario global único. Esto añade complejidad operativa, pero elimina las condiciones de carrera causadas por las zonas horarias que generan lagunas intermitentes en los datos.

Los límites de solicitudes son otra consideración operativa que cobra importancia al trabajar con varios marketplaces. SP-API aplica límites de solicitudes por operación para cada combinación de vendedor y aplicación, y una cuenta de vendedor puede abarcar varios marketplaces de una región. Un pipeline que solicita informes de manera intensiva para tres marketplaces en paralelo puede agotar cuotas compartidas que no agotaría con uno solo. El seguimiento explícito de los límites por vendedor, aplicación y operación, no por marketplace, evita errores por exceso de solicitudes que, de otro modo, resultan difíciles de diagnosticar.