Guia de casos de uso da API de definições de tipo de produto v2020-09-01

Acesse programaticamente o atributo do tipo de produto e os requisitos de dados no catálogo da Amazon.

Versão da API: 2020-09-01

O que é a API de definições de tipo de produto?

Usando a API do parceiro de vendas para definições de tipo de produto (API de definições de tipo de produto), você pode pesquisar e recuperar as definições de tipo de produto da Amazon. As definições de tipo de produto da Amazon descrevem os requisitos de atributos e dados para itens no catálogo da Amazon usando o esquema JSON.

Para obter mais detalhes sobre o formato do esquema JSON fornecido pela API de definições de tipo de produto, consulte a documentação metaesquema de definição de tipo de produto da Amazon (v1) em anexo.

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

Principais recursos

  • Esquemas JSON: a API de definições de tipo de produto fornece esquemas JSON que descrevem os requisitos independentes do vendedor para um determinado tipo de produto da Amazon. Isso inclui o formato dos dados, as restrições de atributos (ou seja, obrigatório, comprimento, máximo etc.) e as restrições de atributos aplicadas condicionalmente (ou seja, se as baterias estiverem incluídas e que tipo de bateria usar).

  • 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 ofertas antes do envio para a Amazon.

  • Detalhes localizados da apresentação: os esquemas JSON fornecidos incluem rótulos de exibição e descrições de atributos em qualquer localidade compatível com qualquer marketplace.

  • Recomendações de tipo de produto: A API de definições de tipo de produto fornece recomendações para ajudar você a escolher o tipo de produto mais aplicável. Essas recomendações são baseadas em títulos de produtos em qualquer local compatível com qualquer mercado, se disponível.

Terminologia

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

  • Metaesquema: os metaesquemas descrevem o vocabulário usado pelos documentos do esquema JSON. Por exemplo, os esquemas de tipo de produto da Amazon incluem vocabulário para selectors e editable. Esse vocabulário é descrito em um metaesquema, 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 dos 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 tipo de produto disponíveis

Use este tutorial para pesquisar e identificar os tipos de produtos da Amazon disponíveis na API de definições de tipos de produtos para um determinado Site da Amazon e tipo de conta de parceiro de vendas.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

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

  • Aprovação para a função de oferta de produtos em seu perfil de desenvolvedor.

  • A função de oferta de produtos selecionada na página de registro do aplicativo para seu aplicativo.

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 tipos de produtos.

Parâmetros de solicitação

Parâmetro Exemplo Descrição Obrigatório
marketplaceIds ATVPDKIKX0DER Lista delimitada por vírgula dos identificadores do Site da Amazon para a solicitação.

Consulte IDs de mercado para obter a lista de identificadores de site da Amazon.
Sim
keywords LUGGAGE Uma lista de palavras-chave delimitada por vírgulas para pesquisar tipos de produtos.

Padrão: Quando não há palavras-chave ou itemName são fornecidas, a lista completa dos tipos de produtos disponíveis é fornecida.
Não
locale en_US A localidade dos nomes de exibição na resposta.

Padrão: localidade primária do mercado.
Não
searchLocale en_US O idioma usado para palavras-chave ou itemName parâmetros.

Padrão: localidade primária do mercado.
Não

Exemplo de solicitação

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

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome Exemplo Descrição
productTypes Consulte o exemplo de resposta Lista de tipos de produtos que correspondem à solicitação de pesquisa.
name LUGGAGE Nome do tipo de produto da Amazon.
displayName Luggage A descrição localizada e legível por humanos do tipo de produto da Amazon.
marketplaceIds ATVPDKIKX0DER Lista de identificadores do site da Amazon para os quais o tipo de produto está disponível (dentro dos identificadores do site solicitados).
productTypeVersion UHqSqmb4FNUk= Os detalhes da versão para o tipo de produto da Amazon..

Exemplo de resposta

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

