Notifications API

Resumen rápido

La Notifications API permite recibir eventos de Amazon en tiempo real en lugar de tener que consultar (hacer polling) la API continuamente. Cuando algo cambia (nuevo pedido, informe listo, cambio de precio, etc.), Amazon envía automáticamente un mensaje a una cola de AWS (SQS) o a Amazon EventBridge. Tu app procesa el mensaje cuando llega. Esto reduce drásticamente el consumo de rate limit.

---

Conceptos importantes

• SQS (Amazon Simple Queue Service): Un servicio de colas de mensajes de AWS. Amazon envía los mensajes de notificación a esta cola; tu app los consume desde ahí.
• EventBridge: Otro servicio de AWS para eventos. Algunos tipos de notificación de Amazon solo funcionan con EventBridge (no SQS).
• Subscription: La suscripción a un tipo de notificación. Debes crearla para empezar a recibir mensajes.
• Destination: El destino donde Amazon enviará las notificaciones. Para SQS, necesitas el ARN de tu cola.
• NotificationType: El tipo de evento al que te suscribes (ej. REPORT_PROCESSING_FINISHED, ORDER_CHANGE, OFFER_CHANGED).
• Lambda: Función serverless de AWS que puede procesarse automáticamente cuando llega un mensaje a una cola SQS.
• ARN (Amazon Resource Name): Identificador único de recursos AWS (ej. de una cola SQS o un rol IAM).

---

Tipos de notificación disponibles (SQS)

NotificationType	Cuándo se dispara
REPORT_PROCESSING_FINISHED	Cuando un informe solicitado está listo
ORDER_CHANGE	Cuando se crea o actualiza un pedido
OFFER_CHANGED	Cuando cambia el precio o el buybox de uno de tus productos
PRICING_HEALTH	Alertas sobre estado de precios
FEE_PROMOTION	Cuando hay promociones de fees activas
ACCOUNT_STATUS_CHANGED	Cuando cambia el estado de la cuenta del vendedor
ORDER_STATUS_CHANGE	Cambio de estado de un pedido

Algunos tipos como BRANDED_ITEM_CONTENT_CHANGE o PRODUCT_TYPE_DEFINITIONS_CHANGE solo están disponibles mediante EventBridge.

---

Cómo funciona

Arquitectura con SQS + Lambda

Amazon SP-API
    ↓ (evento: nuevo pedido, informe listo, etc.)
Cola SQS (AWS)
    ↓ (trigger automático)
AWS Lambda
    ↓ (lógica de negocio)
Tu base de datos / Slack / Email / Dashboard

Proceso de configuración

1. Crear una cola SQS en tu cuenta de AWS.
2. Configurar la política de acceso de la cola para permitir que Amazon SP-API envíe mensajes.
3. Crear un Destination en SP-API apuntando al ARN de tu cola.
4. Crear Subscriptions para los tipos de notificación que quieres recibir.
5. Procesar los mensajes desde la cola (con Python, Lambda, etc.).

---

Pasos prácticos

1. Crear la cola SQS en AWS

1. Ir a AWS Console → SQS → Create Queue.
2. Tipo: Standard Queue.
3. Nombre: algo como sp-api-notifications.
4. Guardar el ARN y la URL de la cola.

2. Configurar la política de acceso de la cola

La cola SQS necesita una política que permita al sistema de Amazon enviar mensajes. Añade esta política en la sección "Access Policy" de la cola:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::437568002678:root"
      },
      "Action": [
        "SQS:GetQueueAttributes",
        "SQS:SendMessage"
      ],
      "Resource": "arn:aws:sqs:eu-west-1:TU_CUENTA:sp-api-notifications"
    }
  ]
}

El número 437568002678 es la cuenta de Amazon SP-API. Es fijo, no lo cambies.

3. Crear Destination y Subscriptions (Python)

import requests

def setup_notifications(
    access_token: str,
    endpoint: str,
    marketplace_id: str,
    sqs_arn: str,
    notification_types: list[str]
) -> dict:
    headers = {
        "x-amz-access-token": access_token,
        "Content-Type": "application/json",
    }

    # Crear destination
    dest_response = requests.post(
        f"{endpoint}/notifications/v1/destinations",
        headers=headers,
        json={
            "name": "my-sqs-destination",
            "resourceSpecification": {
                "sqs": {"arn": sqs_arn}
            }
        }
    )
    dest_response.raise_for_status()
    destination_id = dest_response.json()["payload"]["destinationId"]
    print(f"Destination creado: {destination_id}")

    # Crear subscriptions para cada tipo
    subscriptions = {}
    for notification_type in notification_types:
        sub_response = requests.post(
            f"{endpoint}/notifications/v1/subscriptions/{notification_type}",
            headers=headers,
            json={
                "payloadVersion": "1.0",
                "destinationId": destination_id,
            }
        )
        sub_response.raise_for_status()
        subscriptions[notification_type] = sub_response.json()["payload"]["subscriptionId"]
        print(f"Suscripción creada para {notification_type}: {subscriptions[notification_type]}")

    return subscriptions


