Amazon SP-API notificaciones de pedidos: así se entera una app de que has vendido

Qué es la Selling Partner API y qué vino a sustituir

Toda herramienta seria que toca tu cuenta de Amazon, desde un repricer hasta la exportación contable o una app de avisos de pedido, habla con el mismo sitio: la Selling Partner API, abreviada como SP-API. Una aplicación solo ve lo que tú le has autorizado a ver.

Además es reciente. Su antecesora se llamaba Amazon Marketplace Web Service, MWS para abreviar. Amazon anunció su final en el foro de vendedores: "SP-API will fully replace MWS, and we are migrating developers to SP-API as we work to deprecate MWS", o sea, la SP-API sustituye por completo a MWS. Y con fecha firme: MWS "will no longer be available after March 31, 2024". Si un tutorial antiguo te explica cómo generar claves MWS, está describiendo un sistema que ya no existe.

La API de Amazon Seller Central no es una sola

Mucha gente busca "API Amazon Seller Central" como si fuera una única interfaz. Es una familia: una Orders API para pedidos, una Sales API para totales diarios, una Reports API para los informes que también descargas a mano, una Notifications API para mensajes push y una Finances API para transacciones. Una app de avisos usa tres como mucho.

La SP-API también está separada por regiones. Europa, Norteamérica y Extremo Oriente son puntos de acceso distintos con autorizaciones distintas. Por eso una app te pide conectar una vez para Europa y otra para Norteamérica si vendes en amazon.es y en amazon.com.mx a la vez. Esa es la razón técnica detrás de la estructura de cuentas que explicamos en vender en varios marketplaces de Amazon.

Qué concedes cuando conectas una app

Dar acceso no es dar una contraseña. Acabas en una página de consentimiento del propio Amazon, ves qué roles pide la app y pulsas Confirm. Tus datos de acceso nunca pasan por la aplicación.

Los roles son la parte que conviene leer. Amazon describe así el que necesita una app de pedidos: "The Inventory and Order Tracking role provides access to operations that analyze and manage inventory." Cubre leer pedidos y suscribirse a ORDER_CHANGE. Los roles que muestran nombres y direcciones de compradores son una categoría restringida aparte, con una revisión mucho más dura, y una app de avisos no tiene motivo para pedirlos.

Dos datos que los vendedores oyen poco. La autorización no es para siempre: Amazon indica que "the selling partner must reauthorize your public application every 365 days, or anytime you add a role to your application", así que se renueva cada año. Y puedes cortarla en un minuto en Seller Central, en Apps and Services, Manage Your Apps. El recorrido completo está en cómo conectar una app a Seller Central con seguridad.

ORDER_CHANGE: el mensaje y la cola que hay detrás

La Notifications API de Amazon tiene alrededor de dos docenas de tipos de notificación. El que cuenta para pedidos es ORDER_CHANGE: "The ORDER_CHANGE notification is sent whenever there is an important change in the order. Important changes include order status changes and buyer requested cancelations." En español: el mensaje sale ante cualquier cambio importante, incluidos los cambios de estado y las solicitudes de cancelación del comprador. Existe un tipo anterior, ORDER_STATUS_CHANGE, pero el propio tutorial de Amazon lo da por "deprecated" y remite a ORDER_CHANGE.

En la entrega es donde casi todo el mundo se equivoca. Para este tipo, Amazon no envía nada a una dirección webhook que tú elijas. Amazon escribe en una cola Amazon SQS, una cola de mensajes que el desarrollador crea en su propia cuenta de nube y sobre la que da permiso de escritura a Amazon. La página de configuración de Amazon incluye ORDER_CHANGE entre los tipos que se entregan así, y añade una restricción que dice mucho del diseño: "Selling Partner API does not support delivery to FIFO queues. You must use Amazon SQS standard queues to receive notifications."

Una cola estándar puede entregar un mensaje más de una vez y en desorden. Es normal, y por eso una app cuidadosa guarda el identificador de cada notificación que ya ha procesado. Cuando una app suena dos veces por la misma venta, el fallo suele estar justo aquí.

Qué contiene el mensaje y qué se deja fuera

El mensaje es corto y está construido alrededor del pedido, no del artículo. Amazon lo dice sin rodeos: "If you have multiple order items in the order, you will receive consolidated payloads at the order level." Un pedido con cuatro productos es un mensaje con cuatro líneas dentro, no cuatro avisos.

Falta justo lo que más te interesa: no hay importe del pedido, ni precio por unidad, ni ASIN, ni título de producto. Los solutions architects de Amazon presentan ORDER_CHANGE como un disparador para ir a buscar el pedido completo a la Orders API, no como un sustituto. Así que una app que te enseña un importe ha hecho una segunda llamada.

Y esa segunda llamada tiene un límite en los primeros minutos. Amazon define Pending como "The order has been placed but payment has not been authorized", el pago aún no está autorizado. Mientras dura, "the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions". Pending suele durar media hora, porque "the fulfillable date of an order is usually 30 minutes after the order has been created". Cualquier importe de los primeros minutos es, por tanto, una estimación. El nuestro se muestra con un "≈" y se corrige en silencio en cuanto Amazon publica la cifra real, por los motivos que explicamos en qué significa un pedido pendiente para un vendedor.

Un campo merece nota aparte: el mensaje incluye el código postal de destino, y la Data Protection Policy de Amazon cuenta el código postal como dato personal. Una app que no quiere datos del comprador en sus servidores tira ese campo antes de guardar nada. La nuestra lo hace.

Por qué los pedidos FBA se quedan mudos en Pending

Esta es la parte que no está en la documentación, porque solo la encontramos midiendo sobre nuestra propia cuenta de vendedor.

Si el push es tu único canal, un vendedor FBA se entera de la venta cuando el pago queda autorizado, que en nuestra cuenta fue horas después del clic del comprador, no segundos. Por eso trabajamos con tres capas, y en el orden contrario al que sugieren casi todos los esquemas de arquitectura.

La tercera capa no es idea nuestra. La pide Amazon: "As a best practice, we recommend that you have a means to retrieve needed information in the event of an unexpected outage or delay in notification delivery." Una app sin red de seguridad acabará perdiendo un pedido sin decírtelo nunca. Cómo se suman las capas en tiempo real lo contamos en a qué velocidad puede llegar de verdad un aviso de pedido de Amazon.

Qué significa esto al elegir una app

No hace falta leer una línea de código para juzgar una app de avisos. Cuatro preguntas separan a las cuidadosas del resto.

1. ¿Qué capas usa? Solo push es lo más barato de construir y justo lo que se calla con los pedidos FBA en Pending. Pregunta si además consulta la API y cada cuánto.
2. ¿Cuenta lo que se le ha escapado? Una red de seguridad solo sirve si el resultado se ve. Nuestra app muestra un contador de pedidos perdidos con objetivo cero, y cada aviso indica cuánto tardó en llegar.
3. ¿Qué roles pide? Los ves en la página de consentimiento antes de confirmar. Con un rol de solo lectura basta. Que una app de avisos pida direcciones de compradores es motivo para parar.
4. ¿Qué guarda? El mensaje trae un código postal y Amazon lo trata como dato del comprador. Pregunta si se descarta y con qué rapidez desaparece todo cuando desconectas.

Si todavía dudas si necesitas una app de terceros, empieza por qué envía y qué no envía la app oficial de Amazon Seller.