Tutorial: Obtenha recomendações de definição de tipo de produto

Use este tutorial para obter recomendações de tipo de produto da Amazon a partir da API de definições de tipo de produto para um determinado mercado da Amazon, tipo de conta de parceiro de vendas e nome do item.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

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

  • Aprovação para a função de oferta de produtos em seu perfil de desenvolvedor.

  • A função de oferta de produtos selecionada na página de registro do aplicativo para seu aplicativo.

Pesquisar definições de tipo de produto

Ligue para o searchDefinitionsProductTypes operação para obter recomendações de tipo de produto com base no itemName da API de definições de tipo de produto.

Parâmetros de solicitação

Parâmetro Exemplo Descrição Obrigatório
marketplaceIds ATVPDKIKX0DER Lista delimitada por vírgula dos identificadores do Site da Amazon para a solicitação.

Consulte IDs de mercado para obter a lista de identificadores de site da Amazon.
Sim
itemName Softside Luggage with Spinner Wheels, Black O título do ASIN para obter a recomendação do tipo de produto.

Padrão: Quando não há palavras-chave ou itemName são fornecidas, a lista completa dos tipos de produtos disponíveis é fornecida.
Não
locale en_US A localidade dos nomes de exibição na resposta.

Padrão: localidade primária do mercado.
Não
searchLocale en_US O idioma usado para as palavras-chave ou itemName parâmetros.

Padrão: localidade primária do mercado.
Não

Exemplo de solicitação

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

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome Exemplo Descrição
productTypes Consulte o exemplo de resposta Lista de tipos de produtos que correspondem à solicitação de pesquisa.
name LUGGAGE Nome do tipo de produto da Amazon.
displayName Luggage A descrição localizada e legível por humanos do tipo de produto da Amazon.
marketplaceIds ATVPDKIKX0DER Lista de identificadores do site da Amazon para os quais o tipo de produto está disponível (dentro dos identificadores do site solicitados).
productTypeVersion UHqSqmb4FNUk= Os detalhes da versão do tipo de produto da Amazon.

Exemplo de resposta

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

Tutorial: Recuperar uma definição de tipo de produto

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

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

  • Autorização dos parceiros de vendas para os quais você está fazendo chamadas. Consulte Como autorizar aplicativos da API do parceiro de vendas para obter mais informações.

  • Aprovação para a função de oferta de produtos em seu perfil de desenvolvedor.

  • A função de oferta de produtos selecionada na página de registro do aplicativo para seu aplicativo.

Recupere a definição do tipo de produto

Chame a operação getDefinitionsProductType para recuperar uma definição de tipo de produto da Amazon a partir da API de definições de tipo de produto.

Parâmetros de solicitação

Parâmetros do caminho

Parâmetro Exemplo Descrição Obrigatório
productType LUGGAGE Nome do tipo de produto da Amazon.

Tipo: string

Sim

Parâmetros de consulta

Parâmetro Exemplo Descrição Obrigatório
sellerId AXXXXXXXXXXXXX O identificador do parceiro de vendas. Quando fornecido, os requisitos e valores específicos do vendedor são preenchidos no esquema de definição do tipo de produto, como nomes de marcas associadas ao parceiro de vendas.

Tipo: string

Não
marketplaceIds ATVPDKIKX0DER Lista delimitada por vírgulas de identificadores de mercado da Amazon.
Observação: no momento, esse parâmetro está limitado a um MarketplaceID.

Consulte IDs de mercado para obter a lista de identificadores de mercado da Amazon.

Tipo: < string > array(csv)

Sim
productTypeVersion U1d1eorqMs3U= 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 versão ao vivo LATEST será fornecida.

Padrão: LATEST

Tipo: string

Não
requirements LISTING Nome dos requisitos definidos para os quais recuperar os requisitos.

  • LISTING: requisitos que incluem fatos do produto e condições de venda.
  • LISTING_OFFER_ONLY: requisitos que incluem somente as condições de venda.
  • LISTING_PRODUCT_ONLY: requisitos que incluem apenas os fatos do produto.

