DEV Community

Cover image for Cómo Integrar la API de Amazon SP: Tutorial Paso a Paso
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Integrar la API de Amazon SP: Tutorial Paso a Paso

#api #automation #aws #tutorial

Resumen

La API de Amazon Selling Partner (SP-API) es una API REST que permite el acceso programático a datos de vendedores: pedidos, inventario, listados y cumplimiento. Utiliza OAuth 2.0 con roles IAM, requiere firma AWS SigV4 y tiene límites de tasa variables por endpoint (de 0.1 a 100 solicitudes/seg). Esta guía cubre configuración de cuenta, autenticación, endpoints clave, suscripciones a webhooks y estrategias de despliegue en producción.

Prueba Apidog hoy

💡Apidog simplifica las pruebas de integración de API. Pruebe sus puntos finales de SP-API, valide los flujos de OAuth, inspeccione las firmas de solicitud y depure los problemas de autenticación en un solo espacio de trabajo. Importe especificaciones de API, simule respuestas y comparta escenarios de prueba con su equipo.

¿Qué es la API de Amazon SP?

La API de Amazon Selling Partner (SP-API) es una API REST que da acceso programático a datos de vendedores. Sustituye a Marketplace Web Service (MWS) con mejoras en seguridad, rendimiento y funcionalidad.

Capacidades Clave

La SP-API permite:

  • Recuperar y actualizar pedidos
  • Gestionar inventario en todos los mercados
  • Crear, actualizar y eliminar listados
  • Gestionar envíos FBA
  • Analizar precios y competencia
  • Generar informes
  • Gestionar Contenido A+
  • Analizar marca y datos publicitarios

Comparación SP-API vs MWS

Característica SP-API MWS (Legado)
Arquitectura JSON RESTful Basado en XML
Autenticación OAuth 2.0 + IAM Token MWS
Seguridad AWS SigV4 Tokens simples
Límites de tasa Dinámicos Cuotas fijas
Mercados Unificados Específicos región
Estado Actual Obsoleto (Dic 2025)

Migre las integraciones de MWS a SP-API lo antes posible.

Resumen de la arquitectura

Amazon usa endpoints regionales:

https://sellingpartnerapi-na.amazon.com (Norteamérica)
https://sellingpartnerapi-eu.amazon.com (Europa)
https://sellingpartnerapi-fe.amazon.com (Lejano Oriente)
Enter fullscreen mode Exit fullscreen mode

Requisitos en toda solicitud:

  1. Firma AWS SigV4
  2. Token acceso OAuth
  3. Permisos IAM
  4. ID de solicitud

Mercados soportados

Región Mercados Endpoint API
América del Norte EE. UU., CA, MX sellingpartnerapi-na.amazon.com
Europa Reino Unido, DE, FR, IT, ES, NL, SE, PL, TR, EG, IN, AE, SA sellingpartnerapi-eu.amazon.com
Lejano Oriente JP, AU, SG, BR sellingpartnerapi-fe.amazon.com

Primeros pasos: Configuración de cuenta e IAM

Paso 1: Cree su cuenta de desarrollador

  1. Ingrese al Centro de Desarrolladores de Amazon
  2. Inicie sesión con su cuenta (requiere acceso a Seller Central)
  3. Vaya a Selling Partner API en el panel
  4. Acepte el Acuerdo de Desarrollador

Paso 2: Registre su aplicación

  1. Inicie sesión en Seller Central
  2. Navegue a Aplicaciones y Servicios > Desarrollar Aplicaciones
  3. Haga clic en Añadir Nueva Aplicación
  4. Complete:
    • Nombre de la app
    • Tipo de aplicación (“Autodesarrollada” o “Terceros”)
    • Caso de uso
    • URI de redirección (HTTPS para OAuth)

Recibirá:

  • ID de aplicación
  • ID de cliente
  • Secreto de cliente

No exponga estos datos. Use variables de entorno:

# .env
AMAZON_APPLICATION_ID="amzn1.application.xxxxx"
AMAZON_CLIENT_ID="amzn1.account.xxxxx"
AMAZON_CLIENT_SECRET="your_client_secret_here"
AMAZON_SELLER_ID="your_seller_id_here"
AWS_ACCESS_KEY_ID="your_aws_access_key"
AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
AWS_REGION="us-east-1"
Enter fullscreen mode Exit fullscreen mode

