Guía para la construcción de flujos de trabajo para la gestión de listados

Esta guía resume los pasos que puedes seguir para construir flujos de trabajo de creación y gestión de listados de primera clase al integrarte con la API de Selling Partner. Siguiendo los pasos recomendados, puedes minimizar la fricción que los selling partners pueden experimentar al crear y gestionar sus listados en Amazon.

Versiones de la API

Esta guía hace referencia a las operaciones en las siguientes secciones de la Selling Partner API. Para obtener información más detallada sobre las operaciones de API individuales enumeradas, siga los links a los que se hace referencia.

Terminología

• Catalog item : Representa un item en el catálogo de Amazon y se identifica de forma única mediante un ASIN (Amazon Standard Identification Number) definido por Amazon. Los datos de uno o más items de listados de selling partner se reconcilian en un solo item en el catálogo de Amazon y representan los datos del producto para un item vendido en Amazon.
• Listings item : representa un item (también conocido como listado) en un catálogo de selling partners que se identifica de manera única mediante un SKU (Unidad de mantenimiento de existencias) proporcionado por el selling partner y representa los datos del producto y los términos de venta de un item vendido o gestionado por Amazon.
• JSON Schema : JSON es el formato de serialización utilizado por las API, las notificaciones y los formatos de feed descritos en esta guía. JSON Schema es un vocabulario para anotar, describir y validar contenido JSON y lo utiliza la API de definiciones de tipo de producto para describir el modelo de datos para items de catálogo y items de listados. Consulte http://json-schema.org/learn/ para obtener más detalles sobre JSON Schema.
• JSON_LISTINGS_FEED : JSON_LISTINGS_FEED es un formato de feed masiva compatible por contrato con las API descritas en esta guía y es intercambiable con las operaciones individuales de la Listings Items API. Consulte Creación y actualización masiva de items de listados para obtener más información.
• Variation family : una familia de variantes es una colección de items similares que varían en color, tamaño u otros atributos que se utilizan para proporcionar una única experiencia de página de detalles a los compradores en Amazon. Por ejemplo, una prenda de vestir puede venir en varios colores, varios tamaños y varios estilos. Cada combinación única de color, tamaño y estilo está representada por un item separado en la familia de variantes.

Listing items en Amazon

La publicación de items en Amazon puede tomar múltiples formas, según su caso de uso específico. Los pasos que se describen aquí brindan ejemplos de cómo se pueden componer la API y los bloques de creación de notificaciones para los flujos de trabajo listings de uso común.

📘

Tipos de productos

Amazon está en proceso de migrar tipos de productos para habilitar su soporte en la Listings Items API y la Product Type Definitions API. Para los tipos de productos que aún no se han lanzado para estas API, puede crear nuevos items de listados solo de oferta, editar términos de venta para items de listados o eliminar items de listados. Sin embargo, no puede crear nuevos elementos de listados con datos de productos hasta que se inicie el tipo de producto adecuado en estas API. Puede usar la operación searchDefinitionsProductTypes y la notificación PRODUCT_TYPE_DEFINITIONS_CHANGE para mantenerse actualizado con los tipos de productos disponibles. Consulte la Guía de casos de uso de la Notifications API v1 para obtener información sobre cómo configurar un destino y crear suscripciones.

Suscríbete a las notificaciones de listados

Cada uno de los flujos de trabajo descritos aquí puede generar cambios de estado asincrónicos o problemas en los elementos de sus listados. Al suscribirse y monitorear las notificaciones LISTINGS_ITEM_STATUS_CHANGE y LISTINGS_ITEM_ISSUES_CHANGE , puede crear flujos de trabajo basados en eventos que reaccionan en tiempo real a medida que ocurren estos cambios. Consulte la Guía de casos de uso de la Notifications API v1 para obtener información sobre cómo configurar un destino y crear suscripciones.

Enumere un item que aún no existe en el catálogo de Amazon

