Cómo integrar Amazon Seller Messages API paso a paso

Escrito por Evan Huang

Publicado el 19 de agosto de 2026 • 17 min de lectura

Aprender a integrar Amazon Seller Messages API empieza por utilizar el servicio correcto de Amazon. El producto oficial es Messaging API v1, parte de Selling Partner API de Amazon. Permite a una aplicación de vendedor descubrir qué tipos de mensajes están disponibles para un pedido concreto y solicitar a Amazon que envíe al comprador un mensaje aprobado relacionado con ese pedido.

Lo difícil no es realizar una solicitud HTTP. Una integración fiable debe gestionar la autorización del vendedor, endpoints regionales, disponibilidad de mensajes por pedido, validación de esquemas, adjuntos opcionales, límites de uso y normas de comunicación de Amazon. También debe evitar un error frecuente: tratar Messaging API como una API de bandeja de entrada general o de automatización de marketing. La referencia actual documenta el descubrimiento de acciones y las operaciones de envío permitidas, no un endpoint general para descargar todo el historial de mensajes de un vendedor.

Esta guía convierte esos requisitos en un flujo de integración preparado para producción que abarca configuración de acceso, autenticación LWA, descubrimiento de acciones, adjuntos, entrega de mensajes, pruebas, seguimiento y gestión de fallos. Los ejemplos utilizan marcadores de posición y deben adaptarse al esquema de mensaje devuelto para el pedido seleccionado.

Descripción general de Amazon Seller Messages API

Nombre oficial de la API

«Amazon Seller Messages API» es una frase de búsqueda útil, pero Amazon denomina el servicio Messaging API v1. Es una API de SP-API, el conjunto basado en REST de Amazon para aplicaciones de vendedores y proveedores.

Messaging API está disponible para aplicaciones de vendedores. La mayoría de las operaciones requieren el rol Buyer Communication. La API funciona con acciones específicas de cada pedido, por lo que la aplicación debe empezar con un identificador de pedido de Amazon y un identificador de marketplace. No puede suponer que todos los tipos de mensajes están disponibles para todos los pedidos.

Alcance de mensajería compatible

La Messaging API actual admite un conjunto controlado de comunicaciones del vendedor al comprador. Según el pedido y el marketplace, las acciones disponibles pueden incluir confirmar detalles del pedido o entrega, solicitar información de personalización, proporcionar información de garantía, enviar una declaración legal o una factura.

El patrón habitual es:

1. Seleccionar un pedido.
2. Preguntar a Amazon qué acciones de mensaje están permitidas en ese momento.
3. Validar la entrada del vendedor frente al esquema devuelto.
4. Subir un adjunto cuando la acción seleccionada lo admita.
5. Llamar a la operación asociada a esa acción.

Amazon determina la disponibilidad de mensajes al recibir la solicitud. El estado logístico, tipo de vendedor, marketplace y número de mensajes ya enviados pueden afectar a las acciones devueltas para un pedido.

Límites de Messaging API

Messaging API debe tratarse como un servicio orientado al envío y vinculado a pedidos. La referencia actual de v1 documenta getMessagingActionsForOrder y operaciones para enviar tipos de mensajes permitidos. No documenta una operación general para descargar toda la bandeja de entrada de Seller Central ni todas las respuestas de compradores.

Esta distinción importa al comparar distintas API de productos de Amazon. Un sistema que redacta o envía un mensaje permitido de pedido sigue necesitando un método separado y documentado para cualquier requisito de mensajes entrantes. No debe suponerse que Notifications API entrega respuestas de compradores salvo que Amazon publique un tipo de notificación que cubra explícitamente ese uso.

Messaging API tampoco sustituye a Solicitations API. Las solicitudes de reseñas y valoraciones siguen su propio flujo de Amazon y sus reglas de políticas.

Estructura del flujo