Paso 3: Cree un rol de IAM para la SP-API

  1. Inicie sesión en la Consola de AWS IAM
  2. Roles > Crear Rol
  3. Seleccione Otra cuenta de AWS como entidad de confianza
  4. Ingrese el ID de cuenta de Amazon según región:
  • NA: 906394416454
  • EU: 336853085554
  • FE: 774466381866

Paso 4: Configure la política de IAM

Adjunte esta política al rol:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:Invoke"
      ],
      "Resource": [
        "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/*"
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Nombre sugerido: SellingPartnerApiRole. Guarde el ARN.

Paso 5: Vincule el rol IAM a la aplicación

  1. Seller Central > Desarrollar aplicaciones
  2. Seleccione su app
  3. Editar > ARN del rol de IAM
  4. Ingrese el ARN y guarde

Amazon validará el rol en minutos.

Flujo de autenticación OAuth 2.0

Entendiendo OAuth en SP-API

Flujo de autorización:

1. El vendedor autoriza app
2. Redirección a URL de autorización de Amazon
3. Login y permisos del vendedor
4. Redirección con código de autorización
5. Intercambio por token LWA (Login with Amazon)
6. Intercambio por token de acceso SP-API
7. Uso del token en llamadas API (firmadas con SigV4)
8. Actualizar token al expirar (1h)
Enter fullscreen mode Exit fullscreen mode

Paso 6: Genere la URL de autorización 

const generateAuthUrl = (clientId, redirectUri, state) => {
  const baseUrl = 'https://www.amazon.com/sp/apps/oauth/authorize';
  const params = new URLSearchParams({
    application_id: process.env.AMAZON_APPLICATION_ID,
    client_id: clientId,
    redirect_uri: redirectUri,
    state: state,
    scope: 'sellingpartnerapi::notifications'
  });
  return `${baseUrl}?${params.toString()}`;
};
Enter fullscreen mode Exit fullscreen mode

Ámbitos de OAuth requeridos

Ámbito Descripción Caso de uso
sellingpartnerapi::notifications Recibir notificaciones Webhooks
sellingpartnerapi::migration Migrar desde MWS Integraciones legado

Paso 7: Intercambie el código por un token LWA 

const exchangeCodeForLwaToken = async (code, redirectUri) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code: code
    })
  });
  if (!response.ok) throw new Error('LWA Token Error');
  return await response.json();
};
Enter fullscreen mode Exit fullscreen mode

Paso 8: Intercambie el token LWA por credenciales temporales 

const assumeRole = async (lwaAccessToken) => {
  // Paso 1: Obtener token de cliente
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      scope: 'sellingpartnerapi::notifications'
    })
  });
  const data = await response.json();

  // Paso 2: Intercambio STS
  const stsResponse = await fetch('https://sts.amazonaws.com/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Bearer ${data.access_token}`
    },
    body: new URLSearchParams({
      Action: 'AssumeRole',
      RoleArn: 'arn:aws:iam::YOUR_ACCOUNT:role/SellingPartnerApiRole',
      RoleSessionName: 'sp-api-session',
      Version: '2011-06-15'
    })
  });
  return stsResponse;
};
Enter fullscreen mode Exit fullscreen mode

Paso 9: Implemente la actualización de tokens 

const refreshLwaToken = async (refreshToken) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });
  return await response.json();
};
Enter fullscreen mode Exit fullscreen mode

Firma de solicitudes AWS SigV4

Comprendiendo SigV4

Toda llamada a la SP-API debe estar firmada con AWS Signature Version 4.

Proceso de firma SigV4

Ejemplo de implementación:

const crypto = require('crypto');
class SigV4Signer {
  // ... implementación (ver arriba para detalles) ...
}
Enter fullscreen mode Exit fullscreen mode

Uso del SDK de AWS para SigV4

Recomendado usar el SDK:

const { SignatureV4 } = require('@aws-sdk/signature-v4');
const { Sha256 } = require('@aws-crypto/sha256-js');
// ... ver arriba para detalles ...
Enter fullscreen mode Exit fullscreen mode

API de Pedidos

Recuperación de pedidos 

const getOrders = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    createdAfter: options.createdAfter,
    createdBefore: options.createdBefore,
    orderStatuses: options.orderStatuses?.join(',') || '',
    marketplaceIds: options.marketplaceIds?.join(',') || ['ATVPDKIKX0DER'],
    maxResultsPerPage: options.maxResultsPerPage || 100
  });
  for (const [key, value] of params.entries()) if (!value) params.delete(key);
  const endpoint = `https://sellingpartnerapi-na.amazon.com/orders/v0/orders?${params.toString()}`;
  return makeSpApiRequest('GET', endpoint, accessToken);
};
Enter fullscreen mode Exit fullscreen mode