El siguiente diagrama proporciona una descripción general de los pasos del flujo de trabajo para crear una lista de un item que aún no existe en el catálogo de Amazon.

flujo de trabajo para crear un nuevo elemento de listado

Siga estos pasos para identificar si un item existe en el catálogo de Amazon, recuperar los requisitos de datos para publicar un item nuevo, enviar un item nuevo y recibir las notificaciones generadas como resultado.

1. Llame a la operación searchCatalogItems para buscar items existentes en el catálogo de Amazon por identificadores de productos (UPC, EAN, etc.) o palabras clave. Si se encuentra una coincidencia exacta, use los pasos Anunciar una oferta para un item que ya existe en el catálogo de Amazon a continuación para crear un item de anuncios de solo oferta. Si no se encuentra una coincidencia exacta, continúe con el próximo paso.
2. Identifique el tipo de producto apropiado para su item. Puede hacer referencia al tipo de producto de items similares encontrados al buscar en el catálogo de Amazon en el paso anterior, consulte las Guías de Browse Tree disponibles en Seller Central o el Browse Tree Report disponible mediante la Reports API (consulte la Guía de casos de uso de la Reports API ), o llame a la operación searchDefinitionsProductTypes para buscar el tipo de producto que mejor se aplica a su item.
3. Llame a la operación getDefinitionsProductType para devolver el esquema JSON que describe los atributos y restricciones para el tipo de producto.

📘

Requisitos de listado

La lista de items en Amazon se puede hacer con o sin proporcionar detalles de la oferta (términos de venta) en el momento de la creación. Esto le permite crear items que se pueden comprar o adquirir en un solo envío o crear items inactivos con términos de venta proporcionados más adelante. Para listar un item con datos del producto y términos de venta, use el LISTING como el valor para el Parámetro requirements para recuperar un esquema JSON con atributos de producto y oferta. Para listar un item solo con datos del producto, use el LISTING_PRODUCT_ONLY como el valor para el Parámetro requirements para recuperar un esquema JSON solo con atributos de producto.

4. Prepare el envío de la lista con atributos que se adhieran al esquema JSON para el tipo de producto.

5. Verifique que los datos de la lista cumplan con los requisitos antes de enviarlos mediante las utilidades de validación del esquema JSON. Consulte el metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles sobre la validación de datos con los esquemas JSON de tipo de producto. Debe asegurarse de que se proporcionen los atributos necesarios, que todos los valores sean válidos, que se tengan en cuenta las reglas condicionales y que se cumplan todos los requisitos del esquema.

6. Llame a la operación putListingsItem para enviar el elemento de listados.

7. Inspeccione la respuesta para identificar si el estado del envío era ACCEPTED o INVALID . Si se acepta, las validaciones iniciales han pasado y los datos se han enviado para su posterior procesamiento con el catálogo de Amazon. Si no es válido, uno o más problemas de validación impidieron la aceptación; consulte Manejo de problemas de elementos de listados para obtener más información. Corrija los problemas de validación y vuelva a enviar.

8. Espere a que se envíen las notificaciones asincrónicas LISTINGS_ITEM_STATUS_CHANGE o LISTINGS_ITEM_ISSUES_CHANGE una vez que se haya creado el nuevo elemento o se hayan producido problemas de procesamiento. Llame a la operación getListingsItem para inspeccionar los problemas de elementos de listados, si corresponde.

   Debe suscribirse a las notificaciones mencionadas para recibirlas. Consulta Suscríbete a las notificaciones de listados para obtener más información.

Publique una oferta para un item que ya existe en el catálogo de Amazon

Los pasos de Enumerar un item que aún no existe en el catálogo de Amazon describieron la lista de un item que aún no existe en el catálogo de Amazon. Para los items que ya existen en el catálogo de Amazon, los sellers pueden elegir enumerar solo los detalles necesarios para que coincida con el item existente junto con los términos de venta aplicables.

📘

Anuncios de solo oferta

