Guía de casos de uso de la API de definiciones de tipo de producto v2020-09-01

Accede mediante programación a los requisitos de datos y atributos del tipo de producto en el catálogo de Amazon.

Versión de la API: 2020-09-01

¿Qué es la API de definiciones de tipo de producto?

Mediante la API del colaborador comercial para definiciones de tipo de producto (API de definiciones de tipo de producto), puedes buscar y recuperar definiciones de tipo de producto de Amazon. Las definiciones de tipo de producto de Amazon describen los requisitos de atributos y datos para los artículos del catálogo de Amazon utilizando el esquema JSON.

For more details on the JSON Schema format provided by the Product Type Definitions API, refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation.

Refer to the Product Type Definitions API v2020-09-01 Reference for details about API operations and associated data types and schemas.

Características principales

  • Esquemas JSON: la API de definiciones de tipo de producto proporciona esquemas JSON que describen los requisitos independientes del vendedor para un tipo de producto de Amazon determinado. Esto incluye el formato de los datos, las restricciones de atributos (es decir, obligatorio, longitud, máximo, etc.) y las restricciones de atributos aplicadas condicionalmente (es decir, si se incluyen pilas y qué tipo de pilas utilizar).

  • Compatible con bibliotecas de código abierto: los esquemas JSON proporcionados pueden utilizarse con bibliotecas, aplicaciones y servicios comerciales y de código abierto ampliamente disponibles para comprender los requisitos de datos, crear asignaciones de datos, generar interfaces de usuario y validar los datos de los listings antes de enviarlos a Amazon.

  • Detalles de presentación localizados: los esquemas JSON proporcionados incluyen etiquetas de presentación y descripciones de atributos en cualquier configuración regional compatible con cualquier sitio web.

  • Recomendaciones de tipos de productos: La API de definiciones de tipos de productos ofrece recomendaciones para ayudarte a elegir el tipo de producto más adecuado. Estas recomendaciones se basan en los títulos de los productos en cualquier configuración regional compatible de cualquier mercado, si están disponibles.

Terminología

  • JSON Schema: JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. Refer to json-schema.org for more details.

  • Metaesquema: los metaesquemas describen el vocabulario utilizado por los documentos de esquemas JSON. Por ejemplo, los esquemas de tipo de producto de Amazon incluyen vocabulario para selectors y editable. Este vocabulario se describe en un metaesquema, lo que permite a las bibliotecas y aplicaciones comprender y validar datos JSON basados en estas ampliaciones del vocabulario del esquema JSON estándar.

  • Tipo de producto: un tipo de producto de Amazon es una categorización jerárquica de los artículos del catálogo de Amazon. Los requisitos de datos del producto están vinculados al tipo de producto asociado al producto.

Tutorial: Buscar de definiciones de tipo de productos disponibles

Utiliza este tutorial para buscar e identificar los tipos de productos de Amazon disponibles en la API de definiciones de tipo de producto para un sitio web de Amazon y un tipo de cuenta del colaborador comercial.

Requisitos

Para completar este tutorial, necesitarás:

  • Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

  • Aprobación para el rol de listing de productos en tu perfil de desarrollador.

  • El rol de listing de productos seleccionado en la página de registro de la aplicación.

Buscar definiciones de tipos de productos

Call the searchDefinitionsProductTypes operation to search product types available in the Product Type Definitions API.

Parámetros de solicitud

Parámetro Ejemplo Descripción Obligatorio
marketplaceIds ATVPDKIKX0DER A comma-delimited list of Amazon marketplace identifiers for the request.

Refer to Marketplace IDs for the list of Amazon marketplace identifiers.
keywords LUGGAGE Una lista de palabras clave delimitadas por comas para buscar tipos de productos.

Predeterminado: cuando no hay palabras clave o itemName se proporcionan, se proporciona la lista completa de los tipos de productos disponibles.
No
locale en_US La configuración regional de los nombres mostrados en la respuesta.

Predeterminado: configuración regional principal del mercado.
No
searchLocale en_US El idioma utilizado para las palabras clave o itemName parámetros.

Predeterminado: configuración regional principal del mercado.
No

Ejemplo de solicitud

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes ?marketplaceIds=ATVPDKIKX0DER &keywords=LUGGAGE &locale=en_US &searchLocale=en_US

