Migración de MWS a SP-API

Resumen rápido

MWS (Marketplace Web Service) fue la primera API de Amazon para vendedores. Era XML/SOAP, difícil de usar y ya está completamente deprecada. SP-API es su reemplazo: REST/JSON, más moderna, con mejores herramientas. Si tienes código que usa MWS, ya no funciona. Si encuentras scripts legacy de MWS en un proyecto, hay que reescribirlos usando SP-API.

---

Conceptos importantes

• MWS: La API antigua de Amazon (XML, SOAP). Completamente deprecated desde 2024. No admite nuevas conexiones.
• SP-API: La API actual. REST/JSON, con OAuth 2.0 (LWA) para autenticación.
• Migration: El proceso de reemplazar código MWS por código SP-API. No es una simple sustitución 1:1 — las estructuras de datos son distintas.
• Breaking changes: MWS respondía en XML; SP-API responde en JSON. Las funciones no son equivalentes directas.
• Deprecation: Algunas categorías de MWS dejaron de funcionar antes que otras. El calendario fue:
  • Fulfillment y Orders: deprecado en septiembre de 2023
  • Todo lo demás: deprecado en abril de 2024

---

Diferencias principales: MWS vs SP-API

Aspecto	MWS (antiguo)	SP-API (actual)
Protocolo	SOAP / XML	REST / JSON
Autenticación	AWS Signature v2 + MWS Auth Token	OAuth 2.0 (LWA)
Documentación	Difícil, poco actualizada	Mejor estructurada
Soporte	Deprecado, sin actualizaciones	Activo
Lenguajes	SDKs legacy	SDKs modernos + Postman
Paginación	NextToken (similar)	NextToken (igual concepto)
Rate limits	Quota system	Token bucket algorithm

Equivalencia de APIs

MWS API	SP-API equivalente
Orders	Orders API
Products	Catalog Items API
Reports	Reports API
Feeds (Inventory/Price)	Feeds API + Listings API
Fulfillment	Orders API (FBM confirm)
Finances	Finances API
Subscriptions	Notifications API

---

Cómo funciona la migración

Proceso recomendado (5 pasos)

1. Análisis del código existente

Documenta qué funciones MWS usa cada parte del sistema:

• ¿Qué endpoints MWS se llaman?
• ¿Qué datos se usan de cada respuesta?
• ¿Con qué frecuencia se llama cada función?
• ¿Hay procesamiento de XML que habrá que cambiar a JSON?

2. Optimización del diseño

La migración es una oportunidad para mejorar la arquitectura:

• ¿Se puede reemplazar polling por Notifications API?
• ¿Se puede usar Reports API en vez de llamadas individuales repetidas?
• ¿Hay bucles ineficientes que se pueden simplificar?

3. Creación de nueva app en Developer Central

Si tienes una app MWS, necesitas crear una nueva app SP-API:

1. Ir a sellercentral.amazon.es → Apps y servicios → Desarrollar apps
2. Crear perfil de desarrollador (si no lo tienes)
3. Crear nueva aplicación → obtener client_id y client_secret de LWA
4. Obtener el refresh_token autorizando la app desde Seller Central

4. Reescritura de funciones

Reemplazar cada llamada MWS por su equivalente SP-API. Ejemplo:

MWS (XML, antiguo)

# MWS: ListOrders
import boto3
# ... configurar con AWS keys ...
response = mws_client.list_orders(
    marketplace_id="A1RKKUPIHCS9HS",
    created_after=date_str,
)
# Parsear XML de la respuesta
import xml.etree.ElementTree as ET
orders = ET.fromstring(response.text).findall(".//Order")

SP-API (JSON, actual)

# SP-API: GetOrders
import requests

response = requests.get(
    "https://sellingpartnerapi-eu.amazon.com/orders/v0/orders",
    headers={"x-amz-access-token": access_token},
    params={
        "MarketplaceIds": "A1RKKUPIHCS9HS",
        "CreatedAfter": date_str,
    },
)
orders = response.json()["payload"]["Orders"]

5. Documentar el nuevo sistema

Aprovecha la migración para documentar el código nuevo: qué hace cada función, qué endpoints llama, qué credenciales necesita.

---

Pasos prácticos para migrar Orders

Antes (MWS)

# Típico código MWS para obtener órdenes
def get_orders_mws(mws_access_key, mws_secret_key, seller_id, marketplace_id, start_date):
    # ... XML payload construction ...
    # ... AWS Signature v2 ...
    # ... XML response parsing ...
    pass  # Código XML verboso y frágil

Después (SP-API)

import requests
from datetime import datetime, timedelta

def get_orders_sp_api(access_token: str, marketplace_id: str) -> list:
    """Obtiene los pedidos de los últimos 30 días."""
    endpoint = "https://sellingpartnerapi-eu.amazon.com"
    headers = {"x-amz-access-token": access_token}

    created_after = (datetime.utcnow() - timedelta(days=30)).strftime("%Y-%m-%dT%H:%M:%SZ")
    all_orders = []
    next_token = None

    while True:
        params = {"MarketplaceIds": marketplace_id, "CreatedAfter": created_after}
        if next_token:
            params["NextToken"] = next_token

        response = requests.get(f"{endpoint}/orders/v0/orders", headers=headers, params=params)
        response.raise_for_status()
        payload = response.json().get("payload", {})

        all_orders.extend(payload.get("Orders", []))
        next_token = payload.get("NextToken")
        if not next_token:
            break

    return all_orders

---

Errores comunes en la migración

• Migrar línea a línea sin optimizar: No copies la lógica MWS sin cuestionarla. MWS era verbosa; la migración es una oportunidad de simplificar.
• Olvidar que las estructuras JSON son distintas: Los campos en SP-API se llaman diferente que en MWS. Por ejemplo, en MWS AmazonOrderId y en SP-API AmazonOrderId (puede coincidir, pero no siempre).
• No actualizar el sistema de autenticación: MWS usaba AWSAccessKey + SecretKey + MWSAuthToken. SP-API usa client_id + client_secret + refresh_token. Son mecanismos completamente distintos.
• Esperar que los feeds XML sean iguales: Los feeds de Feeds API de SP-API usan el mismo formato XML de Amazon Envelope, pero el proceso de envío es diferente (ver 10-feeds-api.md).
• No revisar las apps de terceros: Si usas plugins o conectores externos (Shopify, WordPress, etc.) que se basaban en MWS, también debes actualizarlos o reemplazarlos.

---

Qué debo saber antes de programarlo

• MWS ya no acepta nuevas conexiones. Si intentas crear credenciales MWS ahora, no puedes. Solo SP-API está disponible para proyectos nuevos.
• Si encuentras código MWS en un proyecto activo, está funcionando con credenciales antiguas que ya no se pueden regenerar. Si se pierden esas credenciales, no hay vuelta atrás.
• La documentación oficial de MWS ya no está activa. Si necesitas entender qué hacía una función MWS, tendrás que deducirlo del código o consultar cachés históricas.
• Amazon nunca volverá a reactivar MWS. Es una migración obligatoria y permanente.

---

Pendiente de revisar

• ¿Hay alguna API de SP-API que equivalga a Finances API de MWS para datos de settlement completos?
• ¿Los feeds de MWS y los feeds de SP-API son compatibles en formato XML?
• ¿Qué pasa con las apps MWS que tenían roles específicos de PII? ¿Se pueden migrar directamente?