Tenga en cuenta que los listados de solo oferta no son compatibles con los vendors en este momento. Para todos los items, los vendors deben proporcionar los datos del producto y los términos de venta, tal como se describe en los pasos anteriores para Listar un item que aún no existe en el catálogo de Amazon .

El siguiente diagrama proporciona una descripción general de los pasos del flujo de trabajo para crear una lista de un item que ya existe en el catálogo de Amazon.

flujo de trabajo para enumerar un elemento ya existente

1. Llame a la operación searchCatalogItems para buscar items existentes en el catálogo de Amazon por identificadores de productos (UPC, EAN, etc.) o palabras clave. Si se encuentra una coincidencia exacta, continúe con el próximo paso. Si no se encuentra una coincidencia exacta, el item debe crearse como se describe en los pasos anteriores Listar un item que aún no existe en el catálogo de Amazon .
2. Llame a la operación getListingsRestrictions con el identificador ASIN para recuperar los requisitos de elegibilidad que deben cumplirse antes de publicar un item en la condición correspondiente.
3. Llame a la operación getDefinitionsProductType para devolver el esquema JSON que describe los atributos y las restricciones mediante el PRODUCT tipo de producto y LISTING_OFFER_ONLY como el valor para el parámetro requirements .

📘

Tipos de productos de Amazon

Los tipos de productos de Amazon son jerárquicos, con el PRODUCT tipo de producto como la raíz para todos los tipos de productos. Los términos de venta se definen en la raíz. PRODUCT tipo de producto, que debe usarse al listar items solo con términos de venta.

4. Preparar el envío del listado con atributos adheridos al Esquema JSON para el PRODUCT tipo de producto usando el ASIN o identificador de producto para el item encontrado al buscar en el catálogo de Amazon.

5. Verifique que los datos de la lista cumplan con los requisitos antes de enviarlos mediante las utilidades de validación del esquema JSON. Consulte el metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles sobre la validación de datos con los esquemas JSON de tipo de producto. Debe asegurarse de que se proporcionen los atributos necesarios, que todos los valores sean válidos, que se tengan en cuenta las reglas condicionales y que se cumplan todos los requisitos del esquema.

6. Llame a la operación putListingsItem para enviar el elemento de listados.

7. Inspeccione la respuesta para identificar si el estado del envío era ACCEPTED o INVALID . Si se acepta, las validaciones iniciales han pasado y los datos se han enviado para su posterior procesamiento con el catálogo de Amazon. Si no es válido, uno o más problemas de validación impidieron la aceptación; consulte Manejo de problemas de elementos de listados para obtener más información. Corrija los problemas de validación y vuelva a enviar.

8. Espere a que se envíen las notificaciones asincrónicas LISTINGS_ITEM_STATUS_CHANGE o LISTINGS_ITEM_ISSUES_CHANGE una vez que se haya creado el nuevo elemento o se hayan producido problemas de procesamiento. Llame a la operación getListingsItem para inspeccionar los problemas de elementos de listados, si corresponde.

   Debe suscribirse a las notificaciones mencionadas para recibirlas. Consulta Suscríbete a las notificaciones de listados para obtener más información.

Actualizar un item de listados

El siguiente diagrama proporciona una descripción general de los pasos del flujo de trabajo para actualizar un item de listados.

flujo de trabajo para actualizar un item de listados

Siga estos pasos para actualizar los atributos de un item de listados.

1. Identifique el SKU del selling partner que debe actualizarse.

2. Si necesita inspeccionar los atributos existentes, llame a la operación getListingsItem utilizando el SKU identificado. Asegúrese de incluir attributes y issues en la lista de valores para el parámetro includedData .

3. Llame a la operación getDefinitionsProductType para devolver el esquema JSON que describe los atributos y restricciones para el tipo de producto. Usar LISTING o LISTING_PRODUCT_ONLY para el parámetro requirements en función de los atributos que se actualizarán. Consulte los requisitos de listado anteriores para obtener más información.

4. Prepare el envío de la lista con atributos que se adhieran al esquema JSON para el tipo de producto. Valores no editables ("editable": false ) no se pueden modificar a partir de sus valores existentes.