Respuesta

Una respuesta correcta incluye lo siguiente:

Nombre Ejemplo Descripción
productTypes Consulte el ejemplo de respuesta Lista de tipos de productos que coinciden con la solicitud de búsqueda.
name LUGGAGE Nombre del tipo de producto de Amazon.
displayName Luggage La descripción traducida y legible por humanos del tipo de producto de Amazon.
marketplaceIds ATVPDKIKX0DER Lista de identificadores de sitios web de Amazon para los que está disponible el tipo de producto (dentro de los identificadores de sitios web solicitados).
productTypeVersion UHqSqmb4FNUk= Los detalles de la versión del tipo de producto de Amazon.

Ejemplo de respuesta

{ "productTypes": [ { "name": "LUGGAGE", "displayName": "Luggage", "marketplaceIds": [ "ATVPDKIKX0DER" ] } ], "productTypeVersion": "UHqSqmb4FNUk=" }

Tutorial: Obtenga recomendaciones para la definición del tipo de producto

Usa este tutorial para obtener recomendaciones de tipos de productos de Amazon desde la API de definiciones de tipos de productos para una plataforma de Amazon, un tipo de cuenta de socio vendedor y un nombre de artículo determinados.

Requisitos

Para completar este tutorial, necesitarás:

  • Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

  • Aprobación para el rol de listing de productos en tu perfil de desarrollador.

  • El rol de listing de productos seleccionado en la página de registro de la aplicación.

Buscar definiciones de tipos de productos

Call the searchDefinitionsProductTypes operation to get product type recommendations based on the itemName from the Product Type Definitions API.

Parámetros de solicitud

Parámetro Ejemplo Descripción Obligatorio
marketplaceIds ATVPDKIKX0DER A comma-delimited list of Amazon marketplace identifiers for the request.

Refer to Marketplace IDs for the list of Amazon marketplace identifiers.
itemName Softside Luggage with Spinner Wheels, Black El título del ASIN para obtener la recomendación de tipo de producto.

Predeterminado: cuando no hay palabras clave o itemName se proporcionan, se proporciona la lista completa de los tipos de productos disponibles.
No
locale en_US La configuración regional de los nombres mostrados en la respuesta.

Predeterminado: configuración regional principal del mercado.
No
searchLocale en_US El idioma utilizado para las palabras clave o itemName parámetros.

Predeterminado: configuración regional principal del mercado.
No

Ejemplo de solicitud

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes ?marketplaceIds=ATVPDKIKX0DER &itemName=Softside%20Luggage%20with%20Spinner%20Wheels%2C%20Black, &locale=en_US &searchLocale=en_US

Respuesta

Una respuesta correcta incluye lo siguiente:

Nombre Ejemplo Descripción
productTypes Consulte el ejemplo de respuesta Lista de tipos de productos que coinciden con la solicitud de búsqueda.
name LUGGAGE Nombre del tipo de producto de Amazon.
displayName Luggage La descripción traducida y legible por humanos del tipo de producto de Amazon.
marketplaceIds ATVPDKIKX0DER Lista de identificadores de sitios web de Amazon para los que está disponible el tipo de producto (dentro de los identificadores de sitios web solicitados).
productTypeVersion UHqSqmb4FNUk= Los detalles de la versión del tipo de producto de Amazon.

Ejemplo de respuesta

{ "productTypes": [ { "name": "LUGGAGE", "displayName": "Luggage", "marketplaceIds": [ "ATVPDKIKX0DER" ] } ], "productTypeVersion": "UHqSqmb4FNUk=" }

Tutorial: Recuperar una definición de tipo de producto

Utiliza este tutorial para devolver las definiciones de tipo de producto de Amazon y los esquemas relacionados de la API de definiciones de tipo de producto para un colaborador comercial, un tipo de producto de Amazon y un sitio web de Amazon determinados.

Requisitos

Para completar este tutorial, necesitarás:

  • Authorization from the Selling Partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

  • Aprobación para el rol de listing de productos en tu perfil de desarrollador.

  • El rol de listing de productos seleccionado en la página de registro de la aplicación.

Recuperar la definición del tipo de producto

Call the getDefinitionsProductType operation to retrieve an Amazon Product Type Definition from the Product Type Definitions API.

Parámetros de solicitud

