Versión API: 2020-09-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

• 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 : las respuestas de la API de elementos de listados 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. Las versiones futuras de la API de elementos de listados y las notificaciones automáticas relacionadas brindarán la capacidad de recibir estos problemas posteriores a la aceptación.

🚧

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: 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/2020-09-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",
      "attributeName": "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/2020-09-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.

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/2020-09-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 que son descargados por Amazon desde URLs de acceso público de AWS S3 o AWS CloudFront a través de HTTP o HTTPS. También es posible descargar contenido privado de AWS S3 a través de URLs de S3(por ejemplo, s3://bucket-name/object-name.jpg ). Para que Amazon pueda descargar desde URLs privadas de AWS S3, las operaciones GetObject y ListBucket deben estar permitidas para el rol de AWS IAM (arn:aws:iam::368641386589:role/Media-Download-Role) en el bucket de AWS S3. Ten en cuenta que el contenido privado de AWS S3 se trata como inmutable, lo que significa que no se admite cambiar el contenido de una clave de objeto de AWS S3 (es decir, el nuevo contenido multimedia requiere una nueva clave de objeto de AWS S3). Esta convención proporciona el beneficio de tiempos de procesamiento mejorados y evita el costo de descargas redundantes en caso de que las presentaciones de listados sean reprocesadas.

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"
                ]
            }
        }
    ]
}