5. Verifique que los datos de la lista cumplan con los requisitos antes de enviarlos mediante las utilidades de validación del esquema JSON. Consulte el metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles sobre la validación de datos con los esquemas JSON de tipo de producto. Debe asegurarse de que se proporcionen los atributos necesarios, que todos los valores sean válidos, que se tengan en cuenta las reglas condicionales y que se cumplan todos los requisitos del esquema.

6. Llame a la operación patchListingsItem o putListingsItem dependiendo de si desea realizar una actualización parcial o completa.

   Los selling partners pueden actualizar una lista al proporcionar los atributos individuales para actualizar usando el operación patchListingsItem (actualización parcial) o proporcionando todos los atributos de elementos de listados utilizando el Operación putListingsItem (actualización completa).

   Para los sellers, utilizando el La operación putListingsItem reemplazará los atributos de hechos de productos enviados anteriormente y combinará los atributos de términos de ventas enviados anteriormente. Por ejemplo, la omisión de un hecho de producto opcional resultará en su eliminación. Sin embargo, a la inversa, la omisión de un valor de precio de oferta adquirible no dará lugar a su eliminación. Los sellers pueden usar el patchListingsItem para agregar, reemplazar o eliminar uno o más valores de atributo.

   Para los vendors, utilizando el La operación putListingsItem combinará los atributos proporcionados con los atributos enviados previamente. La omisión de un atributo opcional no dará lugar a su eliminación. Los sellers pueden usar el patchListingsItem para agregar o reemplazar uno o más valores de atributo. Sin embargo, en este momento, los vendors no admiten la eliminación de valores de atributos individuales.

📘

Actualizaciones parciales vs. completas

Utilizar el Operación patchListingsItem para realizar actualizaciones parciales en una lista de productos. La ventaja de usar el La operación patchListingsItem es que solo necesita incluir los atributos que están cambiando (y son editables). Sin embargo, también es posible agregar, reemplazar o eliminar atributos usando el operación putListingsItem . Si elige usar la operación putListingsItem , debe completar previamente la carga útil de la solicitud con el resultado de la operación getListingsItem para todos los atributos de identificación (incluidos los atributos no editables) para evitar errores de envío. Básicamente, esto significa reemplazar los datos de atributo de todo el listado. Por esa razón, usando el La operación putListingsItem se adapta mejor a una actualización completa.

7. Inspeccione la respuesta para identificar si el estado del envío era ACCEPTED o INVALID . Si se acepta, las validaciones iniciales han pasado y los datos se han enviado para su posterior procesamiento con el catálogo de Amazon. Si no es válido, uno o más problemas de validación impidieron la aceptación; consulte Manejo de problemas de elementos de listados para obtener más información. Corrija los problemas de validación y vuelva a enviar.

8. Espere a que se envíen las notificaciones asincrónicas LISTINGS_ITEM_STATUS_CHANGE o LISTINGS_ITEM_ISSUES_CHANGE una vez que se haya creado el nuevo elemento o se hayan producido problemas de procesamiento. Llame a la operación getListingsItem para inspeccionar los problemas de elementos de listados, si corresponde.

   Debe suscribirse a las notificaciones mencionadas para recibirlas. Consulta Suscríbete a las notificaciones de listados para obtener más información.

Eliminación de un item de listados

Consulte Tutorial: Eliminar una lista en la Guía de casos de uso de elementos de listas para obtener más información sobre cómo eliminar una lista.

Creación y actualización de elementos de listados de forma masiva

Los flujos de trabajo enumerados anteriormente para crear, actualizar y eliminar elementos de listados operan en elementos individuales uno a la vez. Para flujos de trabajo e gran volumen donde se prefieren los mecanismos de envío masivo, también puede usar el tipo de feed JSON_LISTINGS_FEED con la Feeds API .

El siguiente diagrama proporciona una descripción general de los pasos del flujo de trabajo para crear y actualizar elementos de listas de forma masiva.