El flujo separa la selección de pedidos, el descubrimiento de acciones, la recopilación de contenido, la preparación de adjuntos y la entrega final en nueve pasos de implementación. Los pasos del 4 al 8 son condicionales en la práctica. Si el tipo de mensaje elegido no admite texto personalizado o adjuntos, la integración omite el trabajo no compatible y pasa a la operación de envío permitida.

Requisitos de integración

Acceso de la aplicación

Antes de realizar una solicitud de producción, la integración necesita:

• Un perfil de desarrollador SP-API aprobado
• Una aplicación de vendedor pública o privada registrada
• Autorización del socio vendedor
• El rol Buyer Communication en el perfil de desarrollador y la aplicación
• Un ID de cliente y secreto de cliente LWA
• Un token de actualización LWA
• Un ID de pedido de Amazon
• Un ID de marketplace
• El endpoint SP-API de la región de ventas objetivo

Una aplicación privada de vendedor puede autorizarse a sí misma para la organización propietaria. Una aplicación pública utiliza un flujo de autorización OAuth para que cada socio vendedor conceda acceso.

Rol Buyer Communication

El tutorial de envío de mensajes de Amazon exige que el rol Buyer Communication esté asignado al perfil de desarrollador y seleccionado en la configuración de registro de la aplicación. Un token LWA válido no compensa la ausencia del rol.

Si una solicitud devuelve 403, comprueba la autorización y la configuración de roles antes de cambiar el cuerpo. Confirma también que el token pertenece al socio vendedor asociado al pedido objetivo.

Modelo actual de autenticación

SP-API utiliza Login with Amazon, o LWA, para solicitudes autorizadas por vendedores. La aplicación intercambia su token de actualización por un token de acceso temporal:

curl --request POST \
  --url 'https://api.amazon.com/auth/o2/token' \
  --header 'content-type: application/x-www-form-urlencoded;charset=UTF-8' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=YOUR_REFRESH_TOKEN' \
  --data-urlencode 'client_id=YOUR_LWA_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_LWA_CLIENT_SECRET'

Amazon documenta una duración de una hora para el token de acceso LWA. Guárdalo en caché de forma segura, renuévalo antes de que caduque y nunca expongas el secreto del cliente ni el token de actualización en código del navegador, registros, repositorios públicos o capturas de soporte.

SP-API no requiere recursos de AWS IAM ni AWS Signature Version 4 desde el 2 de octubre de 2023. Las llamadas actuales siguen utilizando tokens de acceso LWA. Los tutoriales antiguos que exigen un usuario IAM, un ARN de rol o firma SigV4 añaden trabajo de configuración obsoleto.

Endpoints regionales

El endpoint debe coincidir con la región del marketplace objetivo:

Una solicitud también necesita el identificador del marketplace de la tienda donde se realizó el pedido. Por ejemplo, el ID del marketplace estadounidense es ATVPDKIKX0DER. Enviar un pedido al endpoint regional equivocado puede producir errores de autorización o recurso que parecen un ID de pedido incorrecto.

Flujo de integración de mensajería en 9 pasos

Paso 1: selecciona el pedido

Muestra los pedidos recientes sobre los que puede actuar el vendedor autorizado y asocia su selección con su amazonOrderId. La lista puede proceder de un flujo aprobado de Orders API o del propio almacén operativo autorizado de la aplicación.

Limita el acceso a los datos. Messaging API necesita el identificador del pedido y el contexto del marketplace. No exige recopilar datos del comprador sin relación. Si una operación independiente de Orders API devuelve información personal restringida, sigue los requisitos de Tokens API para ese recurso restringido.

Paso 2: descubre los tipos de mensajes

Llama a getMessagingActionsForOrder con el pedido seleccionado y un ID de marketplace:

curl --request GET \
  --url 'https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/ORDER_ID?marketplaceIds=ATVPDKIKX0DER' \
  --header 'accept: application/hal+json' \
  --header 'x-amz-access-token: YOUR_LWA_ACCESS_TOKEN' \
  --header 'x-amz-date: 20260819T120000Z' \
  --header 'user-agent: SellerMessagingApp/1.0 (Language=Python/3.12)'

