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
eeditable
. 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 Tipo: enum ( |
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 Tipo: enum ( |
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: Tipo: enum ( |
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: |
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: |
requirements |
LISTING |
Nome do conjunto de requisitos ao qual a definição do tipo de produto da Amazon se aplica.
LISTING Tipo: enum ( |
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 Tipo: enum ( |
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, |
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 ( |
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: ( |
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.
Updated 23 days ago