Parámetros de ruta

Parámetro Ejemplo Descripción Obligatorio
productType LUGGAGE Nombre del tipo de producto de Amazon.

Tipo: cadena

Parámetros de consulta

Parámetro Ejemplo Descripción Obligatorio
sellerId AXXXXXXXXXXXXX El identificador del colaborador comercial. Cuando se proporciona, los requisitos y valores específicos del vendedor se rellenan en el esquema de definición del tipo de producto, como los nombres de marca asociados con el colaborador comercial.

Tipo: cadena

No
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.
Note: This parameter is limited to one marketplaceId at this time.

Refer to Marketplace IDs for the list of Amazon marketplace identifiers.

Tipo: matriz < cadena > (csv)

productTypeVersion U1d1eorqMs3U= Versión de la definición de tipo de producto de Amazon que se desea recuperar. Las versiones preliminares de las definiciones de tipo de producto pueden recuperarse con RELEASE_CANDIDATE. Si no hay ninguna versión preliminar disponible, se proporcionará la versión actual LATEST.

Valor predeterminado: LATEST

Tipo: cadena

No
requirements LISTING Nombre del conjunto de requisitos para los que se van a recuperar los requisitos.

  • LISTING: requisitos que incluyen los datos del producto y las condiciones de venta.
  • LISTING_OFFER_ONLY: requisitos que solo incluyen las condiciones de venta.
  • LISTING_PRODUCT_ONLY: requisitos que solo incluyen los datos del producto.

Valor predeterminado: LISTING

Type: enum (Requirements)

No
requirementsEnforced ENFORCED Identifica si el esquema de definición del tipo de producto impone los atributos necesarios para un conjunto de requisitos. Los requisitos no forzados permiten la validación estructural de atributos individuales sin que estén presentes todos los atributos necesarios (como en el caso de las actualizaciones parciales).

  • ENFORCED: los atributos obligatorios vienen impuestos por el esquema.
  • NOT_ENFORCED: los atributos obligatorios no vienen impuestos por el esquema.

Valor predeterminado: ENFORCED

Type: enum (RequirementsEnforced)

No
locale en_US Configuración regional para recuperar los detalles de la presentación (etiquetas y descripciones). El valor predeterminado es la configuración regional principal del sitio web de Amazon.

Valor predeterminado: DEFAULT

Type: enum (Locale)

No

Ejemplo de solicitud

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE ?marketplaceIds=ATVPDKIKX0DER &requirements=LISTING &locale=en_US

Respuesta

Una respuesta correcta incluye lo siguiente:

Nombre Ejemplo Descripción
metaSchema
"metaSchema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
}
Link to retrieve the Amazon Product Type Definition Meta-Schema document (valid for seven days).

Checksum provided for comparison with previously retrieved documents.

Type: SchemaLink

schema
"schema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
}
Enlace para recuperar el documento de esquema JSON para la definición de tipo de producto de Amazon (válido durante 7 días).

Se proporciona una suma de verificación para comparar con documentos recuperados anteriormente.

Type: SchemaLink

requirements LISTING Nombre del conjunto de requisitos al que se aplica la definición de tipo de producto de Amazon.

  • LISTING: requisitos que incluyen los datos del producto y las condiciones de venta.
  • LISTING_OFFER_ONLY: requisitos que solo incluyen las condiciones de venta.
  • LISTING_PRODUCT_ONLY: requisitos que solo incluyen los datos del producto.

Valor predeterminado: LISTING

Type: enum (Requirements)

requirementsEnforced ENFORCED Identifica si el esquema de definición del tipo de producto impone los atributos necesarios para un conjunto de requisitos. Los requisitos no forzados permiten la validación estructural de atributos individuales sin que estén presentes todos los atributos necesarios (como en el caso de las actualizaciones parciales).

  • ENFORCED: los atributos obligatorios vienen impuestos por el esquema.
  • NOT_ENFORCED: los atributos obligatorios no vienen impuestos por el esquema.

Valor predeterminado: ENFORCED

Type: enum (RequirementsEnforced)

propertyGroups
"propertyGroups": {
  "offer": {
    "title": "Offer",
    "description": "Product Offer",
    "propertyNames": [
      "purchasable_offer"
    ]
  }
}
Los grupos de propiedades definen segmentaciones lógicas de las propiedades descritas en el documento del esquema JSON de definición del tipo de producto de Amazon. Estas segmentaciones pueden utilizarse para agrupar propiedades en interfaces de usuario, identificar la finalidad, etc.