# Ejemplo de uso
setup_notifications(
    access_token=token,
    endpoint="https://sellingpartnerapi-eu.amazon.com",
    marketplace_id="A1RKKUPIHCS9HS",
    sqs_arn="arn:aws:sqs:eu-west-1:123456789:sp-api-notifications",
    notification_types=[
        "REPORT_PROCESSING_FINISHED",
        "ORDER_CHANGE",
        "OFFER_CHANGED",
    ]
)

4. Leer mensajes de la cola (Python con boto3)

import boto3
import json

def process_notifications(queue_url: str, region: str = "eu-west-1"):
    sqs = boto3.client("sqs", region_name=region)

    while True:
        response = sqs.receive_message(
            QueueUrl=queue_url,
            MaxNumberOfMessages=10,
            WaitTimeSeconds=20,  # Long polling
        )

        messages = response.get("Messages", [])
        for msg in messages:
            body = json.loads(msg["Body"])
            notification_type = body.get("notificationType")

            print(f"Notificación recibida: {notification_type}")
            print(f"Payload: {json.dumps(body, indent=2)}")

            # Eliminar mensaje procesado de la cola
            sqs.delete_message(
                QueueUrl=queue_url,
                ReceiptHandle=msg["ReceiptHandle"]
            )

5. Configurar Lambda como trigger automático

1. Crear una función Lambda en AWS.
2. En la configuración de la función, añadir un trigger de tipo "SQS".
3. Seleccionar tu cola SQS.
4. Asegurarse de que el rol de ejecución de Lambda tiene permisos para leer de SQS (AWSLambdaSQSQueueExecutionRole).
5. El código de Lambda se ejecuta automáticamente cada vez que llega un mensaje.

# Handler básico de Lambda
import json

def lambda_handler(event, context):
    for record in event["Records"]:
        body = json.loads(record["body"])
        notification_type = body.get("notificationType")

        if notification_type == "REPORT_PROCESSING_FINISHED":
            report_document_id = body["payload"]["reportDocumentId"]
            # ... descargar y procesar el informe
        elif notification_type == "ORDER_CHANGE":
            order_id = body["payload"]["orderId"]
            # ... procesar el pedido

---

Errores comunes

• Olvidar la política de acceso de la cola SQS: Sin la política correcta, Amazon no puede enviar mensajes y no recibirás notificaciones.
• No implementar Long Polling en SQS: El sondeo corto (sin WaitTimeSeconds) crea muchas más peticiones y cuesta más. Usa WaitTimeSeconds=20 para long polling.
• No eliminar mensajes tras procesarlos: Los mensajes no procesados vuelven a la cola después del tiempo de visibilidad. Si no los eliminas, los procesarás dos veces.
• Suscribirse a demasiados tipos innecesarios: Solo suscríbete a los tipos que realmente vas a procesar.

---

Qué debo saber antes de programarlo

• Necesitas una cuenta de AWS para crear la cola SQS. El coste de SQS para volúmenes normales de notificaciones es mínimo (prácticamente gratuito con el free tier).
• Las Notifications son push (Amazon te envía), no pull (tú consultas). Esto es más eficiente y reduce el rate limit consumido.
• El caso de uso más común y valioso: combinar Reports API + Notifications API. Pides el informe, suscribes a REPORT_PROCESSING_FINISHED, y Amazon te avisa cuando está listo sin que tengas que sondear.
• Otro caso muy útil: suscribirse a ORDER_CHANGE para reaccionar a nuevos pedidos en tiempo real (enviar emails, actualizar tu sistema, etc.) sin tener que consultar Orders API continuamente.
• Para apps en producción con muchos clientes, considera usar EventBridge en lugar de SQS para mayor escalabilidad.

---

Pendiente de revisar

• ¿Cuánto tiempo se guardan los mensajes en la cola SQS antes de expirar si no se consumen?
• ¿Se necesita configurar algo diferente para recibir notificaciones de múltiples cuentas de vendedor?
• ¿Cómo funciona EventBridge en comparación con SQS para las notificaciones de SP-API?