flujo de trabajo de elementos de listados masivos

El tipo de feed JSON_LISTINGS_FEED es compatible contractualmente con la Listings Items API y los atributos en los mensajes de feed siguen los mismos esquemas de definición de tipo de producto proporcionados por la operación getDefinitionsProductType . Estos envíos de feeds pondrán en cola su envío masivo y luego invocarán la Listings Items API en su nombre. Una vez completado, el informe de procesamiento de feeds incluirá cualquier comentario de validación proporcionado por la Listings Items API.

Consulte flujo de trabajo para enviar un feed para obtener detalles sobre cómo enviar un feed y consulte el esquema JSON_LISTINGS_FEED para conocer el esquema del tipo de feed.

¿Debo enviar de forma masiva con JSON_LISTINGS_FEED o de forma individual con la Listings Items API?

📘

Mejora el rendimiento de tus envíos

Ya sea que envíe datos de forma masiva con JSON_LISTINGS_FEED, individualmente con la Listings Items API o una combinación de ambos, sus tiempos de procesamiento generales se ven afectados por el volumen de datos que envía. El envío repetido de datos duplicados aumenta innecesariamente los retrasos en el procesamiento y da como resultado tiempos de procesamiento más prolongados, como volver a enviar todos los listados para un seller en un envío de feed cuando solo cambió un item. Al enviar datos solo para items que tienen cambios materiales, utilizará la capacidad disponible de manera más eficiente y reducirá los retrasos en el procesamiento.

Puede utilizar los mismos datos cuando los envía individualmente a la Listings Items API o de forma masiva con JSON_LISTINGS_FEED . Ya sea que use las operaciones de Listings Items API individuales, envíe de forma masiva con JSON_LISTINGS_FEED o use una combinación de ambos, depende de usted, su caso de uso y sus preferencias. Puede optar por usar JSON_LISTINGS_FEED para realizar una carga inicial de sus datos en Amazon y pasar a usar las Listings Items API para mantener esos datos a lo largo del tiempo. Puede optar por utilizar exclusivamente JSON_LISTINGS_FEED para realizar sincronizaciones diarias de cambios en Amazon. O puede optar por utilizar exclusivamente la Listings Items API para recibir comentarios de validación sincrónicos a medida que envía sus datos, un elemento a la vez.

La siguiente tabla compara la Listings Items API y las funciones JSON_LISTINGS_FEED para ayudarlo a decidir cuál usar en sus flujos de trabajo:

Manejo de problemas de elementos de listados

Pueden ocurrir problemas en los elementos de los listados durante el envío o durante el procesamiento asíncrono después de la aceptación. Estos problemas están disponibles a través de los siguientes mecanismos:

1. Para los problemas que ocurren durante los envíos sincrónicos a la Listings Items API, las respuestas contienen la lista de problemas que impidieron la aceptación del envío. Para la lista de problemas proporcionada, tome medidas correctivas y vuelva a enviar.
2. Para los problemas que ocurren durante la ingesta asíncrona de envíos JSON_LISTINGS_FEED a las Listings Items API, el informe de procesamiento de feeds contiene la lista de problemas que impidieron la aceptación de los envíos. Para la lista de problemas proporcionada, tome medidas correctivas y vuelva a enviar.
3. Para problemas que ocurren después de la aceptación de envíos a la Listings Items API o JSON_LISTINGS_FEED, la operación getListingsItem proporciona la lista de problemas cuando el El parámetro de solicitud includedData incluye issues Además, si está suscrito a la notificación LISTINGS_ITEM_ISSUES_CHANGE , se enviará una notificación casi en tiempo real a medida que se registran los problemas. Esto le permite crear un manejo de respuestas basado en eventos para recuperar más detalles del getListingsItem una vez que se han producido problemas en lugar de sondear repetidamente la operación.

Envío de imágenes para items de listados