Amazon devuelve las acciones disponibles para ese pedido. La respuesta utiliza JSON Hypertext Application Language. La aplicación debe examinar los esquemas y enlaces de las acciones, en lugar de mantener una lista estática de endpoints de mensajes.

Amazon documenta actualmente una tasa predeterminada de 1 solicitud por segundo con una ráfaga de 5 para getMessagingActionsForOrder. El límite real puede variar, por lo que debes leer x-amzn-RateLimit-Limit cuando Amazon lo devuelva.

Paso 3: selecciona el tipo de mensaje

Presenta solo los tipos de mensajes devueltos por Amazon. Guarda el título, esquema y href de la acción seleccionada. Esos valores determinan qué campos puede recopilar la aplicación y a qué operación puede llamar.

Este diseño guiado por la respuesta evita varios fallos:

• Mostrar un tipo de mensaje no disponible para el pedido
• Aceptar texto cuando la operación no tiene un campo de texto
• Aceptar adjuntos cuando no están admitidos
• Llamar a una ruta que no coincide con la acción seleccionada

Paso 4: recopila texto personalizado

Algunas acciones permiten un mensaje personalizado. Cuando el esquema incluye una propiedad de texto como rawMessageBody, valida la entrada del vendedor frente a las restricciones devueltas. Aplica los campos obligatorios, la longitud permitida y cualquier otra limitación antes de enviar.

La validación de esquema es necesaria, pero no suficiente. La aplicación también debe rechazar lenguaje promocional, solicitudes de reseñas prohibidas, información externa de contacto innecesaria y otros contenidos contrarios a las normas de comunicación entre compradores y vendedores de Amazon.

Si la acción no admite texto personalizado, no inventes un campo de texto. Continúa con las entradas compatibles.

Paso 5: recopila el adjunto

Algunos tipos de mensajes permiten adjuntos como instrucciones del producto, información de garantía, documentos legalmente obligatorios o facturas. Utiliza el esquema de la acción seleccionada para determinar si se permiten adjuntos y qué restricciones se aplican.

Valida como mínimo:

• Tipo de archivo y tipo de contenido
• Tamaño del archivo
• Nombre y extensión del archivo
• Finalidad comercial
• Resultado del análisis de malware
• Periodo de conservación

Si no se admiten adjuntos, omite los pasos del 6 al 8.

Paso 6: calcula Content-MD5

El flujo de carga de Amazon requiere un valor Content-MD5. Calcula el resumen MD5 de los bytes exactos del adjunto y después codifica el resumen binario en Base64. Una cadena MD5 hexadecimal no es el mismo valor.

import base64
import hashlib
from pathlib import Path

attachment = Path("warranty.pdf").read_bytes()
content_md5 = base64.b64encode(
    hashlib.md5(attachment).digest()
).decode("ascii")

print(content_md5)

Mantén los bytes originales sin cambios entre el cálculo del hash y la carga. Cualquier transformación posterior al cálculo puede hacer que la carga no supere la validación.

Paso 7: crea el destino de carga

Llama a la operación de Uploads API para el recurso de Messaging seleccionado. La ruta del recurso debe corresponder a la operación de mensaje que utilizará el adjunto. Proporciona el ID del marketplace, el valor Content-MD5 y el tipo de contenido.

La respuesta incluye:

• Una URL de carga prefirmada
• Cabeceras exigidas por el destino de carga
• Un uploadDestinationId

Guarda los tres. La URL y las cabeceras se utilizan para cargar el archivo. El ID de destino se referencia en la solicitud final de Messaging API.

Paso 8: carga el adjunto

Carga los bytes exactos del adjunto en la URL prefirmada con el método y las cabeceras que proporciona Amazon. Esta carga se dirige al almacenamiento de Amazon, por lo que no adjuntes el token LWA salvo que las instrucciones devueltas lo exijan explícitamente.

