Roadmap del Proyecto

Resumen rápido

Este documento propone los próximos pasos para pasar de "entender SP-API" a "tener una aplicación real funcionando". El objetivo es construir de forma incremental: primero lo más simple que funcione, luego añadir complejidad según las necesidades reales.

---

Estado actual (punto de partida)

• Documentación completa de SP-API en español organizada por tema
• Comprensión clara de: autenticación, APIs principales, rate limits, fees, MCP, casos de uso
• Sin código de producción aún
• Sin infraestructura configurada

---

Fase 1: Setup mínimo (semana 1)

Objetivo: Tener las credenciales configuradas y hacer la primera llamada real a la API.

Tareas

1. Crear o verificar el perfil de desarrollador en Amazon

   • Ir a Seller Central → Apps y Servicios → Desarrollar Apps
   • Verificar o crear el perfil de desarrollador privado

2. Crear la primera aplicación

   • Tipo: Private (para empezar)
   • Obtener client_id y client_secret (LWA credentials)

3. Obtener el refresh token

   • Autorizar la app desde Seller Central → Gestionar aplicaciones
   • Guardar el refresh_token de forma segura (archivo .env o gestor de secretos)

4. Verificar la conexión

   # Script de verificación mínimo
   import requests
   
   def test_connection():
       token_response = requests.post("https://api.amazon.com/auth/o2/token", data={
           "grant_type": "refresh_token",
           "refresh_token": "REFRESH_TOKEN",
           "client_id": "CLIENT_ID",
           "client_secret": "CLIENT_SECRET",
       })
       access_token = token_response.json()["access_token"]
       print(f"Token obtenido: {access_token[:20]}...")
   
       # Obtener un pedido de prueba
       orders_response = requests.get(
           "https://sellingpartnerapi-eu.amazon.com/orders/v0/orders",
           headers={"x-amz-access-token": access_token},
           params={
               "MarketplaceIds": "A1RKKUPIHCS9HS",  # amazon.es
               "CreatedAfter": "2024-01-01T00:00:00Z",
           }
       )
       print(f"Status: {orders_response.status_code}")
       print(f"Pedidos encontrados: {len(orders_response.json().get('payload', {}).get('Orders', []))}")
   
   test_connection()

Resultado esperado: Conexión exitosa, primer pedido devuelto.

---

Fase 2: Primer caso de uso real (semanas 2-3)

Objetivo: Construir algo útil inmediatamente. Elige uno:

Opción A: Exportación de pedidos a Google Sheets

Para: Automatizar el seguimiento de pedidos sin herramientas de pago.

Pasos:

1. Crear proyecto en Google Cloud → habilitar Sheets API → descargar credentials.json
2. Instalar gspread y google-auth
3. Implementar script de exportación (ver 16-casos-de-uso-y-automatizaciones.md)
4. Ejecutar manualmente primero, luego automatizar con cron

Opción B: Script de monitorización de inventario

Para: Recibir alertas cuando un producto se queda sin stock.

Pasos:

1. Descargar informe de inventario FBA (GET_FBA_MYI_ALL_INVENTORY_DATA)
2. Filtrar productos con stock < umbral definido
3. Enviar alerta por email o Slack

Opción C: Dashboard local con Streamlit

Para: Visualizar ventas y métricas sin depender de Seller Central.

Pasos:

1. Descargar datos de Reports API (pedidos, settlement)
2. Guardar en CSV o SQLite local
3. Crear dashboard con streamlit y plotly

---

Fase 3: Infraestructura básica (semanas 4-6)

Objetivo: Hacer el sistema robusto y automático.

3.1 Módulo de autenticación centralizado

# auth.py — gestión de tokens
import time
import requests


class SPAPIAuth:
    def __init__(self, client_id: str, client_secret: str, refresh_token: str):
        self.client_id = client_id
        self.client_secret = client_secret
        self.refresh_token = refresh_token
        self._access_token = None
        self._token_expiry = 0

    def get_access_token(self) -> str:
        if time.time() < self._token_expiry - 60:
            return self._access_token
        self._refresh_token()
        return self._access_token

    def _refresh_token(self):
        response = requests.post("https://api.amazon.com/auth/o2/token", data={
            "grant_type": "refresh_token",
            "refresh_token": self.refresh_token,
            "client_id": self.client_id,
            "client_secret": self.client_secret,
        })
        response.raise_for_status()
        data = response.json()
        self._access_token = data["access_token"]
        self._token_expiry = time.time() + data["expires_in"]