Estructura de respuesta de pedido 

{
  "payload": {
    "orders": [
      {
        "amazon_order_id": "112-1234567-1234567",
        // ... otros campos ...
      }
    ],
    "next_token": "eyJleHBpcmF0aW9uVGltZU9mTmV4dFRva2VuIjoxNzEwOTUwNDAwfQ=="
  }
}
Enter fullscreen mode Exit fullscreen mode

Obtención de artículos del pedido 

const getOrderItems = async (accessToken, orderId) => {
  const endpoint = `https://sellingpartnerapi-na.amazon.com/orders/v0/orders/${orderId}/orderItems`;
  return makeSpApiRequest('GET', endpoint, accessToken);
};
Enter fullscreen mode Exit fullscreen mode

Actualización del estado del envío 

const confirmShipment = async (accessToken, orderId, shipmentData) => {
  const endpoint = `https://sellingpartnerapi-na.amazon.com/orders/v0/orders/${orderId}/shipmentConfirmation`;
  const payload = {
    packageDetails: {
      packageReferenceId: shipmentData.packageReferenceId || '1',
      carrier_code: shipmentData.carrierCode,
      tracking_number: shipmentData.trackingNumber,
      ship_date: shipmentData.shipDate || new Date().toISOString(),
      items: shipmentData.items.map(item => ({
        order_item_id: item.orderItemId,
        quantity: item.quantity
      }))
    }
  };
  return makeSpApiRequest('POST', endpoint, accessToken, payload);
};
Enter fullscreen mode Exit fullscreen mode

Códigos comunes de transportistas

Transportista Código
USPS USPS
FedEx FEDEX
UPS UPS
DHL DHL
Canada Post CANADA_POST
Royal Mail ROYAL_MAIL
Australia Post AUSTRALIA_POST
Logística Amazon AMZN_UK

API de Inventario

Obtención de resúmenes de inventario 

const getInventorySummaries = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    granularityType: options.granularityType || 'Marketplace',
    granularityId: options.granularityId || 'ATVPDKIKX0DER',
    startDateTime: options.startDateTime || '',
    sellerSkus: options.sellerSkus?.join(',') || ''
  });
  const endpoint = `https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?${params.toString()}`;
  return makeSpApiRequest('GET', endpoint, accessToken);
};
Enter fullscreen mode Exit fullscreen mode

Actualización de inventario

No hay endpoint directo. Actualice inventario vía:

  1. Envíos FBA
  2. Pedidos MFN
  3. Actualizaciones de listados

Ejemplo para crear un plan de envío FBA:

const createInboundShipmentPlan = async (accessToken, shipmentData) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

API de Listados

Obtención de listados 

const getListings = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    marketplaceIds: options.marketplaceIds?.join(',') || ['ATVPDKIKX0DER'],
    itemTypes: options.itemTypes?.join(',') || ['ASIN', 'SKU'],
    identifiers: options.identifiers?.join(',') || '',
    issuesLocale: options.locale || 'en_US'
  });
  const endpoint = `https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items?${params.toString()}`;
  return makeSpApiRequest('GET', endpoint, accessToken);
};
Enter fullscreen mode Exit fullscreen mode

Creación o actualización de listados 

const submitListingUpdate = async (accessToken, listingData) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Eliminación de un listado 

const deleteListing = async (accessToken, sku, marketplaceIds) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

API de Informes

Creación de programaciones de informes 

const createReport = async (accessToken, reportType, dateRange) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Obtención del documento de informe 

const getReportDocument = async (accessToken, reportId) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

API de Notificaciones

Creación de suscripciones 

const createSubscription = async (accessToken, subscriptionData) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Configuración del destino de SNS 

const createSnsDestination = async (accessToken, destinationData) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Procesamiento de notificaciones 

const express = require('express');
const app = express();
// ...ver arriba para detalles...
Enter fullscreen mode Exit fullscreen mode

Límites de tasa y cuotas

Entendiendo los límites de tasa

Categoría Límite de tasa Límite de ráfaga
Pedidos 10 solicitudes/segundo 20
Artículos del Pedido 5 solicitudes/segundo 10
Inventario 2 solicitudes/segundo 5
Listados 10 solicitudes/segundo 20
Informes 0.5 solicitudes/segundo 1
Notificaciones 1 solicitud/segundo 2
Entrada FBA 2 solicitudes/segundo 5

Revise el header x-amzn-RateLimit-Limit en cada respuesta.

