Guias de uso
Documentação GlobalDeveloper HubSuporteStatus da API

Guia de caso de uso da API de definições de tipo de produto

Como acessar programaticamente atributos e requisitos de dados para tipos de produtos no catálogo da Amazon.

Suggest Edits

Versão da API: 2020-09-01

O que é a API de definições de tipo de produto (Product Type Definitions)?

Com a API Product Type Definitions você pode pesquisar e recuperar definições de tipo de produto da Amazon. As definições de tipo de produto da Amazon descrevem os requisitos de atributo e dados para itens no catálogo da Amazon usando o esquema JSON.

Para obter mais detalhes sobre o formato de esquema JSON fornecido pela API Product Type Definitions, consulte a documentação do Meta-esquema de definição de tipo de produto (v1) da Amazon.

Consulte a Referência da API de definições de tipo de produto para obter detalhes sobre as operações da API e os tipos de dados e esquemas associados.

Características principais

  • JSON Schemas: A API Product Type Definitions fornece esquemas JSON que descrevem os requisitos independentes do vendedor para um determinado tipo de produto da Amazon. Isso inclui o formato de dados, restrições de atributo (ou seja, obrigatoriedade, comprimento, quantidade máxima, etc.) e restrições de atributo aplicadas condicionalmente (ou seja, se as baterias estão incluídas, que tipo de bateria).

  • Compatível com bibliotecas de código aberto: Os esquemas JSON fornecidos podem ser usados ​​com bibliotecas, aplicativos e serviços comerciais e de código aberto amplamente disponíveis para entender os requisitos de dados, criar mapeamentos de dados, gerar interfaces de usuário e validar dados de listagens antes do envio para a Amazon.

  • Detalhes da apresentação localizada: Os esquemas JSON fornecidos incluem rótulos de exibição e descrições para atributos em qualquer localidade com suporte para qualquer mercado.

Terminologia

  • JSON Schema: JSON Schema é um vocabulário que permite anotar e validar documentos JSON. Consulte json-schema.org para obter mais detalhes.

  • Meta Schema: Meta schemas descrevem o vocabulário usado pelos documentos JSON Schema. Por exemplo, os esquemas de tipo de produto da Amazon incluem vocabulário para selectors e editable. Esse vocabulário é descrito em um meta esquema, permitindo que bibliotecas e aplicativos entendam e validem dados JSON com base nessas extensões do vocabulário padrão do esquema JSON.

  • Tipo de produto: Um tipo de produto da Amazon é uma categorização hierárquica de itens no catálogo da Amazon. Os requisitos de dados do item estão vinculados ao tipo de produto associado ao item.

Tutorial: Pesquisar Definições de Tipos de Produtos Disponíveis

Use este tutorial para pesquisar e identificar os tipos de produtos da Amazon disponíveis na API Product Type Definitions para um determinado mercado da Amazon e tipo de conta de parceiro de vendas.

Pré-requisitos

Para concluir este tutorial, você precisará de:

  • Autorização do parceiro de vendas para quem você está fazendo chamadas. Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter mais informações.

  • Aprovação para a função "Product Listing" em seu perfil de desenvolvedor.

  • A função "Product Listing" selecionada na página de registro do aplicativo para seu aplicativo.

Etapa 1. Pesquisar definições de tipo de produto

Chame a operação searchDefinitionsProductTypes para pesquisar tipos de produtos disponíveis na API de definições de tipo de produto.

Parâmetros da requisição

ParâmetroExemploDescrição
marketplaceIds

Obrigatório		ATVPDKIKX0DERLista delimitada por vírgulas de identificadores de mercados da Amazon.

Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter a lista de identificadores de mercado da Amazon.
keywordsLUGGAGELista de palavras-chave delimitadas por vírgulas para pesquisar tipos de produtos disponíveis por nome.

Padrão: quando nenhuma palavra-chave é fornecida, a lista completa de tipos de produtos disponíveis é fornecida.

Exemplo de Requisição 

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

Resposta
Uma resposta bem-sucedida inclui o seguinte:

NomeExemploDescrição
productTypesVeja Exemplo de RespostaLista de tipos de produtos que correspondem à solicitação de pesquisa.
nameLUGGAGENome do tipo de produto da Amazon.
marketplaceIdsATVPDKIKX0DERLista delimitada por vírgulas de identificadores de mercado da Amazon.

Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter a lista de identificadores de mercado da Amazon.

Tipo: array(csv)

Exemplo de resposta 

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

Tutorial: Recuperar Uma Definição de Tipo de Produto

Use este tutorial para retornar as definições de tipo de produto da Amazon e esquemas relacionados da API Product Type Definitions para um determinado parceiro de vendas, tipo de produto da Amazon e mercado da Amazon.

Pré-requisitos

Para concluir este tutorial, você precisará de:

  • Autorização do parceiro de vendas para quem você está fazendo chamadas. Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter mais informações.

  • Aprovação para a função "Product Listing" em seu perfil de desenvolvedor.

  • A função da "Product Listing" selecionada na página de registro do aplicativo para seu aplicativo

Etapa 1. Recuperar a Definição do Tipo de Produto

Chame a operação getDefinitionsProductType para recuperar uma definição de tipo de produto da Amazon da API Product Type Definitions.

Parâmetros da Requisição

Parâmetros do Path

ParâmetroExemploDescrição
productType

Obrigatório		LUGGAGENome do tipo de produto da Amazon.

Tipo: string

Parâmetros da Consulta

ParâmetroExemploDescrição
sellerIdAXXXXXXXXXXXXXO identificador do parceiro de vendas. Quando fornecidos, os requisitos e valores específicos do vendedor são preenchidos no esquema de definição de tipo de produto, como nomes de marcas associadas ao parceiro de vendas.

