Cómo funciona la API de Amazon para reportes: estructura, límites y casos de uso

Extraer datos de Seller Central manualmente es viable cuando gestionas una cuenta con 50 SKUs. Cuando tienes 500 o 5,000, se convierte en un cuello de botella operativo. La API de reportes de Amazon Selling Partner (SP-API) existe precisamente para resolver ese problema: acceso programático a datos de inventario, ventas, pedidos, finanzas y publicidad sin depender de descargas manuales ni de la interfaz web.

Arquitectura básica de la SP-API para reportes

La SP-API utiliza un modelo asíncrono para la generación de reportes. No solicitas un reporte y lo recibes de inmediato. El flujo estándar implica tres pasos: crear la solicitud del reporte (createReport), consultar el estado hasta que esté listo (getReport), y finalmente descargar el documento generado (getReportDocument). Este diseño responde a que algunos reportes pueden tardar minutos u horas en procesarse, dependiendo del volumen de datos.

Cada tipo de reporte tiene un identificador específico (reportType). Por ejemplo, GET_FLAT_FILE_OPEN_LISTINGS_DATA devuelve tu catálogo activo, GET_MERCHANT_LISTINGS_ALL_DATA incluye SKUs inactivos, y GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL proporciona información de envíos FBA. La documentación oficial lista más de 80 tipos de reportes disponibles, cada uno con su propia estructura de campos y frecuencia de actualización permitida.

El documento final se entrega comprimido y cifrado. Amazon proporciona una clave de descifrado junto con la URL de descarga. Tu sistema debe implementar el proceso de descompresión y descifrado antes de poder parsear los datos, que típicamente vienen en formato TSV o XML dependiendo del tipo de reporte.

Autenticación y permisos requeridos

La SP-API utiliza OAuth 2.0 con tokens de actualización de larga duración. Necesitas registrar tu aplicación en el Developer Central de Amazon, obtener credenciales LWA (Login with Amazon), y vincular la aplicación a cada cuenta de seller que desees consultar. El proceso de autorización genera un refresh token que permite obtener access tokens válidos por una hora.

Los permisos se definen a nivel de rol. Para reportes, el rol necesario depende del tipo de datos:

• Reportes de inventario y catálogo: rol de Inventory and Order Management
• Reportes financieros: rol de Finance and Accounting
• Reportes de ventas y tráfico: rol de Brand Analytics (requiere Brand Registry)
• Reportes de publicidad: se gestionan por separado en la Amazon Ads API

Un error común es asumir que con un rol genérico puedes acceder a todos los reportes. Amazon deniega la solicitud si el rol asociado no tiene permisos explícitos para ese reportType específico.

Límites de throttling y estrategias de manejo

Amazon aplica rate limits estrictos en la SP-API. El endpoint createReport permite típicamente 15 solicitudes por minuto, mientras que getReport tiene un límite más generoso. Cuando excedes el límite, recibes un error 429 (Too Many Requests) con un header Retry-After que indica cuántos segundos esperar. Ignorar este mecanismo y reintentar agresivamente puede resultar en bloqueos temporales más largos.

La estrategia recomendada combina tres elementos: implementar backoff exponencial con jitter para reintentos, mantener un rate limiter local que respete los límites documentados, y agrupar solicitudes cuando sea posible. Si necesitas el mismo reporte para múltiples marketplaces, puedes usar el parámetro marketplaceIds para incluir varios en una sola solicitud en lugar de hacer llamadas separadas.

Para operaciones de alto volumen, considera almacenar reportes en caché con una política de invalidación razonable. Un reporte de inventario de hace 15 minutos sigue siendo útil para la mayoría de dashboards operativos. Solicitar el mismo reporte cada minuto cuando los datos subyacentes se actualizan cada 4 horas es desperdiciar quota.

Reportes más utilizados en operaciones de ecommerce

Inventario y catálogo

GET_MERCHANT_LISTINGS_ALL_DATA es el punto de partida para cualquier auditoría de catálogo. Incluye precio, cantidad, condición, ASIN, SKU y status de cada listing. Para operaciones FBA, GET_FBA_MYI_ALL_INVENTORY_DATA proporciona niveles de stock en centros de fulfillment, incluyendo unidades reservadas, en tránsito y disponibles para venta.

Ventas y pedidos

GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE entrega el detalle de cada pedido en un rango de fechas. Para análisis agregados, GET_SALES_AND_TRAFFIC_REPORT ofrece métricas por ASIN incluyendo sesiones, page views, Buy Box percentage y conversion rate. Este último requiere Brand Registry y tiene un lag de 48-72 horas en los datos.

Finanzas

GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2 es esencial para conciliación contable. Detalla cada transacción del periodo de liquidación: ventas, reembolsos, comisiones, tarifas FBA, ajustes y transferencias. La mayoría de sellers descubren discrepancias entre sus cálculos y los pagos reales porque no procesan correctamente las múltiples líneas de ajuste que Amazon incluye.

Diferencias entre SP-API Reports y Amazon Ads API

Un punto de confusión frecuente: los reportes de campañas publicitarias no se obtienen mediante la SP-API. Amazon Ads tiene su propia API con autenticación separada, endpoints diferentes y una lógica de solicitud de reportes distinta. Si tu objetivo es consolidar datos de performance orgánico y pagado, necesitas integrar ambas APIs y unificar los datos en tu capa de almacenamiento.

La Ads API también maneja reportes de forma asíncrona, pero usa un sistema de reportId diferente y tiempos de procesamiento propios. Los reportes de Sponsored Products, Sponsored Brands y Sponsored Display tienen cada uno sus métricas específicas y niveles de granularidad (campaña, ad group, keyword, ASIN, placement). Planifica tu arquitectura de datos considerando que tendrás al menos dos fuentes primarias que deben sincronizarse.

Consideraciones para implementación en producción

Monitorear el estado de salud de tu integración es tan importante como construirla. Amazon depreca reportTypes sin mucho aviso, cambia estructuras de campos y modifica límites de throttling. Implementa alertas para errores 4xx y 5xx, y revisa periódicamente los changelogs de la SP-API. Un reporte que funcionó durante 18 meses puede dejar de existir en cualquier actualización trimestral.

El manejo de múltiples marketplaces añade complejidad. Cada marketplace (US, MX, CA, UK, DE, etc.) puede tener reportTypes disponibles diferentes y datos con estructuras ligeramente distintas. Normalizar campos como moneda, zona horaria y formato de fechas en tu pipeline de datos evita problemas de análisis posteriores.

La SP-API de reportes es infraestructura crítica para cualquier operación de ecommerce que escale más allá de lo artesanal. Entender su modelo asíncrono, respetar sus límites y diseñar sistemas resilientes a cambios determina si tu stack de datos es un activo operativo o una fuente constante de incidencias.