import requests

with open("warranty.pdf", "rb") as file_handle:
    upload_response = requests.put(
        PRESIGNED_URL,
        headers=UPLOAD_HEADERS,
        data=file_handle,
        timeout=60,
    )

upload_response.raise_for_status()

No llames a la operación de mensaje después de una carga de adjunto fallida o ambigua. Registra la respuesta de carga y reintenta de forma segura antes de construir el cuerpo final del mensaje.

Paso 9: envía el mensaje

Llama a la operación asociada a la acción elegida por el vendedor. Una solicitud de detalles de personalización puede parecerse a la siguiente, pero el esquema de acción devuelto para el pedido real sigue siendo la referencia autorizada:

curl --request POST \
  --url 'https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/ORDER_ID/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER' \
  --header 'content-type: application/json' \
  --header 'x-amz-access-token: YOUR_LWA_ACCESS_TOKEN' \
  --header 'x-amz-date: 20260819T120000Z' \
  --header 'user-agent: SellerMessagingApp/1.0 (Language=Python/3.12)' \
  --data '{
    "text": "Please confirm the spelling requested for this customized order.",
    "attachments": [
      {
        "uploadDestinationId": "UPLOAD_DESTINATION_ID",
        "fileName": "customization-example.pdf"
      }
    ]
  }'

Consulta la referencia de la operación para conocer su estado de éxito y contrato de respuesta. El tutorial de Amazon explica que Amazon envía el mensaje por correo electrónico al comprador; no promete una respuesta de negocio que confirme que lo ha leído.

Guarda el estado HTTP, x-amzn-RequestId, ID del pedido, ID del marketplace, acción seleccionada y marca temporal. No registres texto del mensaje ni contenido de adjuntos salvo que una necesidad operativa documentada lo justifique y los datos estén protegidos.

Patrones de solicitud y respuesta

Patrón de solicitud en Python

El ejemplo siguiente obtiene un token de acceso LWA y descubre las acciones de mensajes disponibles. Se detiene deliberadamente antes del envío para que la aplicación pueda mostrar y validar las opciones devueltas por Amazon.

import os
import requests

LWA_URL = "https://api.amazon.com/auth/o2/token"
SP_API_BASE = "https://sellingpartnerapi-na.amazon.com"

