Versión API: 2020-09-01

¿Qué es la Product Type Definitions API?

Con la Selling Partner API para definiciones de tipos de productos (Product Type Definitions API), puede buscar y recuperar definiciones de tipos de productos de Amazon. Las definiciones de tipos de productos de Amazon describen los requisitos de datos y atributos para los artículos del catálogo de Amazon mediante el esquema JSON.

Para obtener más detalles sobre el formato de esquema JSON proporcionado por la API de definiciones de tipo de producto, consulte la documentación del metaesquema de definición de tipo de producto de Amazon (v1) que se adjunta.

Consulte la Referencia de la API de definiciones de tipos de productos para obtener detalles sobre las operaciones de la API y los tipos de datos y esquemas asociados.

Características clave

• Esquemas JSON : la API de definiciones de tipos de productos proporciona esquemas JSON que describen los requisitos independientes del seller para un tipo de producto de Amazon determinado. Esto incluye el formato de datos, restricciones de atributos (es decir, requerido, longitud, máximo, etc.) y restricciones de atributos aplicadas condicionalmente (es decir, si se incluyen baterías, qué tipo de batería).
• Compatible con bibliotecas de código abierto : los esquemas JSON proporcionados se pueden usar 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 datos de LISTINGs antes de enviarlos a Amazon.
• Detalles de presentación localizados : los esquemas JSON proporcionados incluyen etiquetas de visualización y descripciones de atributos en cualquier configuración regional admitida para cualquier marketplace.

Terminología

• JSON Schema : JSON Schema es un vocabulario que le permite anotar y validar documentos JSON. Consulte json-schema.org para obtener más detalles.
• Meta Schema : los meta esquemas describen el vocabulario utilizado por los documentos de esquema 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 que las bibliotecas y las aplicaciones comprendan y validen los datos JSON en función de estas extensiones del vocabulario del esquema JSON estándar.
• Product Type : un tipo de producto de Amazon es una categorización jerárquica de artículos en el catálogo de Amazon. Los requisitos de datos del artículo están vinculados al tipo de producto asociado del artículo.

Tutorial: Buscar definiciones de tipos de productos disponibles

Utilice este tutorial para buscar e identificar los tipos de productos de Amazon disponibles en la API de definiciones de tipos de productos para un marketplace de Amazon determinado y un tipo de cuenta de selling partner.

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 API de Selling Partner para obtener más información.
• Aprobación para el rol de LISTING de productos en su perfil de desarrollador.
• El rol de LISTING de productos seleccionado en la página de registro de la aplicación para su aplicación.

Paso 1. Buscar definiciones de tipos de productos

Llame a la operación searchDefinitionsProductTypes para buscar tipos de productos disponibles en la API de definiciones de tipos de productos.

Parámetros de solicitud

solicitud de ejemplo

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

Respuesta

Una respuesta exitosa incluye lo siguiente:

Respuesta de ejemplo

{
  "productTypes": [
    {
      "name": "LUGGAGE",
      "marketplaceIds": [
        "ATVPDKIKX0DER"
      ]
    }
  ]
}

Tutorial: Recuperar una definición de tipo de producto

Utilice este tutorial para devolver definiciones de tipos de productos de Amazon y esquemas relacionados desde la API de definiciones de tipos de productos para un selling partner determinado, un tipo de producto de Amazon y un marketplace de Amazon.

requisitos previos

Para completar este tutorial, necesitará:

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

Paso 1. Recuperar definición de tipo de producto

Llame a la operación getDefinitionsProductType para recuperar una definición de tipo de producto de Amazon de la API de definiciones de tipo de producto.

Parámetros de solicitud

Parámetros de ruta

Parámetros de consulta

solicitud de ejemplo

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

Respuesta

Una respuesta exitosa incluye lo siguiente:

"metaSchema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
}

"schema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
}

"propertyGroups": {
  "offer": {
    "title": "Offer",
    "description": "Product Offer",
    "propertyNames": [
      "purchasable_offer"
    ]
  }
}

Respuesta de ejemplo

{
  "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 imagess 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",
  "productTypeVersion": {
    "version": "U8L4z4Ud95N16tZlR7rsmbQ==",
    "latest": true,
    "releaseCandidate": false
  }
}

Paso 2. Recuperar documentos de 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 links para recuperar el metaesquema y los documentos de esquema de tipo de producto. Los links proporcionados son válidos durante 7 días.

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