Los grupos de propiedades son meramente informativos y no afectan a la estructura ni al formato de los datos.

Type: < string, PropertyGroup > map

locale en_US La configuración regional de los detalles de presentación (etiquetas y descripciones) proporcionados en el documento de esquema JSON de definición de tipo de producto de Amazon.

Type: enum (Locale)

marketplaceIds ATVPDKIKX0DER Identificadores del sitio web de Amazon al que se aplica la definición de tipo de producto de Amazon.

Tipo: matriz < cadena >

productType LUGGAGE El nombre del tipo de producto de Amazon al que se aplica esta definición de tipo de producto.

Tipo: cadena

productTypeVersion U8L4z4Ud95N16tZlR7rsmbQ== Versión de la definición de tipo de producto de Amazon.

Type: (ProductTypeVersion)

displayName Luggage La descripción traducida y legible por humanos del tipo de producto de Amazon.

Ejemplo de respuesta

{ "metaSchema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "QFQDmPwMARO7vwMEyLhOtw==" }, "schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" }, "requirements": "LISTING", "requirementsEnforced": "ENFORCED", "propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "fulfillment_channel_availability", "purchasable_offer", "condition_type", "condition_note", "list_price", "product_tax_code", "merchant_release_date", "merchant_shipping_group", "max_order_quantity", "gift_options", "main_offer_image_locator", "other_offer_image_locator_1", "other_offer_image_locator_2", "other_offer_image_locator_3", "other_offer_image_locator_4", "other_offer_image_locator_5" ] }, "images": { "title": "Images", "description": "Physical images or URL's", "propertyNames": [ "main_product_image_locator", "other_product_image_locator_1", "other_product_image_locator_2", "other_product_image_locator_3", "other_product_image_locator_4", "other_product_image_locator_5", "other_product_image_locator_6", "other_product_image_locator_7", "other_product_image_locator_8", "swatch_product_image_locator" ] }, "shipping": { "title": "Shipping", "description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)", "propertyNames": [ "item_dimensions", "item_package_dimensions", "item_package_weight" ] }, "variations": { "title": "Variations", "description": "Variations that product will use", "propertyNames": [ "parentage_level", "child_parent_sku_relationship", "variation_theme" ] }, "safety_and_compliance": { "title": "Safety & Compliance", "description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))", "propertyNames": [ "country_of_origin", "warranty_description", "batteries_required", "batteries_included", "battery", "num_batteries", "number_of_lithium_metal_cells", "number_of_lithium_ion_cells", "lithium_battery", "supplier_declared_dg_hz_regulation", "hazmat", "safety_data_sheet_url", "item_weight", "ghs", "supplier_declared_material_regulation", "california_proposition_65", "pesticide_marking" ] }, "product_identity": { "title": "Product Identity", "description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)", "propertyNames": [ "item_name", "brand", "supplier_declared_has_product_identifier_exemption", "externally_assigned_product_identifier", "merchant_suggested_asin", "item_type_keyword", "item_type_name", "model_number", "manufacturer" ] }, "product_details": { "title": "Product Details", "description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)", "propertyNames": [ "product_description", "bullet_point", "generic_keyword", "special_feature", "style", "department", "target_gender", "age_range_description", "material", "outer", "fabric_type", "lining_description", "number_of_items", "number_of_wheels", "wheel", "model_name", "color", "size", "size_map", "part_number", "compliance_media" ] } }, "locale": "en_US", "marketplaceIds": [ "ATVPDKIKX0DER" ], "productType": "LUGGAGE", "displayName": "Luggage", "productTypeVersion": { "version": "U8L4z4Ud95N16tZlR7rsmbQ==", "latest": true, "releaseCandidate": false } }

Recuperar los documentos del esquema

En el paso anterior, la definición de tipo de producto de Amazon recuperada incluye detalles sobre el tipo de producto de Amazon y enlaces para recuperar el metaesquema y los documentos de esquema del tipo de producto. Los enlaces proporcionados son válidos durante 7 días.