token_response = requests.post(
    LWA_URL,
    data={
        "grant_type": "refresh_token",
        "refresh_token": os.environ["SP_API_REFRESH_TOKEN"],
        "client_id": os.environ["LWA_CLIENT_ID"],
        "client_secret": os.environ["LWA_CLIENT_SECRET"],
    },
    timeout=30,
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

order_id = "ORDER_ID"
marketplace_id = "ATVPDKIKX0DER"

actions_response = requests.get(
    f"{SP_API_BASE}/messaging/v1/orders/{order_id}",
    params={"marketplaceIds": marketplace_id},
    headers={
        "accept": "application/hal+json",
        "x-amz-access-token": access_token,
        "user-agent": "SellerMessagingApp/1.0 (Language=Python/3.12)",
    },
    timeout=30,
)
actions_response.raise_for_status()
actions = actions_response.json()

El código de producción debe guardar el token en caché hasta poco antes de su caducidad, utilizar un cliente HTTP compartido, establecer tiempos de espera de conexión y lectura por separado y ocultar credenciales en los informes de excepciones.

Análisis de respuestas HAL

Los enlaces HAL permiten que Amazon indique al cliente qué puede ocurrir a continuación. Un analizador robusto debe admitir un pedido sin acciones disponibles y no suponer que _embedded contiene siempre los mismos campos.

Como mínimo, la aplicación debe:

• Confirmar que la respuesta es JSON válido
• Tratar una colección de acciones vacía como un resultado de negocio
• Vincular el esquema seleccionado al enlace seleccionado
• Rechazar entradas desconocidas u obligatorias ausentes
• Conservar la ruta y los parámetros de consulta exactos devueltos por Amazon

Secuencia de adjuntos

El proceso de adjuntos es condicional y secuencial:

Validate file
→ Calculate Content-MD5
→ Create upload destination
→ Upload exact bytes
→ Save uploadDestinationId
→ Send the permitted message

Trata el ID de destino como un valor efímero del flujo, no como un identificador reutilizable de recurso. Si cambian el pedido, la acción o el adjunto seleccionados, repite el descubrimiento de acciones y las comprobaciones de carga.

Cumplimiento, errores y límites

Normas de comunicación

Los mensajes a compradores de Amazon deben responder a una finalidad permitida relacionada con el pedido. Las promociones de marketing, cupones, enlaces externos innecesarios, intentos de influir en reseñas positivas y solicitudes de eliminar o modificar reseñas negativas pueden infringir las políticas y acuerdos de Amazon.

Los controles de cumplimiento deben ejecutarse antes de la llamada de envío:

• Permitir solo las acciones devueltas por Amazon
• Validar el contenido frente al esquema de la acción
• Señalar lenguaje promocional y lenguaje prohibido sobre reseñas
• Restringir los adjuntos a una finalidad documentada relacionada con el pedido
• Exigir revisión humana del contenido incierto
• Mantener un registro de auditoría sin exponer datos sensibles del mensaje

Los equipos que utilizan un agente propio del usuario para redactar respuestas deben mantener el envío final detrás de comprobaciones deterministas de políticas y, cuando corresponda, aprobación humana. El prompt del agente no anula la acción ni el esquema permitidos por Amazon.

Errores HTTP comunes

Una descripción de 403 puede mencionar varias causas posibles. Utiliza el ID de solicitud de Amazon, el cuerpo de respuesta, el contexto del token y la configuración de la aplicación para acotar la causa en lugar de adivinar.

Límites de solicitudes y reintentos

Utiliza x-amzn-RateLimit-Limit cuando esté disponible y coordina los límites entre los procesos que comparten la misma pareja vendedor-aplicación. Para respuestas 429 y 5xx transitorias, aplica esperas exponenciales con variación aleatoria.

El envío exige especial cuidado. Puede producirse un tiempo de espera de red después de que Amazon reciba la solicitud pero antes de que el cliente reciba la respuesta. Reintentar a ciegas un envío ambiguo puede crear mensajes duplicados al comprador. Una protección técnica puede retener esa solicitud para revisión, registrar internamente una clave de deduplicación y reintentar solo si la aplicación puede justificar que la primera solicitud no fue aceptada.

Este comportamiento de deduplicación es una recomendación para la aplicación, no una garantía de idempotencia proporcionada por Amazon.

Seguridad de credenciales

Amazon exige rotar los secretos de cliente LWA cada 180 días. Tras la rotación, el secreto anterior caduca siete días después. Un sistema de producción debe admitir credenciales solapadas durante esa transición y alertar con suficiente antelación al plazo.

Guarda los secretos de cliente y tokens de actualización en un gestor de secretos. Restringe el acceso por rol de servicio, cifra las copias de seguridad, oculta los datos sensibles de observabilidad y rota inmediatamente tras sospechar una exposición.

Pruebas y preparación para producción

Límites del sandbox estático

Amazon documenta Messaging API v1 con un sandbox estático. Sus respuestas utilizan coincidencias de patrones de solicitudes y datos simulados. Sirven para confirmar la gestión de autenticación, rutas, parámetros, análisis de respuestas y ramas de error.

Una llamada correcta al sandbox estático no demuestra que un pedido de producción vaya a ofrecer la misma acción de mensaje. La disponibilidad en producción depende del pedido real, vendedor, marketplace e historial de mensajes.

Lista de comprobación para producción

Antes de habilitar envíos reales, verifica:

• La autorización del vendedor está activa
• Buyer Communication está aprobado y seleccionado
• La renovación del token funciona sin intervención manual
• Los ID de marketplace se dirigen al endpoint regional correcto
• El descubrimiento de acciones se ejecuta antes de cada nuevo flujo de mensajes
• La validación del esquema bloquea entradas no compatibles
• Los errores de hash y carga de adjuntos detienen el envío
• La gestión de límites funciona entre procesos concurrentes
• Los registros ocultan tokens, texto, adjuntos y datos del comprador
• Los fallos ambiguos de envío no activan reintentos a ciegas
• Los controles de políticas y reglas de aprobación están activos
• Las alertas incluyen x-amzn-RequestId y contexto no sensible

Empieza con un tipo de mensaje acotado y una cuenta de vendedor controlada. Amplía solo cuando la evidencia de producción confirme que la autorización, seguimiento y controles de cumplimiento se comportan como se espera.

Seguimiento operativo

Supervisa fallos de renovación de tokens, errores de autorización 403, limitaciones 429, respuestas 5xx de Amazon, fallos de carga de adjuntos, tasas de éxito de operaciones de mensajes y plazos de rotación de credenciales.

Separa el éxito técnico de la entrega comercial. Una solicitud API aceptada significa que Amazon aceptó la operación según su contrato de respuesta. No demuestra que un comprador leyera el correo ni actuara en consecuencia.

Añade datos de comercio electrónico al conjunto de herramientas del vendedor

La mensajería con compradores es una parte de las operaciones del vendedor. El análisis de productos, competidores, palabras clave, reseñas, precios, ventas y tendencias suele estar en otras partes del sistema. Estos conjuntos de datos pueden orientar decisiones de productos y mercados, pero deben mantenerse separados de la autorización de mensajes y de los datos de comunicación privada.

Nexscope proporciona datos estructurados de comercio electrónico mediante una capa API independiente. Los equipos pueden conectar datos compatibles a su propio agente mediante REST API o MCP, o utilizar las mismas capacidades dentro del producto web de Nexscope. Una clave API de Nexscope no sustituye a las credenciales LWA de Amazon ni concede acceso a mensajes de compradores de Amazon.

Entre las capacidades relevantes están:

• Datos estructurados de productos y mercados de Amazon
• Señales de palabras clave, reseñas, competidores, precios, ventas y tendencias
• Acceso REST API y MCP para el propio agente y flujo del equipo
• Acceso web para equipos que prefieren trabajar dentro de Nexscope
• Límites visibles de fuente, actualización, estimación y datos ausentes cuando sean compatibles

Esta separación vincula cada credencial a su finalidad real: credenciales SP-API de Amazon para operaciones autorizadas de vendedores y credenciales Nexscope para acceder a datos compatibles de comercio electrónico. Los mismos datos pueden respaldar flujos basados en una Amazon Search API o API de scraping de Amazon seleccionadas cuidadosamente, sin presentarlos como datos de una cuenta de Seller Central.

Explora datos de Amazon más allá de la mensajería con compradores

Conecta datos estructurados de productos, competidores, palabras clave, reseñas, precios, ventas y mercados a aplicaciones de comercio electrónico o al propio agente del usuario mediante REST API o MCP.

Explora Amazon Data API →

Errores comunes de integración

Acciones de mensajes codificadas de forma fija

Llamar a un endpoint conocido sin descubrir primero las acciones disponibles para el pedido elude el diseño central de la API. Una acción que funcionó con un pedido puede no estar disponible para otro por condiciones de marketplace, logística, vendedor o mensajes previos. Llama siempre a getMessagingActionsForOrder y vincula el esquema seleccionado a la ruta de la acción elegida.

Configuración SigV4 heredada

Las integraciones nuevas a veces copian ejemplos antiguos que crean recursos de AWS IAM y firman cada solicitud SP-API. Amazon eliminó ese requisito en octubre de 2023. Conservar código obsoleto de firma aumenta el tiempo de configuración y crea riesgos de credenciales innecesarios. Utiliza el modelo actual de conexión LWA y las cabeceras SP-API obligatorias.

Reintentos de envío a ciegas

Un tiempo de espera agotado no demuestra que Amazon rechazara la solicitud de envío. Repetir automáticamente una solicitud ambigua puede duplicar un mensaje al comprador. Registra el contexto, aplica una protección interna de deduplicación y remite los envíos inciertos a revisión en lugar de tratarlos como una lectura idempotente.

Exceso de confianza en el sandbox

Las respuestas del sandbox estático son simuladas. Confirman la forma de la solicitud y el comportamiento del análisis, pero no reproducen las condiciones reales del pedido que controlan la disponibilidad de mensajes. El despliegue en producción debe comenzar con un tipo de mensaje acotado, una cuenta controlada, registros no sensibles y aprobación explícita de envíos reales.

Confusión de credenciales

Las credenciales LWA de Amazon autorizan operaciones de vendedores. Las credenciales Nexscope autorizan datos compatibles de comercio electrónico de Nexscope. Ninguna sustituye a la otra. Mantener separadas ambas rutas de datos y almacenes de secretos evita un comportamiento engañoso del producto y reduce el alcance de un incidente de credenciales.

Conclusión

Una integración fiable de Amazon Messaging API empieza con el modelo de acceso correcto y sigue guiándose por las acciones que Amazon devuelve para cada pedido. La aplicación obtiene un token de acceso LWA, selecciona un pedido, llama a getMessagingActionsForOrder, valida el esquema elegido, carga un adjunto cuando está permitido y llama a la operación de mensaje correspondiente.

La calidad de producción depende de lo que rodea a esas solicitudes. El acceso Buyer Communication, el enrutamiento regional, los controles de políticas, la gestión de secretos, los límites de solicitudes, los reintentos prudentes y el seguimiento no sensible deben funcionar antes de habilitar mensajes reales.

Amazon SP-API sigue siendo la autoridad para la autorización de vendedores y la mensajería con compradores. Nexscope proporciona una capa separada de datos de comercio electrónico para investigación y análisis mediante REST API, MCP o el producto web de Nexscope.

Preguntas frecuentes

¿Cuál es el nombre oficial de Amazon Seller Messages API?

Amazon denomina el servicio Messaging API v1, parte de Selling Partner API. «Amazon Seller Messages API» es una frase habitual de búsqueda, no el nombre formal del producto. La API permite a las aplicaciones de vendedores descubrir los tipos de mensajes disponibles para un pedido concreto y llamar a una operación que solicita un mensaje aprobado al comprador. Su referencia actual está orientada al envío y no documenta un endpoint general para descargar toda la bandeja de entrada de Seller Central ni todas las respuestas de compradores.

¿Cómo integro Amazon Seller Messages API?

Registra una aplicación de vendedor, obtén el rol Buyer Communication, completa la autorización del vendedor e intercambia el token de actualización LWA por uno de acceso. Selecciona un pedido y llama a getMessagingActionsForOrder con su ID y el del marketplace. Permite al vendedor elegir una de las acciones devueltas, valida el texto y los adjuntos frente a su esquema, completa el flujo de Uploads API cuando sea necesario y llama a la operación vinculada a esa acción. Añade controles de políticas, reintentos seguros, seguimiento y rotación de credenciales antes de utilizarla en producción.

¿Puede Amazon Messaging API leer las respuestas de compradores?

La documentación actual de Messaging API v1 describe el descubrimiento de acciones disponibles y el envío de mensajes permitidos relacionados con pedidos. No documenta una operación general para obtener toda la bandeja de mensajes entre compradores y vendedores ni su historial. Por ello, una aplicación debe evitar prometer sincronización de bandeja de entrada o incorporación automática de respuestas basándose solo en Messaging API. Cualquier flujo entrante necesita una capacidad independiente documentada por Amazon que admita explícitamente los datos necesarios. No debe suponerse que Notifications API proporciona mensajes de compradores sin un tipo de notificación publicado que coincida.

¿Qué rol requiere Amazon Messaging API?

La mayoría de las operaciones de Messaging API v1 requieren el rol Buyer Communication. El tutorial de envío de Amazon indica que el rol debe asignarse al perfil de desarrollador y seleccionarse en la página de registro de la aplicación. Algunas operaciones especializadas pueden incluir roles adicionales, por lo que la referencia actual de la operación sigue siendo la autoridad. Si una solicitud devuelve 403, verifica el rol del desarrollador, la selección de roles de la aplicación, autorización del vendedor, estado del token, vendedor objetivo y endpoint regional antes de cambiar el cuerpo.

¿Sigue requiriendo SP-API AWS Signature Version 4?

No. Amazon eliminó el requisito de recursos AWS IAM y AWS Signature Version 4 de SP-API el 2 de octubre de 2023. Las solicitudes actuales siguen utilizando tokens de acceso de Login with Amazon. Las aplicaciones siguen necesitando el endpoint SP-API adecuado y las cabeceras obligatorias, incluidas x-amz-access-token, x-amz-date y user-agent. Los ejemplos antiguos que crean un rol IAM o firman cada solicitud con SigV4 describen un modelo de conexión heredado y no deben ser la opción predeterminada para una integración nueva.

¿Por qué no hay acciones de mensajes disponibles para un pedido?

Una lista vacía puede ser un resultado de negocio válido. Amazon señala que la disponibilidad de mensajes puede depender del estado logístico, tipo de vendedor, marketplace y número de mensajes ya enviados para el pedido. Confirma que el pedido pertenece al vendedor autorizado, que el ID del marketplace es correcto, que el endpoint regional coincide con la tienda y que la aplicación tiene acceso Buyer Communication. No eludas la respuesta vacía llamando a un endpoint de envío fijo, porque esa acción quizá no esté permitida para el pedido.

¿Cómo funcionan los adjuntos en Amazon Messaging API?

Los adjuntos solo se admiten en los tipos de mensajes cuyo esquema devuelto los permite. La aplicación valida el archivo, calcula un valor Content-MD5 en Base64 y llama a Uploads API para crear un destino para el recurso Messaging correspondiente. Carga los bytes exactos en la URL prefirmada devuelta y guarda el uploadDestinationId. La solicitud final incluye ese ID y el nombre del archivo. Si fallan el hash, la creación del destino o la carga, la aplicación debe detenerse en lugar de enviar un mensaje con una referencia de adjunto inválida.

¿Puede probarse Amazon Messaging API en un sandbox?

Sí. Amazon incluye Messaging API v1 con un sandbox estático. Las llamadas devuelven respuestas simuladas según coincidencias de patrones de solicitudes, por lo que sirven para validar la construcción de solicitudes, el análisis de respuestas, la gestión de autenticación y las rutas de error. No reproducen toda la lógica de negocio de un pedido real. Por tanto, una respuesta correcta del sandbox no demuestra que el mismo tipo de mensaje esté disponible en producción. Las pruebas de producción deben empezar con un alcance limitado, cuentas autorizadas, seguimiento y controles explícitos de los envíos reales.

Fuentes

1. Amazon. (2026). Messaging API. Consultado en developer-docs.amazon.com
2. Amazon. (2026). Enviar un mensaje. Consultado en developer-docs.amazon.com
3. Amazon. (2026). getMessagingActionsForOrder. Consultado en developer-docs.amazon.com
4. Amazon. (2023). SP-API ya no requiere AWS IAM ni AWS Signature Version 4. Consultado en developer-docs.amazon.com
5. Amazon. (2026). Políticas y acuerdos de Selling Partner API. Consultado en developer-docs.amazon.com