Nota importante : el documento de esquema JSON de definición de tipo de producto de Amazon hace referencia al metaesquema por nombre. Algunas bibliotecas de esquemas JSON intentan resolver nombres de metaesquemas en línea a través de la web, lo que no es compatible con el metaesquema de definición de tipo de producto de Amazon (v1) . Estas bibliotecas deben configurarse para usar una copia descargada del metaesquema en su lugar. Consulte la documentación adjunta del metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles.

Preguntas frecuentes

Esta documentación cubre preguntas comunes y detalles para la API de definiciones de tipos de productos. Si tiene preguntas o inquietudes que no están cubiertas por esta documentación, comuníquese con el soporte de Selling Partner API o cree un problema en el repositorio de GitHub.

¿Qué tan frescas son las definiciones de tipos de productos de Amazon?

A menos que se especifique una anterior productTypeVersion , las definiciones de tipo de producto de Amazon siempre describen los últimos requisitos actualizados del catálogo de Amazon.

¿Todos los tipos de productos de Amazon están disponibles con la API de definiciones de tipos de productos?

No.

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

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

Los esquemas JSON de definición de tipo de producto de Amazon amplían el esquema JSON 2019-09 . Consulte la documentación adjunta del metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles.

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

A medida que la API de definiciones de tipos de productos adopte versiones futuras del esquema JSON, estarán acompañadas por una nueva versión de la API de definiciones de tipos de productos y el metaesquema de definiciones de tipos de productos de Amazon .

Las versiones futuras del esquema JSON no serán adoptadas por las versiones existentes de la API de definiciones de tipo de producto o el metaesquema de definición de tipo de producto de Amazon .

¿Los esquemas JSON de definición de tipo de producto incluyen vocabulario personalizado?

La mayoría de los requisitos del catálogo de Amazon se describen utilizando el vocabulario JSON Schema 2019-09 estándar. Sin embargo, existen algunos requisitos que requieren la extensión del esquema JSON con vocabulario personalizado. Consulte la documentación adjunta del metaesquema de definición de tipo de producto de Amazon (v1) para obtener más detalles.

¿Estoy obligado a implementar la validación para el vocabulario personalizado?

No.

El metaesquema de definición de tipo de producto de Amazon (v1) utiliza un vocabulario personalizado para describir completamente los requisitos del catálogo de Amazon. La validación de datos con datos personalizados le permite evitar que ocurran la mayoría de los problemas relacionados con los LISTINGs antes de enviarlos a Amazon. Sin embargo, depende de usted implementar dicha validación. Sin implementar esta validación, el envío de datos a Amazon puede generar problemas relacionados con los LISTINGs después del envío a Amazon.

¿Necesito código personalizado para usar esquemas JSON?

Sí.

La cantidad de código personalizado depende de su aplicación. Escenarios de ejemplo:

• Uso de la biblioteca de código abierto con validación de vocabulario personalizado : aprovechar una biblioteca de código abierto para manejar la mayoría de las validaciones de esquemas JSON significa que se necesita código personalizado para recuperar esquemas de la API de definiciones de tipos de productos, implementar la validación de vocabulario personalizado e integrarse con el biblioteca de código abierto.
• Uso de la biblioteca de código abierto sin validación de vocabulario personalizado : aprovechar una biblioteca de código abierto para manejar la mayoría de la validación de esquemas JSON significa que se necesita código personalizado para recuperar esquemas de la API de definiciones de tipos de productos e integrarse con la biblioteca de código abierto.

¿Qué bibliotecas de código abierto están disponibles?

Hay docenas de bibliotecas e implementaciones de código abierto disponibles para validar datos, representar interfaces de usuario y generar código. Consulte Implementaciones de esquema JSON para obtener una lista completa.

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

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

La documentación adjunta del metaesquema de definición de tipo de producto de Amazon (v1) incluye integraciones de ejemplo con bibliotecas de código abierto para validar datos con vocabulario personalizado en .NET (C#), Java y JavaScript (Node.js).

¿Cómo informo problemas con las definiciones de tipos de productos de Amazon?

Para problemas específicos de la API de definiciones de tipos de productos o el contenido de los esquemas JSON de definiciones de tipos de productos de Amazon, comuníquese con el soporte de la Selling Partner API .