Versión API: 2021-08-01

¿Qué es la Listings Items API?

Con la Selling Partner API para elementos de listados (Listings Items API), puede crear, editar, eliminar y recuperar detalles sobre los listados de Amazon (SKU) para un selling partner. Esto incluye datos del producto, como títulos de items y términos de venta, como precio e inventario. Consulte la Referencia de la Listings Items API para obtener detalles sobre las operaciones de la Listings Items API y los tipos de datos y esquemas asociados.

Los datos de listados enviados a la Listings Items API se adhieren al formato de esquema JSON proporcionado por la Selling Partner API para Product Type Definitions API. Consulte la documentación de la API de definiciones de tipos de productos para obtener detalles sobre cómo recuperar esquemas para los tipos de productos de Amazon admitidos y validar los datos antes de enviarlos a Amazon con la Listings Items API.

Características clave

• Recuperar detalles sobre listados : la Listings Items API acepta Operaciones GET para devolver información detallada sobre un listado existente.
• Crear o actualizar listados por completo : la API de items de listados acepta Operaciones PUT para crear una nueva lista o reemplazar completamente los datos de una lista existente.
• Actualizar listados parcialmente : la Listings Items API acepta PATCH operaciones para actualizar uno o más atributos individuales para una lista existente, como para actualizar el precio y la cantidad. Además, la Listings Items API acepta PATCH operaciones para eliminar uno o más atributos individuales para una lista existente.
• Eliminar listados : la Listings Items API acepta Operaciones DELETE para eliminar un listado existente.
• Mensajes de problemas localizados : la Listings Items API proporciona mensajes de problemas localizados en la configuración regional especificada por la aplicación que llama o en la configuración regional predeterminada del marketplace de Amazon.
• Validación de envío : la API de elementos de listado proporciona la validación de los datos de envío antes de aceptar un envío para su procesamiento. Los errores de validación que impiden un procesamiento posterior se proporcionan sincrónicamente a la aplicación que realiza la llamada.

Terminología

• Listing : un listado de Amazon es un item que un selling partner ha puesto a la venta en Amazon y está identificado por una stock keeping unit (SKU). Los datos de los productos incluidos en los listados de Amazon se concilian en los items del catálogo de Amazon, que se identifican mediante números de identificación estándar de Amazon (ASIN).
• Full Update : una actualización completa de una lista de Amazon da como resultado una validación completa de los requisitos de datos en los datos enviados y crea una nueva lista o reemplaza los datos de una lista existente.
• Partial Update : una actualización parcial de una lista de Amazon da como resultado una validación parcial de los requisitos de datos para los atributos proporcionados y actualiza uno o más atributos para una lista existente.
• Product Type : un tipo de producto de Amazon es una categorización jerárquica de items en el catálogo de Amazon. Los requisitos de datos del item están vinculados al tipo de producto asociado del item.

Consideraciones

• Actualizaciones 1x1 : la Listings Items API acepta actualizaciones de listados una a la vez. Para casos de uso más adecuados para cargas masivas, el El tipo de feed JSON_LISTINGS_FEED se puede usar con la Selling Partner API para feeds. El JSON_LISTINGS_FEED es el equivalente masivo de la Listings Items API, que ofrece las mismas características y esquemas proporcionados por la Selling Partner API para Product Type Definitions API.
• Tipos de productos totalmente compatibles : la Listings Items API aún no es totalmente compatible con todos los tipos de productos de Amazon. Los tipos de productos de Amazon admitidos difieren según el tipo de selling partner (comerciante o vendor) y según el marketplace de Amazon. Consulte la Selling Partner API para ver las definiciones de tipos de productos para conocer los últimos tipos de productos de Amazon disponibles.
• Tipos de productos parcialmente admitidos : para los tipos de productos de Amazon que aún no son totalmente compatibles con la Listings Items API, los envíos de solo ofertas para los ASIN existentes y las actualizaciones parciales son compatibles mediante el uso de PRODUCT tipo de producto.
• Resultados y problemas : respuestas de los items de listados putListingsItem , patchListingsItem y Las operaciones deleteListingsItem indican si el envío se aceptó o no para su procesamiento, junto con cualquier problema que impida que se acepte el envío. Las respuestas no incluyen los problemas que ocurren después de aceptar el envío para su procesamiento. Respuestas a los items de los listados La operación getListingsItem puede incluir problemas que ocurren después de que se haya procesado el envío.

🚧

