Documentación API Amazon Vendor Central: guía SP-API, autenticación y endpoints específicos de proveedor
Guía completa SP-API para Amazon Vendor Central — autenticación LWA OAuth 2.0, endpoints vendor-specific, SLA de reconocimiento de PO, limitaciones sandbox y errores comunes.
Índice de contenidos
Resumen — Puntos clave
-
Amazon reemplazó su API legacy MWS (Marketplace Web Services) con la Selling Partner API (SP-API) — las integraciones de Vendor Central utilizan el mismo framework SP-API que Seller Central, con secciones de API específicas para proveedores que cubren pedidos de compra, confirmaciones de inventario, aprovisionamiento retail y confirmaciones de envío
-
La autenticación SP-API utiliza Login with Amazon (LWA) OAuth 2.0, no el antiguo modelo de clave de acceso/clave secreta — las nuevas integraciones deben implementar el patrón de intercambio de tokens LWA; las credenciales MWS dejaron de funcionar para la mayoría de endpoints después de enero de 2024
-
Las tres secciones SP-API de proveedor con mayor impacto práctico son: Vendor Orders (recibir y confirmar pedidos de compra), Vendor Shipments (ASNs y enrutamiento de facturas) y Vendor Inventory (enviar feeds de inventario al sistema de Amazon)
-
El entorno sandbox de SP-API de Amazon usa respuestas mock estáticas, no datos en vivo — es adecuado para pruebas de conexión y validación del flujo de autenticación, pero no para pruebas de flujo de trabajo end-to-end con patrones de datos realistas
-
El fallo de integración SP-API más frecuente en proveedores es la latencia en la confirmación de pedidos de compra — el SLA de Amazon para la confirmación de PO es típicamente de 24-48 horas, y superar esta ventana activa flujos de autocancelación que afectan a las métricas de tasa de llenado y el scorecard de proveedor
La documentación de la API de Amazon Vendor Central es de esas cosas que suenan sencillas hasta que estás realmente construyendo una integración. La documentación existe, es razonablemente completa, pero navegar la transición de MWS a SP-API, entender los endpoints específicos de proveedor frente a los endpoints de vendedor, y saber qué APIs importan realmente para los flujos de trabajo que intentas automatizar requiere más contexto del que la propia documentación proporciona.
Esta guía cubre la estructura SP-API para integraciones de Vendor Central específicamente — qué está disponible, cómo funciona la autenticación, las secciones API específicas de proveedor que usarás realmente, y los patrones de integración que importan para la eficiencia operativa.
MWS ha muerto — SP-API es la plataforma
Si trabajas con documentación antigua o código de integración interno, lo primero que debes saber: Amazon deprecó MWS (Marketplace Web Services) y lo reemplazó completamente con la Selling Partner API (SP-API). Amazon completó el sunset de MWS en enero de 2024 — cualquier integración que todavía use claves de acceso de MWS necesita migrarse al modelo de autenticación LWA OAuth 2.0 de SP-API.
La documentación de SP-API está en developer-docs.amazon.com/sp-api/. La consola de desarrollador para registrar aplicaciones y gestionar credenciales está en sellercentral.amazon.com/developer/applications (sí, es Seller Central — Vendor Central no tiene su propio portal de desarrollador, lo que confunde a la mayoría de personas que construyen integraciones de Vendor Central por primera vez).
SP-API cubre tanto los flujos de trabajo de Seller Central como de Vendor Central a través del mismo framework API, con diferentes secciones de endpoints y alcances de acceso según el tipo de cuenta. Una cuenta híbrida 1P/3P puede mantener tokens OAuth tanto de Vendor Central como de Seller Central y acceder a ambos conjuntos de endpoints desde un único registro de aplicación.
2024
Año en que Amazon completó el sunset de MWS — cualquier integración de Vendor Central que todavía use autenticación con clave de acceso MWS necesita migrarse a SP-API LWA OAuth 2.0 de forma inmediata
Fuente: Documentación para desarrolladores SP-API de Amazon
Autenticación SP-API para integraciones de Vendor Central
SP-API usa Login with Amazon (LWA) OAuth 2.0. El flujo de autenticación es:
1. Registro de aplicación. Registra tu aplicación en la consola de desarrollador de Seller Central. Recibirás un Client ID y un Client Secret. Para el acceso a Vendor Central, necesitas especificar los alcances (scopes) de proveedor apropiados durante el registro.
2. Flujo de autorización. Para Vendor Central, autorizas la aplicación a través de la interfaz de Vendor Central (no Seller Central). El patrón de URL de autorización para Vendor Central es: https://vendorcentral.amazon.com/apps/authorize/consent?application_id={app_id}&state={state}&version=beta
3. Intercambio de tokens. Intercambia el código de autorización por un token de acceso y un refresh token mediante LWA: POST a https://api.amazon.com/auth/o2/token con grant_type=authorization_code y tus credenciales de cliente.
4. Renovación de tokens. Los tokens de acceso caducan después de 1 hora. Usa el refresh token con grant_type=refresh_token para obtener un nuevo token de acceso. Implementa lógica de renovación de tokens en tu capa de integración — no codifiques tokens de acceso en duro.
5. Firma de solicitudes. Las solicitudes SP-API requieren firma AWS Signature Version 4 usando el Restricted Data Token (RDT) o el token de acceso LWA estándar según el endpoint. El Restricted Data Token es necesario para endpoints que devuelven PII (datos de clientes) — la mayoría de endpoints de aprovisionamiento de proveedor no requieren RDT.
Las secciones SP-API específicas de proveedor que importan
| Sección API | Operaciones clave | SLA / nota operativa |
|---|---|---|
| Vendor Orders | GET pedidos de compra, enviar confirmaciones de PO | Confirmar en 24-48h — la falta de ACK activa autocancelación |
| Vendor Shipments | Enviar Advance Shipment Notices (ASNs), enrutamiento de facturas | ASN requerido antes de la llegada del envío — afecta eficiencia de recepción |
| Vendor Inventory | Enviar feeds de inventario, actualizaciones de disponibilidad en almacén | Los feeds de inventario informan el algoritmo de reposición de Amazon |
| Retail Procurement | Gestión de pedidos de compra para flujos de aprovisionamiento retail | Usado por proveedores más grandes con relaciones directas con compradores retail |
| Catalog Items | Recuperar datos del catálogo ASIN, atributos de producto | Solo lectura para proveedores vía SP-API; las actualizaciones van por UI de Vendor Central o feeds |
| Product Pricing | Datos de precios competitivos, información de precio Buy Box | Rate-limited; usar para inteligencia de precios, no monitorización en tiempo real |
SESIÓN GRATUITA
¿Construyendo una integración con la API de Vendor Central? Evita los puntos de fallo más comunes.
Epinium ha construido integraciones SP-API en producción para más de 200 proveedores. Una llamada de 30 minutos cubre tu arquitectura de integración, configuración de autenticación, diseño de SLA para confirmación de PO, y qué endpoints de la API de proveedor son realmente estables en producción.
Reservar revisión técnica → ✓ Gratis ✓ 30 min ✓ Sin compromiso
Vendor Orders API — la integración que afecta a tu scorecard
La Vendor Orders API es la sección SP-API operativamente más crítica para la mayoría de proveedores. Amazon genera Pedidos de Compra a través de Vendor Central y los pone disponibles vía esta API. Tu integración necesita:
Hacer polling de nuevos POs. GET /vendor/orders/v1/purchaseOrders con status=NEW devuelve POs abiertos pendientes de confirmación. Establece un calendario de polling apropiado a tu volumen de pedidos — los proveedores de alto volumen suelen hacer polling cada 15-30 minutos en horario laboral; los de menor volumen pueden usar polling horario.
Confirmar dentro de la ventana de SLA. Envía confirmaciones vía POST /vendor/orders/v1/acknowledgements. El payload especifica el número de PO, la cantidad confirmada por línea de pedido y la condición del artículo. Se admiten confirmaciones parciales — puedes confirmar cantidades parciales y marcar líneas específicas como en espera. El detalle operativo crítico: si superas la ventana de confirmación (típicamente 24-48 horas después de la creación del PO), Amazon puede autocancelar el PO y esto afecta a tu tasa de confirmación puntual en el scorecard de proveedor.
Gestionar la respuesta correctamente. La API de confirmación devuelve un transactionId, no una confirmación de éxito/error síncrona. Necesitas hacer polling del endpoint de estado de transacción para confirmar que la confirmación fue procesada. Muchas integraciones primeriza confunden la respuesta del transactionId con una confirmación y saltan el paso de polling de transacción — esto crea fallos silenciosos de confirmación.
El manejo de errores para Vendor Orders merece atención específica: la API de Amazon devuelve respuestas 429 (Too Many Requests) cuando se alcanzan los límites de tasa, y estos límites varían por endpoint y cuenta. Implementa backoff exponencial con jitter, no lógica de reintento a intervalos fijos. Un reintento fijo de 1 segundo golpeando una ventana de límite de tasa de 5 minutos agotará todos los intentos de reintento inmediatamente.
Entorno sandbox — qué prueba realmente
SP-API proporciona un entorno sandbox en sandbox.sellingpartnerapi-na.amazon.com (más variantes EU y FE). Para las APIs de Vendor Central, el sandbox usa respuestas mock estáticas definidas en la especificación API — no genera POs dinámicos, datos de inventario reales, ni flujos de confirmación realistas.
Para qué es útil el sandbox: validación del flujo de autenticación, verificación de la firma de solicitudes, parseo del esquema de respuesta y confirmación de que tu biblioteca cliente de API envía solicitudes correctamente formadas. Para qué no es útil: probar flujos de trabajo end-to-end con tiempos realistas, probar tu lógica de SLA de confirmación bajo volúmenes reales de pedidos, o simular condiciones de error que dependen del estado.
Para pruebas de integración más realistas, necesitas una cuenta de Vendor Central de staging o una prueba de producción controlada con POs reales mínimos. Algunos proveedores usan un marketplace de prueba dedicado (como Amazon.com.mx para proveedores de EE.UU.) para ejecutar pruebas de integración de menor riesgo antes de desplegar en el marketplace principal.
Fallos de integración más comunes y cómo evitarlos
De la construcción y revisión de integraciones SP-API de proveedor, estos son los fallos que vemos más consistentemente:
Sin lógica de renovación de tokens. Los tokens de acceso LWA caducan después de 1 hora. Las integraciones que codifican tokens de acceso en duro o no implementan lógica de renovación fallan silenciosamente después de una hora de operación y requieren intervención manual. Implementa lógica de refresh token en cada llamada API — comprueba la caducidad del token y renuévalo proactivamente, no reactivamente después de un error 401.
Falta de polling de estado de transacción. Como se indicó anteriormente, los endpoints de confirmación y envío de confirmación de pedido devuelven transactionIds, no confirmaciones directas de éxito. No hacer polling del estado de transacción crea fallos silenciosos donde las confirmaciones parecen exitosas pero no se procesan.
ID de marketplace incorrecto. Los endpoints de SP-API requieren IDs de marketplace para la mayoría de operaciones. Los IDs de marketplace de Amazon están documentados pero se confunden frecuentemente: ATVPDKIKX0DER es Amazon.com de EE.UU.; A2EUQ1WTGCTBG2 es Amazon.ca; A1F83G8C2ARO7P es Amazon.co.uk. Usar el ID de marketplace incorrecto produce respuestas de error crípticas.
Manejo inadecuado de límites de tasa. Cada endpoint de SP-API tiene límites de tasa específicos (solicitudes por segundo y capacidad de burst). Estos están documentados por endpoint en la referencia SP-API. Construye el manejo de límites de tasa como un componente genérico en tu cliente API, no como lógica de reintento endpoint por endpoint.
¿Dónde está la documentación de la API de Amazon Vendor Central?
La documentación de la API de Amazon Vendor Central es parte de la documentación SP-API en developer-docs.amazon.com/sp-api/, bajo la categoría Vendors en la navegación izquierda. El registro de aplicaciones y la gestión de credenciales para integraciones de Vendor Central se hace a través de la consola de desarrollador de Seller Central en sellercentral.amazon.com/developer/applications, a pesar de ser una integración de Vendor Central — no existe un portal de desarrollador separado para Vendor Central.
¿Es la API de Amazon Vendor Central la misma que la de Seller Central?
Utilizan el mismo framework SP-API, el mismo método de autenticación (LWA OAuth 2.0) y la misma consola de desarrollador. La diferencia está en las secciones de endpoints y los scopes OAuth: los endpoints específicos de proveedor cubren pedidos de compra, envíos, inventario y flujos de aprovisionamiento retail propios del modelo de proveedor 1P. Una cuenta híbrida 1P/3P puede acceder a ambos conjuntos de endpoints con tokens de autorización separados.
¿Cómo me autentico con el SP-API de Amazon Vendor Central?
Registra tu aplicación en la consola de desarrollador de Seller Central, obtén Client ID y Client Secret, luego autoriza la aplicación mediante el flujo de consentimiento OAuth de Vendor Central (vendorcentral.amazon.com/apps/authorize/consent). Intercambia el código de autorización por tokens de acceso y refresh mediante el endpoint de tokens LWA en api.amazon.com/auth/o2/token. Los tokens de acceso caducan después de 1 hora — implementa lógica de refresh token. Firma las solicitudes API usando AWS Signature Version 4 con tu token de acceso LWA.
¿Cuál es el SLA de confirmación de PO para la Vendor Orders API?
Amazon espera la confirmación de PO en 24-48 horas desde la creación del PO, aunque el SLA exacto puede variar según el acuerdo con el proveedor. Superar la ventana de confirmación activa flujos de autocancelación en las líneas no confirmadas y afecta negativamente a tu tasa de confirmación puntual en el scorecard de proveedor. Construye tu lógica de polling y confirmación con frecuencia suficiente (mínimo 2-3 veces al día) para cumplir de forma fiable esta ventana de SLA para todos los POs.
¿Funciona el sandbox de SP-API para las pruebas de Vendor Central?
El sandbox de SP-API usa respuestas mock estáticas para los endpoints de Vendor Central — valida autenticación y formato de solicitudes pero no simula ciclos de vida reales de PO, volúmenes dinámicos de pedidos ni condiciones de error que dependen del estado de la cuenta. Para pruebas de integración realistas necesitas una cuenta de proveedor de staging o una prueba controlada de bajo volumen contra un marketplace secundario. El sandbox es más útil para la verificación inicial de conexión y el parseo de esquemas, no para la validación de flujos de trabajo end-to-end.
Construir una integración con la API de Vendor Central es un tipo de proyecto diferente a una integración típica de API REST. Las consecuencias son operativas: un fallo en la confirmación de un PO afecta a tu tasa de llenado, tu scorecard y potencialmente tu relación de proveedor con Amazon. La documentación es completa pero requiere saber qué partes importan para qué flujos de trabajo — las secciones de proveedor están bien definidas, pero navegar un framework que comparte infraestructura con el ecosistema mucho más grande de Seller Central requiere orientación. Hacer bien el flujo de autenticación, implementar el polling de estado de transacción y diseñar lógica de confirmación que cumpla de forma fiable el SLA de Amazon son las tres cosas que determinan si una integración SP-API de proveedor funciona en producción o falla silenciosamente en mitad de la noche.
TRANSFORM BY EPINIUM
Integraciones de Vendor Central que funcionan en producción, no solo en el sandbox
Epinium construye y audita integraciones SP-API de proveedor para más de 200 marcas — automatización de confirmación de PO, envío de ASN, gestión de feeds de inventario. Revisión técnica gratuita de tu arquitectura de integración o plan.
Gratis · 30 min · Sin compromiso