Los documentos de esquema pueden recuperarse mediante programación con un cliente HTTP estándar o manualmente con un navegador web.

❗️

Los nombres de los metaesquemas no se pueden resolver a través de la web

The Amazon Product Type Definition JSON Schema document references the meta schema by name. Some JSON Schema libraries attempt to resolve meta schema names online via the web, which the Amazon Product Type Definition Meta-Schema (v1) does not support. These libraries should be configured to use a downloaded copy of the meta schema instead. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.

Preguntas frecuentes

En esta documentación se abordan preguntas y detalles comunes sobre la API de definiciones de tipo de producto. Si tienes alguna pregunta o duda que no esté incluida en esta documentación, ponte en contacto con el servicio de asistencia de la API del colaborador comercial o crea un caso en el repositorio de GitHub.

¿Hasta qué punto están actualizadas las definiciones de tipo de producto de Amazon?

A menos que especifique un productTypeVersion anterior, las definiciones de tipo de producto de Amazon siempre describen los requisitos más recientes y actualizados del catálogo de Amazon.

¿Están disponibles todos los tipos de productos de Amazon con la API de definiciones de tipo de producto?

Amazon amplía continuamente la compatibilidad con tipos de productos de Amazon nuevos y existentes en la API de definiciones de tipo de producto. Para obtener una lista actualizada de los tipos de productos de Amazon disponibles, utiliza la API de definiciones de tipo de producto.

¿Qué versión del esquema JSON se utiliza?

Amazon Product Type Definition JSON Schemas extend JSON Schema 2019-09. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.

Cómo se utilizarán las futuras versiones del esquema JSON?

As future versions of JSON Schema are adopted by the Product Type Definitions API, they will be accompanied by a new version release of the Product Type Definitions API and Amazon Product Type Definition Meta-Schema.

Future versions of JSON Schema will not be adopted by existing versions of the Product Type Definitions API or Amazon Product Type Definition Meta-Schema.

¿Incluyen los esquemas JSON de definición de tipo de producto vocabulario personalizado?

Most Amazon catalog requirements are described utilizing standard JSON Schema 2019-09 vocabulary. However, there are a few requirements that necessitate extending JSON Schema with custom vocabulary. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.

¿Debo implementar la validación para el vocabulario personalizado?

No. The Amazon Product Type Definition Meta-Schema (v1) uses custom vocabulary to fully describe Amazon catalog requirements. Validating data with custom data enables you to prevent most listings-related issues from occurring before submitting to Amazon. However, it is up-to-you to implement such validation. Without implementing this validation, submitting data to Amazon can produce listings-related issues after submission to Amazon.

¿Necesito código personalizado para utilizar esquemas JSON?

La cantidad de código personalizado depende de tu aplicación. Casos de ejemplo:

  • Uso de una biblioteca de código abierto con validación de vocabulario personalizado: el uso de una biblioteca de código abierto para realizar la mayor parte de la validación de esquemas JSON significa que se necesita código personalizado para recuperar esquemas de la API de definiciones de tipo de producto, implementar la validación de vocabulario personalizado e integrarse con la biblioteca de código abierto.

  • Uso de una biblioteca de código abierto sin validación de vocabulario personalizado: el uso de una biblioteca de código abierto para realizar la mayor parte de la validación del esquema JSON significa que se necesita código personalizado para recuperar esquemas de la API de definiciones de tipo de producto e integrarlos en la biblioteca de código abierto.

¿Qué bibliotecas de código abierto hay disponibles?

Dozens of open-source libraries and implementations are available to validate data, render user interfaces, and generate code. Refer to JSON Schema Tooling for a full list.

Amazon no apoya ni respalda directamente ninguna biblioteca o implementación comercial o de código abierto específica. Los ejemplos proporcionados en esta documentación son solo de referencia.

¿Qué ejemplos hay disponibles para validar datos con esquemas de tipo de producto?

The accompanying Amazon Product Type Definition Meta-Schema (v1) documentation includes example integrations with open-source libraries to validate data with custom vocabulary in .NET (C#), Java, and JavaScript (Node.js).

¿Cómo puedo informar de problemas con las definiciones de tipo de producto de Amazon?

For issues specific to the Product Type Definitions API or the content of Amazon Product Type Definition JSON Schemas, contact Selling Partner API support.


¿Te ha ayudado esta página?