Manejo de esquemas JSON genéricos en bibliotecas cliente

Si ha generado una biblioteca de cliente, es importante tener en cuenta que Swagger Codegen genera tipos en función de las propiedades definidas en los modelos de Swagger, y que Swagger Codegen producirá tipos vacíos o incompletos cuando un objeto se define con additionalProperties: true . Para manipular tales objetos, utilice el --import-mappings parámetro de línea de comandos para asignar estos objetos a un tipo de objeto JSON genérico o un tipo de objeto personalizado de su elección.

Ejemplo de parámetros de entrada de Swagger Codegen:

C#: --import-mappings ItemAttributes=Newtonsoft.Json.Linq.JObject
Java: --import-mappings ItemAttributes=com.google.gson.JsonObject

Tutorial: Recuperar detalles sobre un listado

Use este tutorial para obtener información detallada sobre una lista de Amazon para un selling partner y un marketplace de Amazon determinados. Los detalles devueltos pueden incluir una serie de conjuntos de datos opcionales que brindan información importante sobre el estado del listado.

Importante : El nuevo LISTINGS_ITEM_ISSUES_CHANGE y Las notificaciones LISTINGS_ITEM_STATUS_CHANGE mencionadas en los siguientes párrafos solo están disponibles para los sellers en este momento.

Por ejemplo, si se ha suscrito para recibir el LISTINGS_ITEM_ISSUES_CHANGE mediante la Selling Partner API para notificaciones (Notifications API) y recibe la notificación, puede llamar al getListingsItem de la Listings Items API para obtener más detalles. El La notificación LISTINGS_ITEM_ISSUES_CHANGE no incluye el mismo nivel de información detallada sobre problemas que la API. Para devolver información más detallada, llame al getListingsItem y especificar issues en el Parámetro includedData para obtener el conjunto de datos de problemas.

Del mismo modo, si se suscribe a la LISTINGS_ITEM_STATUS_CHANGE mediante la Notifications API y recibe la notificación, puede llamar al operación getListingsItem para recibir información más detallada. Por ejemplo, si un listado deja de ser DESCUBIERTO como se indica en la notificación, es posible que desee obtener el conjunto de datos de problemas para ver el motivo de la supresión de la búsqueda.

Para otro ejemplo, si el La notificación LISTINGS_ITEM_STATUS_CHANGE no indica que el listado se pueda comprar (es decir, el estado no incluye COMPRABLE), una razón común podría ser la falta de inventario. En ese caso, llame al operación getListingsItem e incluir fulfillmentAvailability en el Parámetro includedData para devolver el conjunto de datos de disponibilidad de cumplimiento.

En general, los conjuntos de datos disponibles a través de la El parámetro includedData lo ayudará a comprender mejor el estado de la lista. Los conjuntos de datos disponibles incluyen información de resumen, atributos aportados, problemas, información de oferta (sellers), disponibilidad de cumplimiento (sellers) y detalles de adquisición (vendors).

requisitos previos

Para completar este tutorial, necesitará:

• Autorización del selling partner para el que está haciendo llamadas. Consulte la Guía para desarrolladores de la Selling Partner API para obtener más información.
• Aprobación para el rol de Listado de productos en su perfil de desarrollador.
• El rol de Listado de productos seleccionado en la página de registro de la aplicación para su aplicación.

Paso 1: Envíe la solicitud de obtención de items de listados

Llame a la operación getListingsItem para devolver detalles sobre un item de listados, pasando los siguientes parámetros:

Parámetros de solicitud

Parámetros de ruta

Parámetros de Query

Solicitud de ejemplo

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/50-TS3D-QEPT
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=issues,attributes,summaries,offers,fulfillmentAvailability

Respuesta

Una respuesta exitosa incluye uno o más de los siguientes:

Respuesta de ejemplo

Respuesta de ejemplo para un seller (comerciante) que incluye los conjuntos de datos, summaries, attributes, issues, offers y fulfillmentAvailability.