3.2 Manejo de rate limits

Integrar el RateLimiter de 12-rate-limits-y-throttling.md en todas las llamadas.

3.3 Base de datos local

Guardar los datos en SQLite o PostgreSQL para no depender de la API para consultas:

• Tabla orders con todos los pedidos
• Tabla inventory con el stock actual
• Tabla reports con el historial de informes descargados

3.4 Automatización con scheduler

# Ejecutar con cron o APScheduler
import schedule
import time

def daily_sync():
    print("Iniciando sincronización diaria...")
    sync_orders()
    sync_inventory()
    print("Sincronización completada")

schedule.every().day.at("02:00").do(daily_sync)

while True:
    schedule.run_pending()
    time.sleep(60)

---

Fase 4: Notificaciones en tiempo real (semanas 7-8)

Objetivo: Reaccionar a eventos de Amazon sin polling.

Implementar Notifications API con SQS

1. Crear cola SQS en AWS
2. Configurar política de acceso (cuenta de Amazon: 437568002678)
3. Crear Destination y Subscriptions en SP-API
4. Implementar worker que procese mensajes SQS

Notificaciones prioritarias para implementar primero:

• ORDER_CHANGE: Pedidos nuevos → enviar notificación inmediata
• REPORT_PROCESSING_FINISHED: Informes listos → descargar automáticamente
• OFFER_CHANGED: Cambios de precio de competencia → base para repricer

---

Fase 5: App de producción (mes 2+)

Objetivo: Sistema robusto, escalable, con UI si es necesario.

5.1 Decisiones de arquitectura

Decisión	Opción simple	Opción escalable
Backend	Script Python en VPS	AWS Lambda + SQS
Base de datos	SQLite	PostgreSQL en RDS
Scheduler	Cron en servidor	EventBridge
Secrets	.env file	AWS Secrets Manager
Monitorización	Logs en archivo	CloudWatch

5.2 Posibles ampliaciones

• Multi-marketplace: Añadir soporte para amazon.de, amazon.fr, etc. Los marketplace IDs están en 02-autenticacion-y-conexion.md.
• Repricer: Suscribirse a OFFER_CHANGED y actualizar precios con Listings API. Ver 16-casos-de-uso-y-automatizaciones.md.
• PII y datos de envío: Si necesitas datos completos de comprador, solicitar acceso PII. Ver 04-acceso-pii-y-rdt.md.
• Public app: Si quieres dar acceso a otros vendedores, cambiar a perfil público. Ver 03-tipos-de-apps-y-desarrolladores.md.
• Integración con IA: Conectar el sistema a Claude Code o similar vía MCP. Ver 15-mcp-y-herramientas-ia.md.

---

Decisión crítica: ¿Eres third-party developer?

Antes de empezar:

• Si construyes solo para tus propias cuentas → Private developer, sin fees, más simple.
• Si construyes para otros vendedores → Third-party developer, fees desde enero 2026 ($1.400/año base).

Ver 14-fees-y-optimizacion-de-llamadas.md para entender el impacto económico.

---

Checklist de lanzamiento

• [ ] Credenciales LWA configuradas (client_id, client_secret, refresh_token)
• [ ] Marketplace ID correcto configurado
• [ ] Endpoint de región correcto (EU para España/Europa)
• [ ] Rate limiter implementado en todas las llamadas
• [ ] Manejo de errores y reintentos en lugar de fallar silenciosamente
• [ ] Access token con refresh automático (no hardcoded)
• [ ] Secretos en variable de entorno o gestor de secretos (nunca en el código)
• [ ] Logging básico para depuración
• [ ] Si es third-party: tarjeta de crédito registrada en Developer Central

---

Orden de lectura recomendado de esta documentación

1. 01-que-es-sp-api.md — entender el panorama general
2. 02-autenticacion-y-conexion.md — conectar y autenticar
3. 03-tipos-de-apps-y-desarrolladores.md — elegir tipo de app
4. 05-orders-api.md — primera API útil
5. 12-rate-limits-y-throttling.md — imprescindible para no ser bloqueado
6. 08-reports-api.md + 09-notifications-api.md — para sistemas eficientes
7. El resto según necesidades específicas