Implementación del manejo de límites de tasa 

const makeRateLimitedRequest = async (method, endpoint, accessToken, body = null, maxRetries = 5) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Implementación de cola de solicitudes 

class RateLimitedQueue {
  // ...ver arriba para detalles...
}
// Uso
const ordersQueue = new RateLimitedQueue(10, 20);
const orders = await ordersQueue.add(() => getOrders(accessToken, options));
Enter fullscreen mode Exit fullscreen mode

Mejores prácticas de seguridad

Gestión de credenciales

Nunca almacene claves en el código fuente.

// Malo
const AWS_ACCESS_KEY = 'AKIAIOSFODNN7EXAMPLE';
// Bueno
const AWS_ACCESS_KEY = process.env.AWS_ACCESS_KEY_ID;
// Mejor: AWS Secrets Manager
Enter fullscreen mode Exit fullscreen mode

Requisitos de almacenamiento de tokens

  • Use cifrado AES-256 para los tokens en reposo
  • Use HTTPS/TLS siempre
  • Limite acceso a los tokens
  • Registre accesos y rotaciones
  • Actualice tokens antes de expirar

Ejemplo de clase para cifrado:

class TokenStore {
  // ...ver arriba para detalles...
}
Enter fullscreen mode Exit fullscreen mode

Privilegio mínimo de IAM

Otorgue solo permisos necesarios, evite comodines en producción.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SPAPIOrdersAccess",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/orders/*"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Seguridad de la firma de solicitudes

  • Use HTTPS
  • Incluya todos los headers requeridos
  • Sincronice reloj del servidor
  • Rote credenciales regularmente
  • Prefiera roles IAM 
const validateTimestamp = (amzDate) => {
  // ...ver arriba para detalles...
};
Enter fullscreen mode Exit fullscreen mode

Prueba de integraciones de SP-API con Apidog

Por qué probar las integraciones

Las integraciones SP-API implican flujos de autenticación y límites de tasa complejos. Pruebe para:

  • Validar OAuth 2.0
  • Depurar SigV4
  • Probar manejo de errores y cuotas
  • Simular respuestas
  • Documentar flujos

Configuración de Apidog para pruebas SP-API

Paso 1: Importar OpenAPI

  1. Descargue la especificación desde el repositorio de Amazon
  2. Cree un nuevo proyecto en Apidog (apidog.com)
  3. Importe el archivo OpenAPI
  4. Configure las variables de entorno

Paso 2: Configure las variables de entorno

URL base (Sandbox): https://sandbox.sellingpartnerapi-na.amazon.com
URL base (Producción): https://sellingpartnerapi-na.amazon.com
Token de acceso LWA: {{lwa_access_token}}
Clave de acceso de AWS: {{aws_access_key}}
Clave secreta de AWS: {{aws_secret_key}}
Región: us-east-1
Enter fullscreen mode Exit fullscreen mode

Paso 3: Scripts de pre-solicitud para SigV4

// Script de pre-solicitud Apidog (ver arriba para detalles)
Enter fullscreen mode Exit fullscreen mode

Paso 4: Escenarios de prueba

// Prueba: Obtener pedidos últimas 24h (ver arriba para detalles)
Enter fullscreen mode Exit fullscreen mode

Simulación de respuestas SP-API

Utilice la simulación inteligente de Apidog:

{
  "payload": {
    "orders": [
      {
        "amazon_order_id": "112-{{randomNumber}}-{{randomNumber}}",
        "order_status": "Unshipped",
        "purchase_date": "{{now}}",
        "order_total": {
          "currency_code": "USD",
          "amount": "{{randomFloat 10 500}}"
        }
      }
    ],
    "next_token": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Depuración de problemas comunes

Problema: Firma SigV4 incorrecta

  • Verifique headers requeridos
  • Orden alfabético de headers
  • Solicitud canónica correcta
  • Marca de tiempo válida

Problema: Errores token OAuth

const tokenCheck = await apidog.send({
  method: 'GET',
  url: '/orders/v0/orders',
  params: { createdAfter: new Date().toISOString() }
});
if (tokenCheck.status === 401) {
  // Flujo de actualización de token
}
Enter fullscreen mode Exit fullscreen mode

Automatización de pruebas en CI/CD 

# GitHub Actions (ver arriba)
Enter fullscreen mode Exit fullscreen mode

Referencia de ID de Mercado

País ID de Mercado
Estados Unidos ATVPDKIKX0DER
Canadá A2EUQ1WTGCTBG2
México A1AM78C64UM0Y8

Top comments (0)