Padrão: LISTING

Tipo: enum (Requirements)

Não
requirementsEnforced ENFORCED Identifica se os atributos necessários para um conjunto de requisitos são impostos pelo esquema de definição do tipo de produto. Requisitos não aplicados permitem a validação estrutural de atributos individuais sem que todos os atributos necessários estejam presentes (como para atualizações parciais).

  • ENFORCED: os 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)

Não
locale en_US Local para recuperar os detalhes da apresentação (rótulos e descrições). O padrão é a localidade principal do site da Amazon.

Padrão: DEFAULT

Tipo: enum (Locale)

Não

Exemplo de solicitaçã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:

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

Soma de verificação fornecida para comparação com documentos recuperados anteriormente.

Tipo: SchemaLink

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

Soma de verificação fornecida para comparação com documentos recuperados anteriormente.

Tipo: SchemaLink

requirements LISTING Nome do conjunto de requisitos ao qual a definição do tipo de produto da Amazon se aplica.

  • LISTING: requisitos que incluem fatos do produto e condições de venda.
  • LISTING_OFFER_ONLY: requisitos que incluem somente as condições de venda.
  • LISTING_PRODUCT_ONLY: requisitos que incluem apenas os fatos do produto.

Padrão: LISTING

Tipo: enum (Requirements)

requirementsEnforced ENFORCED Identifica se os atributos necessários para um conjunto de requisitos são impostos pelo esquema de definição do tipo de produto. Requisitos não aplicados permitem a validação estrutural de atributos individuais sem que todos os atributos necessários estejam presentes (como para atualizações parciais).

  • ENFORCED: os 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 das propriedades descritas no documento de esquema JSON de definição de tipo de produto da Amazon. Essas segmentações podem ser usadas para agrupar propriedades em interfaces de usuário, identificar a finalidade 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 > mapa

locale en_US A localidade dos detalhes da apresentação (rótulos e descrições) fornecidos no documento de esquema JSON de definição de tipo de produto da Amazon.

Tipo: enum (Locale)

marketplaceIds ATVPDKIKX0DER Identificadores do site da Amazon aos quais a definição do tipo de produto da Amazon é aplicável.

Tipo: < string > array

productType LUGGAGE O nome do tipo de produto da Amazon ao qual essa definição de tipo de produto se aplica.

Tipo: string

productTypeVersion U8L4z4Ud95N16tZlR7rsmbQ== Versão da definição do tipo de produto da Amazon.

Tipo: (ProductTypeVersion)

displayName Luggage A descrição localizada e legível por humanos do tipo de produto da Amazon.

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

Recupere os documentos do esquema

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

Os documentos do esquema podem ser recuperados programaticamente com um cliente HTTP padrão ou manualmente com um navegador da Web.

❗️

Os nomes dos meta-esquemas não podem ser resolvidos pela web

Observação importante: o documento do esquema JSON de definição de tipo de produto da Amazon faz referência ao metaesquema pelo nome. Algumas bibliotecas de esquema JSON tentam resolver nomes de metaesquemas on-line por meio da Web, o que o metaesquema de definição de tipo de produto da Amazon (v1) não suporta. Em vez disso, essas bibliotecas devem ser configuradas para usar uma cópia baixada do metaesquema. Consulte a documentação Metaesquema de definição de tipo de produto da Amazon (v1) em anexo para obter mais detalhes.

Perguntas frequentes

Esta documentação aborda perguntas e detalhes comuns sobre a API de definições de tipos de produtos. Em caso de dúvidas ou preocupações não abordadas nessa documentação, entre em contato com o suporte da API do parceiro de vendas ou abra uma solicitação no repositório do GitHub.

Quão atualizadas são as definições de tipo de produto da Amazon?