{
  "sku": "50-TS3D-QEPT",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B08YRD1CNN",
      "productType": "DRINKING_CUP",
      "conditionType": "new_new",
      "status": [
        "BUYABLE",
        "DISCOVERABLE"
      ],
      "itemName": "6 Pack Coffee Mug Set, Farielyn-X 16 Ounce Ceramic Coffee Cups, Black Large Coffee mugs, Restaurant Coffee Cups for Coffee, Tea, Cappuccino, Cocoa, Cereal, Matte Black Outside and Colorful Inside",
      "createdDate": "2021-07-14T19:57:02.327Z",
      "lastUpdatedDate": "2021-07-14T19:57:10.637Z",
      "mainImage":
      {
        "link": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
        "height": 500,
        "width": 500
      }
    }
  ],
  "attributes":
  {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_shipping_group": [
      {
        "value": "legacy-template-id",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "B08YRD1CNN",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "purchasable_offer": [
      {
        "currency": "USD",
        "start_at":
        {
          "value": "2021-07-14T19:56:57.717Z"
        },
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 30.0
              }
            ]
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "fulfillment_availability": [
      {
        "fulfillment_channel_code": "DEFAULT",
        "quantity": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxx1.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_1": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx2.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_2": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx3.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "issues": [
    {
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeName": "item_diameter",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ]
    },
    {
      "message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
      "severity": "WARNING",
      "attributeName": "color",
      "attributeNames": [
        "color",
        "item_dimensions",
        "item_weight"
      ]
    }
  ],
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2C",
      "price":
      {
        "currency": "USD",
        "amount": "30.0"
      }
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 1
    }
  ]
}

Ejemplo de solicitud y respuesta para un vendor que incluye conjuntos de datos de summaries, procurement y issues.

Solicitud de ejemplo

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=summaries,procurement,issues

Respuesta de ejemplo

{
  "sku": "example-sku",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "status": [
        "DISCOVERABLE"
      ],
      "itemName": "Hardside Carry-On Spinner Suitcase Luggage",
      "createdDate": "2021-02-01T00:00:00Z",
      "lastUpdatedDate": "2021-03-01T00:00:00Z",
      "mainImage":
      {
        "link": "https://www.example.com/luggage.png",
        "height": 500,
        "width": 500
      }
    }
  ],
  "procurement": [
    {
      "costPrice":
      {
        "currencyCode": "USD",
        "amount": "100.00"
      }
    }
  ],
  "issues": [
    {
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeName": "item_diameter",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ]
    },
    {
      "message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
      "severity": "WARNING",
      "attributeName": "color",
      "attributeNames": [
        "color",
        "item_dimensions",
        "item_weight"
      ]
    }
  ]
}

Tutorial: Crear o actualizar completamente una lista

Use este tutorial para crear o actualizar completamente una lista de Amazon para un selling partner y un marketplace de Amazon determinados.

requisitos previos

Para completar este tutorial, necesitará:

• Autorización del selling partner para el que está haciendo llamadas. Consulte la Guía para desarrolladores de la Selling Partner API para obtener más información.
• Aprobación para el rol de Listado de productos en su perfil de desarrollador.
• El rol de Listado de productos seleccionado en la página de registro de la aplicación para su aplicación.
• Una carga útil de lista basada en JSON que se adhiere al esquema JSON proporcionado por la Selling Partner API para Product Type Definitions API para el selling partner, el marketplace de Amazon y el tipo de producto de Amazon determinados.

Paso 1. Enviar solicitud de venta de elementos de listados

Llame a la operación putListingsItem para crear o actualizar completamente una lista, pasando los siguientes parámetros:

Parámetros de solicitud

Parámetros de ruta

Parámetros de Query

Parámetro del Body

Solicitud de ejemplo

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
    ?marketplaceIds=ATVPDKIKX0DER
    &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ...
  }
}

Respuesta

Una respuesta exitosa incluye lo siguiente:

Respuesta de ejemplo

{
  "sku": "ABC123",
  "status": "INVALID",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": [
    {
      "code": "90220",
      "message": "'product_description' is required but not supplied.",
      "severity": "ERROR",
      "attributeNames": [
        "product_description"
      ]
    }
    ...
  ]
}

Tutorial: actualizar parcialmente un listado

Use este tutorial para actualizar parcialmente una lista de Amazon para un selling partner determinado y el marketplace de Amazon usando la API de elementos de listas.

Las actualizaciones parciales se envían en forma de documentos JSON Patch. Consulte https://tools.ietf.org/html/rfc6902 para obtener más detalles sobre los documentos JSON Patch. Para los listados de Amazon, los documentos JSON Patch pueden agregar, reemplazar o eliminar atributos completos. No se admite la aplicación de parches al contenido dentro de los atributos.

requisitos previos

Para completar este tutorial, necesitará:

• Autorización del selling partner para el que está haciendo llamadas. Consulte la Guía para desarrolladores de la Selling Partner API para obtener más información.
• Aprobación para el rol de Listado de productos en su perfil de desarrollador.
• El rol de Listado de productos seleccionado en la página de registro de la aplicación para su aplicación.
• Para las actualizaciones de atributos, las cargas útiles de atributos de listas basadas en JSON se adhieren al esquema JSON proporcionado por la Selling Partner API para Product Type Definitions API para el selling partner, el marketplace de Amazon, el tipo de producto de Amazon y los atributos.
• Para las eliminaciones de atributos, las cargas útiles de atributos de listas basadas en JSON se adhieren al esquema JSON proporcionado por la Selling Partner API para Product Type Definitions API para el selling partner, el marketplace de Amazon, el tipo de producto de Amazon y los atributos con las propiedades del selector de los atributos que se eliminarán. Los atributos no se pueden eliminar solo por nombre, los valores del selector identifican qué instancia de atributos eliminar.

Paso 1. Enviar solicitud de parche de item de listados

Llame a la operación patchListingsItem para actualizar parcialmente una lista, pasando los siguientes parámetros:

Parámetros de solicitud

Parámetros de ruta

Parámetros de Query

Parámetro del Body

Solicitud de ejemplo

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
    ?marketplaceIds=ATVPDKIKX0DER
    &issueLocale=en_US

{
  "productType":"LUGGAGE",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/item_name",
      "value":[
        {
          "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op":"delete",
      "path":"/attributes/item_type_name",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}

Respuesta

Una respuesta exitosa incluye lo siguiente:

Respuesta de ejemplo

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}

Tutorial: Eliminar una lista

Use este tutorial para eliminar una lista de Amazon para un selling partner determinado y el marketplace de Amazon usando la API de elementos de listas.

El siguiente diagrama proporciona una descripción general de los pasos del flujo de trabajo para eliminar un elemento de la lista.

Workflow para eliminar una lista

requisitos previos

Para completar este tutorial, necesitará:

• Autorización del selling partner para el que está haciendo llamadas. Consulte la Guía para desarrolladores de la Selling Partner API para obtener más información.
• Aprobación para el rol de Listado de productos en su perfil de desarrollador.
• El rol de Listado de productos seleccionado en la página de registro de la aplicación para su aplicación.

Paso 1. Enviar solicitud de eliminación de elementos de listados

Llame a la operación deleteListingsItem para eliminar un listado, pasando los siguientes parámetros:

Parámetros de solicitud

Parámetros de ruta

Parámetros de Query

Solicitud de ejemplo

DELETE https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
    ?marketplaceIds=ATVPDKIKX0DER
    &issueLocale=en_US

Respuesta

Una respuesta exitosa incluye lo siguiente:

Respuesta de ejemplo

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}

Envío de imágenes y otros atributos multimedia

La Listings Items API acepta imágenes de productos y otros atributos de contenido multimedia de las siguientes fuentes:

• Contenido de bucket de Amazon S3 de acceso público descargado a través de URL HTTP o HTTPS
• Contenido de distribución de Amazon CloudFront de acceso público descargado a través de URL HTTP o HTTPS
• Contenido privado del bucket de Amazon S3 descargado a través de la URL de S3 (por ejemplo, s3://bucket-name/object-name.jpg )

Las imágenes alojadas en servidores de terceros no son compatibles.

Si utiliza un bucket de Amazon S3 privado, también debe configurar su política de buckets de Amazon S3 para permitir que GetObject y Operaciones ListBucket en el rol de IAM que accede al bucket (arn:aws:iam::368641386589:role/Media-Download-Role ). Consulte la siguiente política de bucket de S3 para ver un ejemplo.

El contenido privado de Amazon S3 se trata como inmutable, lo que significa que no puede cambiar el contenido de una clave de objeto de Amazon S3. El nuevo contenido multimedia requiere una nueva clave de objeto de Amazon S3. Esta convención brinda el beneficio de tiempos de procesamiento mejorados y evita el costo de descargas redundantes en caso de que se vuelvan a procesar los envíos de listas.

El siguiente es un ejemplo de política de bucket de Amazon S3 que habilita las operaciones requeridas en un bucket denominado bucket-name :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::bucket-name/*",
                "arn:aws:s3:::bucket-name"
            ],
            "Principal": {
                "AWS": [
                    "arn:aws:iam::368641386589:role/Media-Download-Role"
                ]
            }
        }
    ]
}