Tipo: string
marketplaceIds


Obrigatório		ATVPDKIKX0DERLista delimitada por vírgulas de identificadores de mercado da Amazon.
Observação: este parâmetro está limitado a um marketplaceId no momento

Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter a lista de identificadores de mercado da Amazon.

Tipo: < string > array(csv)
productTypeVersionU1d1eorqMs3U=Versão da definição do tipo de produto da Amazon a ser recuperada. As versões de pré-lançamento das definições de tipo de produto podem ser recuperadas com RELEASE_CANDIDATE. Se nenhuma versão de pré-lançamento estiver disponível no momento, a última (LATEST) versão publicada será fornecida.

Padrão: LATEST

Tipo: string
requirementsLISTINGNome do conjunto de requisitos para os quais recuperar os requisitos.
LISTING - Requisitos incluindo fatos do produto e termos de vendas.
 LITING_OFFER_ONLY - Requisitos que incluem apenas os termos de vendas.
* LITING_PRODUCT_ONLY - Requisitos que incluem apenas informações sobre o produto.
Padrão: LISTING

Tipo: enum (Requirements)
requirementsEnforcedENFORCEDIdentifica se os atributos necessários para um conjunto de requisitos são impostos pelo esquema de definição de tipo de produto. Os requisitos não obrigatórios permitem a validação estrutural de atributos individuais sem que todos os atributos necessários estejam presentes (como para atualizações parciais).
ENFORCED - Atributos obrigatórios são impostos pelo esquema.
 NOT_ENFORCED - Os atributos obrigatórios não são impostos pelo esquema.
Padrão: ENFORCED

Tipo: enum (RequirementsEnforced)
localept_BRLocalização para recuperar detalhes da apresentação (rótulos e descrições). O padrão é a localidade principal do mercado da Amazon.

Padrão: DEFAULT

Tipo: enum (Locale)

Exemplo de Requisição 

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

Resposta

Uma resposta bem-sucedida inclui o seguinte:

NomeExemploDescrição
metaSchema"metaSchema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "QFQDmPwMARO7vwMEyLhOtw==" }Link para recuperar o documento Meta-Schema de definição de tipo de produto da Amazon (válido por 7 dias).

Checksum fornecido para comparação com documentos recuperados anteriormente.

Tipo: SchemaLink
schema"schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" }Link para recuperar o documento JSON Schema para a definição do tipo de produto da Amazon (válido por 7 dias).

Checksum fornecido para comparação com documentos recuperados anteriormente.

Tipo: SchemaLink
requirementsLISTINGNome do conjunto de requisitos para os quais recuperar os requisitos.
LISTING - Requisitos incluindo fatos do produto e termos de vendas.
 LITING_OFFER_ONLY - Requisitos que incluem apenas os termos de vendas.
LITING_PRODUCT_ONLY - Requisitos que incluem apenas informações sobre o produto.
 Padrão: LISTING

Tipo: enum (Requirements)
requirementsEnforcedENFORCEDIdentifica se os atributos necessários para um conjunto de requisitos são impostos pelo esquema de definição de tipo de produto. Os requisitos não obrigatórios permitem a validação estrutural de atributos individuais sem que todos os atributos necessários estejam presentes (como para atualizações parciais).
ENFORCED - Atributos obrigatórios são impostos pelo esquema.
 NOT_ENFORCED - Os atributos obrigatórios não são impostos pelo esquema.
Padrão: ENFORCED

Tipo: enum (RequirementsEnforced)
propertyGroups"propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "purchasable_offer" ] } }Os grupos de propriedades definem segmentações lógicas de propriedades descritas no documento JSON Schema de definição de tipo de produto da Amazon. Essas segmentações podem ser usadas para agrupar propriedades em interfaces de usuário, identificar propósitos e assim por diante.

Os grupos de propriedades são apenas informativos e não afetam a estrutura ou a formatação dos dados.

Tipo: < string, PropertyGroup > map
localept_BRA localidade dos detalhes da apresentação (rótulos e descrições) fornecidos no documento JSON Schema de definição de tipo de produto da Amazon.

Tipo: enum (Locale)
marketplaceIdsATVPDKIKX0DERIdentificadores de mercado da Amazon para os quais a definição de tipo de produto da Amazon é aplicável.

Tipo: < string > array
productTypeLUGGAGEO nome do tipo de produto da Amazon ao qual essa definição de tipo de produto se aplica.[

Tipo: string
productTypeVersionU8L4z4Ud95N16tZlR7rsmbQ==Versão da definição do tipo de produto da Amazon.

Tipo: (ProductTypeVersion)

Exemplo de Resposta 

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

Etapa 2. Recuperar Documentos de Schema

Na etapa anterior, a definição de tipo de produto da Amazon recuperada inclui detalhes sobre o tipo de produto da Amazon e links para recuperar os documentos do meta schema e do schema do tipo de produto. Os links fornecidos são válidos por 7 dias.

Documentos de schema podem ser recuperados programaticamente com um cliente HTTP padrão ou manualmente com um navegador web.

Observação importante: O documento JSON Schema de definição de tipo de produto da Amazon faz referência ao meta-schema por nome. Algumas bibliotecas de JSON Schema tentam resolver nomes de meta-schemas on-line por meio da web, que o Meta-Schema de definição de tipo de produto da Amazon (v1) não oferece suporte. Essas bibliotecas devem ser configuradas para usar uma cópia baixada do meta-schema. Consulte a documentação do Meta-Schema de definição de tipo de produto da Amazon (v1) para obter mais detalhes.

[Perguntas Frequentes] (https://pt-br-group.readme.io/amazon-portuguese/docs/perguntas-frequentes)

Updated almost 2 years ago