A menos que especifique um productTypeVersion anterior, as definições de tipo de produto da Amazon sempre descrevem os requisitos mais recentes e atualizados do catálogo da Amazon.

Todos os tipos de produtos da Amazon estão disponíveis com a API de definições de tipos de produtos?

A Amazon está expandindo continuamente o suporte para tipos de produtos novos e existentes da Amazon na API de definições de tipos de produtos. Para obter a lista atualizada dos tipos de produtos disponíveis da Amazon, use a API de definições de tipos de produtos.

Qual versão do esquema JSON é usada?

Os Esquemas JSON da definição do tipo de produto da Amazon estendem o Esquema JSON 2019-09. Veja a documentação Metaesquema de definição de tipos de produto da Amazon (v1) em anexo para obter mais detalhes.

Como as versões futuras do esquema JSON serão aproveitadas?

À medida que futuras versões do esquema JSON forem adotadas pela API de definições de tipos de produto, elas serão acompanhadas por uma nova versão da API de definições de tipos de produto e Metaesquema de definição de tipos de produto da Amazon.

Versões futuras do esquema JSON não serão adotadas pelas versões existentes da API de definições de tipos de produto ou pelo Metaesquema de definição de tipos de produto da Amazon.

Os esquemas JSON de definição de tipo de produto incluem vocabulário personalizado?

A maioria dos requisitos do catálogo da Amazon é descrita utilizando o vocabulário padrão do Esquema JSON 2019-09. No entanto, existem alguns requisitos que exigem a extensão do esquema JSON com vocabulário personalizado. Veja a documentação Metaesquema de definição de tipos de produto da Amazon (v1) em anexo para obter mais detalhes.

Preciso implementar a validação para vocabulário personalizado?

O metaesquema de definição de tipo de produto da Amazon (v1) usa vocabulário personalizado para descrever completamente os requisitos do catálogo da Amazon. A validação de dados com dados personalizados permite que você evite que a maioria dos problemas relacionados às ofertas ocorra antes de enviá-las para a Amazon. No entanto, cabe a você implementar essa validação. Se não implementá-la, poderá experimentar problemas após o envio de uma oferta para a Amazon.

Preciso de código personalizado para usar esquemas JSON?

A quantidade de código personalizado depende do seu aplicativo. Cenários de exemplo:

  • Uso de biblioteca de código aberto com validação de vocabulário personalizado: utilizar uma biblioteca de código aberto para fazer a maior parte da validação do esquema JSON significa que é necessário código personalizado para recuperar esquemas da API de definições de tipos de produto, implementar a validação de vocabulário personalizado e integrar à biblioteca de código aberto.

  • Uso de biblioteca de código aberto sem validação de vocabulário personalizado: utilizar uma biblioteca de código aberto para fazer a maior parte da validação do esquema JSON significa que é necessário código personalizado para recuperar esquemas da API de definições de tipos de produto e integrar à biblioteca de código aberto.

Quais bibliotecas de código aberto estão disponíveis?

Dezenas de bibliotecas e implementações de código aberto estão disponíveis para validar dados, renderizar interfaces de usuário e gerar código. Veja Implementações do esquema JSON para obter uma lista completa.

A Amazon não oferece suporte ou endossa diretamente nenhuma biblioteca ou implementação comercial ou de código aberto específica. Os exemplos fornecidos nesta documentação são apenas para referência.

Quais exemplos estão disponíveis para validar dados com esquemas de tipo de produto?

A documentação Metaesquema de definição de tipos de produto da Amazon (v1) em anexo inclui exemplos de integrações com bibliotecas de código aberto para validar dados com vocabulário personalizado em .NET (C#), Java e JavaScript (Node.js).

Como faço para relatar problemas com as definições de tipo de produto da Amazon?

Para questões específicas da API de definições de tipos de produto ou do conteúdo dos esquemas JSON de definição de tipos de produto da Amazon, entre em contato com o Suporte da API do parceiro de vendas.


Esta página ajudou você?