Los atributos relacionados con la imagen se incluyen en los esquemas de productos devueltos por la operación getDefinitionsProductType (por ejemplo, main_offer_image_locator , other_offer_image_locator_1 ).

Se puede cargar una imagen de producto principal y hasta 9 imágenes secundarias utilizando la Listings Items API llamando a las operaciones putListingsItem o patchListingsItem y proporcionando las URL de las imágenes.

Las imágenes asociadas con un ASIN o SKU se pueden recuperar mediante las operaciones getCatalogItem y getListingsItem respectivamente.

Para obtener más información, consulte Envío de imágenes y otros atributos de medios .

Configuración de elementos de listados relacionados (variaciones, jerarquías de paquetes)

Los elementos de los listados se pueden relacionar entre sí para crear familias de variantes o jerarquías de paquetes. Los esquemas de definición de tipo de producto proporcionados por la operación getDefinitionsProductType describen los atributos aplicables para definir relaciones, como parentage_level y variation_theme .

Configuración de familias de variantes

Una familia de variaciones representa una colección de items para un producto que se vende en múltiples variedades. Por ejemplo, una prenda de vestir puede venir en varios tamaños y colores. Cada combinación única de tamaño y color está representada por un item de listado separado y agrupado por un item de listado principal para proporcionar una única experiencia de página de detalles. Siga estos pasos para configurar una familia de variantes para los tipos de productos admitidos:

1. Siga los pasos anteriores para enumerar un item que aún no existe en el catálogo de Amazon para crear el item principal de las listas con el parentage_level valor establecido en parent
2. Para cada combinación única de atributos de familia de variantes, siga los pasos anteriores para Enumerar un elemento que aún no existe en el catálogo de Amazon para crear los elementos de listados secundarios con el parentage_level valor establecido en child y haciendo referencia al identificador de SKU del elemento de listado principal.

3. 📘

   Soporte para configurar familias de variantes

   En este momento, los vendors no admiten la configuración de familias de variantes con la Listings Items API.

Configuración de jerarquías de paquetes

Una package hierarchy representa una colección de items para un producto que se vende como unidades individuales, en cajas y en paquetes de cajas (es decir, tarimas). Por ejemplo, una bebida consumible se puede vender como una botella individual, una caja de 6 botellas y una paleta que contiene 12 cajas. Siga estos pasos para configurar una package hierarchy para los tipos de productos admitidos:

1. Siga los pasos anteriores para Enumerar un item que aún no existe en el catálogo de Amazon para crear el item que representa la unidad vendible individual con los atributos de jerarquía de paquete provistos.
2. Siga los pasos anteriores para enumerar un item que aún no existe en el catálogo de Amazon para crear el item que representa el estuche (también conocido como paquete interno) que contiene la unidad individual y hace referencia al identificador SKU de la unidad individual.
3. Siga los pasos anteriores para Enumerar un item que aún no existe en el catálogo de Amazon para crear el item que representa el palé (también conocido como caja) que contiene la caja (paquete interior) y hace referencia al identificador SKU de la caja (paquete interior).

📘

Soporte para configurar jerarquías de paquetes

La configuración de jerarquías de paquetes con la Listings Items API no es compatible con los sellers en este momento.

Al crear jerarquías de paquetes, tenga en cuenta lo siguiente:

• Los atributos de dimensión del paquete de items deben ser diferentes en la jerarquía del paquete. Estos atributos representan las dimensiones reales del paquete cuando se envía a los compradores.
• El enfoque recomendado para la El valor item_name para los items listados de caja (paquete interno) y palé (paquete de caja) es agregar los detalles del paquete al item_name valor utilizado para la unidad individual. Por ejemplo, Pep 12oz Bottle , Pep 12oz Bottle (Case of 6) , y Pep 12oz Bottle (Pallet of 72) .
• Cada item en la jerarquía del paquete debe contener un identificador de producto externo único para poder venderlo a los compradores. Para las jerarquías de paquetes que usan un identificador de producto externo común para cada item, solo uno de los items estará disponible para la venta a los compradores.