Guia de casos de uso da API de itens do catálogo v2022-04-01

Como usar a API de itens do catálogo.

Versão da API: 2022-04-01

O que é a API de itens do catálogo?

Usando a API do parceiro de vendas para itens do catálogo (API de itens do catálogo), você pode recuperar informações sobre os itens no catálogo da Amazon. Consulte Referência da API de itens do catálogo para obter detalhes sobre as operações de API e os tipos de dados e esquemas associados.

Principais recursos

  • Recupere informações detalhadas do item: a API de itens do catálogo fornece detalhes sobre itens no catálogo da Amazon, como

    • Detalhes resumidos do item
    • Atributos
    • Navegue pelas classificações
    • Dimensão
    • Identificadores de produto
    • Imagens
    • Classificações de vendas
    • Relacionamentos

Os fornecedores podem recuperar detalhes adicionais específicos do fornecedor.

  • Pesquise por identificadores ou palavras-chave. A API de itens do catálogo permite que você pesquise itens do catálogo da Amazon e informações associadas por identificadores (como identificadores UPC ou código EAN, até 20 por solicitação) ou por palavras-chave. Os mesmos detalhes do item estão disponíveis ao realizar uma consulta de pesquisa ou ao recuperar itens explicitamente pelo ASIN.

Terminologia

  • Código ASIN: número de identificação padrão da Amazon que identifica um item no catálogo da Amazon.

  • Código SKU: unidade de manutenção de estoque fornecida pelo parceiro de vendas que identifica uma oferta do vendedor ou fornecedor. Os dados de um ou mais anúncios de parceiros de vendas são reconciliados com itens no catálogo da Amazon.

  • Variação: as variações são um tipo de relacionamento entre os itens do catálogo da Amazon que agrupam itens que variam por cor, tamanho ou outros atributos. Um item principal do catálogo da Amazon é usado para agrupar os itens secundários na família de variações. Por exemplo, uma camisa pode ser oferecida em vários tamanhos e cores. Nesse cenário, cada combinação distinta de tamanho e cor é representada como seu próprio item no catálogo da Amazon com um produto (parent) que os agrupa para fornecer uma única página de detalhes nos sites de varejo da Amazon.

🚧

Manipulação de esquemas JSON genéricos em bibliotecas de cliente

Se você gerou uma biblioteca de clientes, é importante observar que o Swagger Codegen gera tipos com base nas propriedades definidas nos modelos Swagger e produzirá tipos vazios ou incompletos quando um objeto for definido com additionalProperties: true. Para lidar com esses objetos, use o parâmetro de linha de comando --import-mappings para mapeá-los para um tipo de objeto JSON genérico ou um tipo de objeto personalizado de sua escolha.

Exemplo de parâmetros de entrada do Swagger Codegen:

C#: --import-mappings ItemAttributes=Newtonsoft.Json.Linq.JObject
Java: --import-mappings ItemAttributes=com.google.gson.JsonObject

Tutorial: recupere detalhes de um item individual no catálogo da Amazon por meio de seu identificador (ASIN)

Use este tutorial para recuperar informações sobre um item no catálogo da Amazon relacionado a um determinado ASIN e marketplace.

Pré-requisitos

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

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

  • 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.

Etapa 1: obtenha informações sobre um item do catálogo

Chame a operação getCatalogItem, passando os seguintes parâmetros:

Parâmetros do caminho

Parâmetro Type Exemplo Descrição Obrigatório
asin string XXXXXXXXXX Número de identificação padrão da Amazon para o item de interesse. Sim

Parâmetros de consulta

Parâmetro Type Exemplo Descrição Obrigatório
marketplaceIds < string > array(csv) ATVPDKIKX0DER Uma lista delimitada por vírgulas dos identificadores do Site da Amazon.

Consulte IDs dos marketplaces para obter uma lista de identificadores do Site da Amazon.
Sim
includedData < enum (IncludedData) > array(csv) summaries Uma lista delimitada por vírgulas dos detalhes do item a serem solicitados. Se nenhum for especificado, o padrão será retornar dados de summaries.
  • attributes: atributos de itens listáveis. Disponível para o proprietário da marca do item. Contém todos os atributos de itens listáveis presentes no item para seu tipo de produto específico. Consulte a API de definições de tipos de produto para obter mais informações sobre como recuperar esquemas JSON que descrevem o formato dos atributos retornados.
  • classifications - Procure classificações (também chamadas de *nós* ou *categorias de produtos*).
  • dimensions: dimensões do item e da embalagem.
  • identifiers: identificadores externos de itens, como código EAN, UPC, ISBN etc.
  • images: imagens do produto. Cada imagem do produto conterá o nome da variante da imagem, a resolução e um link para baixar a imagem.
  • productTypes: tipo de produto do item. Os atributos e os requisitos de dados de um item são definidos por seu tipo de produto, que pode ser obtido usando a API de definições de tipos de produto.
  • relationships: dados de relacionamentos de itens. Contém listas de códigos ASIN que representam os itens principais ou secundários relacionados a esse item.
  • salesRanks: dados de classificação de vendas de itens. Cada classificação de vendas conterá o nome da categoria, a classificação do item e um link para a página de classificação de vendas no site de varejo.
  • summaries: resumo dos dados do item. Atributos básicos, como nome do item, fabricante e marca.
  • vendorDetails: dados do fornecedor do item. Disponível para fornecedores. Contém informações sobre reabastecimento de itens, marca e fabricante.
Não
locale string en_US Idioma para obter resumos localizados. O padrão é o idioma principal do marketplace. Não

Exemplo de solicitação:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items/XXXXXXXXXX ?marketplaceIds=ATVPDKIKX0DER &includedData=attributes,classifications,dimensions,identifiers,images,productTypes,salesRanks,summaries,relationships,vendorDetails

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome Type Descrição
asin ItemAsin O código ASIN solicitado.

attributes ItemAttributes Um objeto JSON contendo dados detalhados do item do catálogo. Os valores de vários mercados são agrupados em uma lista abaixo do nome de cada atributo.

Consulte o Guia de casos de uso da API de definições de tipos de produto para obter mais informações.

classifications ItemBrowseClassifications Procure classificações (também chamadas de *nós* ou *categorias de produtos*).
dimensions ItemDimensions Dimensões normalizadas do item e da embalagem.
identifiers ItemIdentifiers Identificadores externos, como UPC, EAN, se aplicável.
images ItemImages Dados de imagem do item.
productTypes ItemProductTypes O tipo de produto do item no catálogo da Amazon. Consulte a API de definições de tipos de produto para obter mais informações.
ranks ItemSalesRanks Os dados da classificação de vendas do item em todas as categorias em que ele é rastreado.
relationships ItemRelationships Listas de códigos ASIN que representam os itens principais e secundários relacionados a esse item.
summaries ItemSummaries Resumo dos dados do item.
vendorDetails ItemVendorDetails Informações detalhadas do fornecedor deste produto.

Exemplo de resposta:

{ "asin": "B07N4M94X4", "attributes": { "total_hdmi_ports": [ { "value": 4, "marketplace_id": "ATVPDKIKX0DER" } ], "resolution": [ { "language_tag": "en_US", "value": "4K", "marketplace_id": "ATVPDKIKX0DER" } ], "item_weight": [ { "unit": "pounds", "value": 107.6, "marketplace_id": "ATVPDKIKX0DER" } ], "product_subcategory": [ { "value": "50400120", "marketplace_id": "ATVPDKIKX0DER" } ], "bullet_point": [ { "language_tag": "en_US", "value": "SMART TV WITH UNIVERSAL GUIDE: Simple on-screen Guide is an easy way to find streaming content and live TV shows", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "100% COLOR VOLUME WITH QUANTUM DOTS: Powered by Quantum dots, Samsung’s 4K QLED TV offers over a billion shades of brilliant color and 100% color volume for exceptional depth of detail that will draw you in to the picture for the best 4K TV experience", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "QUANTUM PROCESSOR 4K: Intelligently powered processor instantly upscales content to 4K for sharp detail and refined color", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "QUANTUM HDR 4X: 4K depth of detail with high dynamic range powered by HDR10+ delivers the lightest to darkest colors, scene by scene, for amazing picture realism", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "AMBIENT MODE: Customizes and complements your living space by turning a blank screen of this big screen TV into enticing visuals including décor, info, photos and artwork", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "SMART TV FEATURES: OneRemote to control all compatible devices, Bixby voice command, on-screen universal guide, SmartThings to control compatible home appliances and devices, smart speaker expandability with Alexa and Google Assistant compatibility, and more", "marketplace_id": "ATVPDKIKX0DER" } ], "item_dimensions": [ { "width": { "unit": "inches", "value": 72.4 }, "length": { "unit": "inches", "value": 2.4 }, "height": { "unit": "inches", "value": 41.4 }, "marketplace_id": "ATVPDKIKX0DER" } ], "brand": [ { "language_tag": "en_US", "value": "SAMSUNG", "marketplace_id": "ATVPDKIKX0DER" } ], "control_method": [ { "value": "voice", "marketplace_id": "ATVPDKIKX0DER" } ], "item_package_dimensions": [ { "length": { "unit": "centimeters", "value": 26.67 }, "width": { "unit": "centimeters", "value": 121.92 }, "height": { "unit": "centimeters", "value": 203.2 }, "marketplace_id": "ATVPDKIKX0DER" } ], "image_aspect_ratio": [ { "language_tag": "en_US", "value": "16:9", "marketplace_id": "ATVPDKIKX0DER" } ], "part_number": [ { "value": "QN82Q60RAFXZA", "marketplace_id": "ATVPDKIKX0DER" } ], "includes_remote": [ { "value": true, "marketplace_id": "ATVPDKIKX0DER" } ], "style": [ { "language_tag": "en_US", "value": "TV only", "marketplace_id": "ATVPDKIKX0DER" } ], "item_type_name": [ { "language_tag": "en_US", "value": "TV", "marketplace_id": "ATVPDKIKX0DER" } ], "battery": [ { "cell_composition": [ { "value": "alkaline" } ], "marketplace_id": "ATVPDKIKX0DER" } ], "image_contrast_ratio": [ { "language_tag": "en_US", "value": "QLED 4K", "marketplace_id": "ATVPDKIKX0DER" } ], "manufacturer": [ { "language_tag": "en_US", "value": "Samsung", "marketplace_id": "ATVPDKIKX0DER" } ], "number_of_boxes": [ { "value": 1, "marketplace_id": "ATVPDKIKX0DER" } ], "total_usb_ports": [ { "value": 2, "marketplace_id": "ATVPDKIKX0DER" } ], "model_number": [ { "value": "QN82Q60RAFXZA", "marketplace_id": "ATVPDKIKX0DER" } ], "supplier_declared_dg_hz_regulation": [ { "value": "not_applicable", "marketplace_id": "ATVPDKIKX0DER" } ], "num_batteries": [ { "quantity": 2, "type": "aaa", "marketplace_id": "ATVPDKIKX0DER" } ], "california_proposition_65": [ { "compliance_type": "on_product_combined_cancer_reproductive", "marketplace_id": "ATVPDKIKX0DER" }, { "compliance_type": "chemical", "chemical_names": [ "di_2_ethylhexyl_phthalate_dehp" ], "marketplace_id": "ATVPDKIKX0DER" } ], "display": [ { "resolution_maximum": [ { "unit": "pixels", "language_tag": "en_US", "value": "3840 x 2160" } ], "size": [ { "unit": "inches", "value": 82 } ], "type": [ { "language_tag": "en_US", "value": "QLED" } ], "marketplace_id": "ATVPDKIKX0DER" } ], "item_name": [ { "language_tag": "en_US", "value": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility", "marketplace_id": "ATVPDKIKX0DER" } ], "list_price": [ { "currency": "USD", "value": 3799.99, "marketplace_id": "ATVPDKIKX0DER" } ], "batteries_required": [ { "value": false, "marketplace_id": "ATVPDKIKX0DER" } ], "includes_rechargable_battery": [ { "value": false, "marketplace_id": "ATVPDKIKX0DER" } ], "product_site_launch_date": [ { "value": "2019-03-11T08:00:01.000Z", "marketplace_id": "ATVPDKIKX0DER" } ], "product_category": [ { "value": "50400100", "marketplace_id": "ATVPDKIKX0DER" } ], "batteries_included": [ { "value": false, "marketplace_id": "ATVPDKIKX0DER" } ], "connectivity_technology": [ { "language_tag": "en_US", "value": "Bluetooth", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "USB", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Wireless", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "HDMI", "marketplace_id": "ATVPDKIKX0DER" } ], "included_components": [ { "language_tag": "en_US", "value": "QLED Standard Smart Remote", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Power Cable", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Stand", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Samsung Smart Control", "marketplace_id": "ATVPDKIKX0DER" } ], "specification_met": [ { "language_tag": "en_US", "value": "", "marketplace_id": "ATVPDKIKX0DER" } ], "parental_control_technology": [ { "value": "V-Chip", "marketplace_id": "ATVPDKIKX0DER" } ], "power_consumption": [ { "unit": "watts", "value": 120, "marketplace_id": "ATVPDKIKX0DER" } ], "cpsia_cautionary_statement": [ { "value": "no_warning_applicable", "marketplace_id": "ATVPDKIKX0DER" } ], "item_type_keyword": [ { "value": "qled-televisions", "marketplace_id": "ATVPDKIKX0DER" } ], "number_of_items": [ { "value": 1, "marketplace_id": "ATVPDKIKX0DER" } ], "warranty_description": [ { "language_tag": "en_US", "value": "1 year manufacturer", "marketplace_id": "ATVPDKIKX0DER" } ], "max_resolution": [ { "unit": "pixels", "value": 8.3, "marketplace_id": "ATVPDKIKX0DER" } ], "color": [ { "language_tag": "en_US", "value": "Black", "marketplace_id": "ATVPDKIKX0DER" } ], "screen_surface_description": [ { "language_tag": "en_US", "value": "Flat", "marketplace_id": "ATVPDKIKX0DER" } ], "item_package_weight": [ { "unit": "kilograms", "value": 62.142, "marketplace_id": "ATVPDKIKX0DER" } ], "speaker_type": [ { "language_tag": "en_US", "value": "2CH", "marketplace_id": "ATVPDKIKX0DER" } ], "supported_internet_services": [ { "language_tag": "en_US", "value": "Amazon Instant Video", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "YouTube", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Netflix", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Hulu", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Browser", "marketplace_id": "ATVPDKIKX0DER" } ], "tuner_technology": [ { "language_tag": "en_US", "value": "Analog Tuner", "marketplace_id": "ATVPDKIKX0DER" } ], "controller_type": [ { "language_tag": "en_US", "value": "SmartThings", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Voice Control", "marketplace_id": "ATVPDKIKX0DER" } ], "special_feature": [ { "language_tag": "en_US", "value": "100% Color Volume with Quantum Dot; Quantum Processor 4K; Ambient Mode; Quantum HDR 4X; Real Game Enhancer", "marketplace_id": "ATVPDKIKX0DER" } ], "wireless_communication_technology": [ { "language_tag": "en_US", "value": "Wi-Fi::Wi-Fi Direct::Bluetooth", "marketplace_id": "ATVPDKIKX0DER" } ], "model_year": [ { "value": 2019, "marketplace_id": "ATVPDKIKX0DER" } ], "power_source_type": [ { "language_tag": "en_US", "value": "Corded Electric", "marketplace_id": "ATVPDKIKX0DER" } ], "street_date": [ { "value": "2019-03-21T00:00:01Z", "marketplace_id": "ATVPDKIKX0DER" } ], "mounting_type": [ { "language_tag": "en_US", "value": "Table Mount", "marketplace_id": "ATVPDKIKX0DER" }, { "language_tag": "en_US", "value": "Wall Mount", "marketplace_id": "ATVPDKIKX0DER" } ], "refresh_rate": [ { "unit": "hertz", "language_tag": "en_US", "value": "120", "marketplace_id": "ATVPDKIKX0DER" } ] }, "classifications": [ { "marketplaceId": "ATVPDKIKX0DER", "classifications": [ { "displayName": "QLED TVs", "classificationId": "21489946011", "parent": { "displayName": "Televisions", "classificationId": "172659", "parent": { "displayName": "Television & Video", "classificationId": "1266092011", "parent": { "displayName": "Electronics", "classificationId": "172282" } } } } ] } ], "dimensions": [ { "marketplaceId": "ATVPDKIKX0DER", "item": { "height": { "unit": "inches", "value": 41.4 }, "length": { "unit": "inches", "value": 2.4 }, "weight": { "unit": "pounds", "value": 107.6 }, "width": { "unit": "inches", "value": 72.4 } }, "package": { "height": { "unit": "inches", "value": 10.49999998929 }, "length": { "unit": "inches", "value": 79.9999999184 }, "weight": { "unit": "kilograms", "value": 62.142 }, "width": { "unit": "inches", "value": 47.99999995104 } } } ], "identifiers": [ { "marketplaceId": "ATVPDKIKX0DER", "identifiers": [ { "identifier": "0887276302195", "identifierType": "EAN" }, { "identifier": "00887276302195", "identifierType": "GTIN" }, { "identifier": "887276302195", "identifierType": "UPC" } ] } ], "images": [ { "marketplaceId": "ATVPDKIKX0DER", "images": [ { "variant": "MAIN", "link": "https://m.media-amazon.com/images/I/91uohwV+k3L.jpg", "height": 1707, "width": 2560 }, { "variant": "MAIN", "link": "https://m.media-amazon.com/images/I/51DZzp3w3vL.jpg", "height": 333, "width": 500 }, { "variant": "PT01", "link": "https://m.media-amazon.com/images/I/81w2rTVShlL.jpg", "height": 2560, "width": 2560 }, { "variant": "PT01", "link": "https://m.media-amazon.com/images/I/41Px9eq9tkL.jpg", "height": 500, "width": 500 }, { "variant": "PT02", "link": "https://m.media-amazon.com/images/I/51NTNhdhPyL.jpg", "height": 375, "width": 500 }, { "variant": "PT03", "link": "https://m.media-amazon.com/images/I/51o4zpL+A3L.jpg", "height": 375, "width": 500 }, { "variant": "PT04", "link": "https://m.media-amazon.com/images/I/71ux2k9GAZL.jpg", "height": 1000, "width": 1000 }, { "variant": "PT04", "link": "https://m.media-amazon.com/images/I/61UUX63yw1L.jpg", "height": 500, "width": 500 }, { "variant": "PT05", "link": "https://m.media-amazon.com/images/I/61LwHkljX-L.jpg", "height": 1000, "width": 1000 }, { "variant": "PT05", "link": "https://m.media-amazon.com/images/I/51wJTQty3PL.jpg", "height": 500, "width": 500 }, { "variant": "PT06", "link": "https://m.media-amazon.com/images/I/61uvoB4VvoL.jpg", "height": 1000, "width": 1000 }, { "variant": "PT06", "link": "https://m.media-amazon.com/images/I/51ZexIO628L.jpg", "height": 500, "width": 500 }, { "variant": "PT07", "link": "https://m.media-amazon.com/images/I/7121MGd2ncL.jpg", "height": 1000, "width": 1000 }, { "variant": "PT07", "link": "https://m.media-amazon.com/images/I/61QK+JBMrGL.jpg", "height": 500, "width": 500 }, { "variant": "PT08", "link": "https://m.media-amazon.com/images/I/61ECcGlG4IL.jpg", "height": 1080, "width": 1920 }, { "variant": "PT08", "link": "https://m.media-amazon.com/images/I/31TxwfqvB5L.jpg", "height": 281, "width": 500 }, { "variant": "PT09", "link": "https://m.media-amazon.com/images/I/41B5vgmp4IL.jpg", "height": 375, "width": 500 }, { "variant": "PT10", "link": "https://m.media-amazon.com/images/I/51S5IY3AV0L.jpg", "height": 375, "width": 500 }, { "variant": "PT11", "link": "https://m.media-amazon.com/images/I/41-6bmPtUlL.jpg", "height": 375, "width": 500 }, { "variant": "PT12", "link": "https://m.media-amazon.com/images/I/41s9Q6gWJ7L.jpg", "height": 448, "width": 500 }, { "variant": "PT13", "link": "https://m.media-amazon.com/images/I/519nG0mRzuL.jpg", "height": 314, "width": 500 }, { "variant": "PT14", "link": "https://m.media-amazon.com/images/I/71sHhrGMc7L.jpg", "height": 1097, "width": 1500 }, { "variant": "PT14", "link": "https://m.media-amazon.com/images/I/41CH6gKtU5L.jpg", "height": 366, "width": 500 }, { "variant": "PT15", "link": "https://m.media-amazon.com/images/I/21-s7QYrTxL.jpg", "height": 500, "width": 175 }, { "variant": "EEGL", "link": "https://m.media-amazon.com/images/I/61i3dsKD09L.jpg", "height": 1375, "width": 370 }, { "variant": "EEGL", "link": "https://m.media-amazon.com/images/I/41E7ku-qdGL.jpg", "height": 500, "width": 135 }, { "variant": "EGUS", "link": "https://m.media-amazon.com/images/I/61i3dsKD09L.jpg", "height": 1375, "width": 370 }, { "variant": "EGUS", "link": "https://m.media-amazon.com/images/I/41E7ku-qdGL.jpg", "height": 500, "width": 135 } ] } ], "productTypes": [ { "marketplaceId": "ATVPDKIKX0DER", "productType": "TELEVISION" } ], "salesRanks": [ { "marketplaceId": "ATVPDKIKX0DER", "classificationRanks": [ { "classificationId": "21489946011", "title": "QLED TVs", "link": "http://www.amazon.com/gp/bestsellers/electronics/21489946011", "rank": 113 } ], "displayGroupRanks": [ { "websiteDisplayGroup": "ce_display_on_website", "title": "Electronics", "link": "http://www.amazon.com/gp/bestsellers/electronics", "rank": 72855 } ] } ], "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "SAMSUNG", "browseClassification": { "displayName": "QLED TVs", "classificationId": "21489946011" }, "color": "Black", "itemClassification": "BASE_PRODUCT", "itemName": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility", "manufacturer": "Samsung", "modelNumber": "QN82Q60RAFXZA", "packageQuantity": 1, "partNumber": "QN82Q60RAFXZA", "size": "82-Inch", "style": "TV only", "websiteDisplayGroup": "ce_display_on_website" } ], "relationships": [ { "marketplaceId": "ATVPDKIKX0DER", "relationships": [ { "type": "VARIATION", "parentAsins": [ "B08J7TQ9FL" ], "variationTheme": { "attributes": [ "color", "size" ], "theme": "SIZE_NAME/COLOR_NAME" } } ] } ], "vendorDetails": [ { "marketplaceId": "ATVPDKIKX0DER", "brandCode": "SAMF9", "manufacturerCode": "SAMF9", "manufacturerCodeParent": "SAMF9", "productCategory": { "displayName": "Televisions", "value": "50400100" }, "productGroup": "Home Entertainment", "productSubcategory": { "displayName": "Plasma TVs", "value": "50400120" }, "replenishmentCategory": "OBSOLETE" } ] }

Tutorial: pesquise um ou mais itens por códigos ASIN ou identificadores de produto

Use este tutorial para recuperar informações sobre vários itens no catálogo da Amazon para os códigos ASIN ou identificadores de produto fornecidos.

Pré-requisitos

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

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

  • 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.

Etapa 1: pesquise itens

Chame a operação searchCatalogItems com os seguintes parâmetros:

Parâmetros de consulta

Parâmetro Type Exemplo Descrição Obrigatório
identifiers < string > array(csv) 0887276302195 Uma lista delimitada por vírgulas de identificadores de produtos a pesquisar no catálogo da Amazon. Observação: não pode ser usado com keywords. Não
identifiersType string ISBN Tipo de identificadores de produto a pesquisar no catálogo da Amazon. Observação: é necessário quando identifiers são fornecidos.
  • ASIN: Amazon Standard Identification Number (número de identificação padrão da Amazon).
  • EAN: European Article Number (número de artigo europeu).
  • GTIN: Global Trade Item Number (número global do item comercial).
  • ISBN: International Standard Book Number (número padrão internacional para livros).
  • JAN: Japanese Article Number (número de artigo japonês).
  • MINSAN: código Minsan.
  • SKU: unidade de manutenção de estoque.
  • UPC: códigos de produto exclusivos.
Não
marketplaceIds < string > array(csv) ATVPDKIKX0DER Uma lista delimitada por vírgula dos identificadores do Site da Amazon para a solicitação. Sim
includedData < enum (IncludedData) > array(csv) summaries Uma lista delimitada por vírgulas dos detalhes do item a serem solicitados. Se nenhum for especificado, o padrão será retornar dados de summaries.
  • attributes: atributos de itens listáveis. Disponível para o proprietário da marca do item. Contém todos os atributos de itens listáveis presentes no item para seu tipo de produto específico. Consulte a API de definições de tipos de produto para obter mais informações sobre como recuperar esquemas JSON que descrevem o formato dos atributos retornados.
  • classifications - Procure classificações (também chamadas de *nós* ou *categorias de produtos*).
  • dimensions: dimensões do item e da embalagem.
  • identifiers: identificadores externos de itens, como código EAN, UPC, ISBN etc.
  • images: imagens do produto. Cada imagem do produto conterá o nome da variante da imagem, a resolução e um link para baixar a imagem.
  • productTypes: tipo de produto do item. Os atributos e os requisitos de dados de um item são definidos por seu tipo de produto, que pode ser obtido usando a API de definições de tipos de produto.
  • relationships: dados de relacionamentos de itens. Contém listas de códigos ASIN que representam os itens principais ou secundários relacionados a esse item.
  • salesRanks: dados de classificação de vendas de itens. Cada classificação de vendas conterá o nome da categoria, a classificação do item e um link para a página de classificação de vendas no site de varejo.
  • summaries: resumo dos dados do item. Atributos básicos, como nome do item, fabricante e marca.
  • vendorDetails: dados do fornecedor do item. Disponível para fornecedores. Contém informações sobre reabastecimento de itens, marca e fabricante.
Não
locale string
en_US Idioma para obter resumos localizados. O padrão é o idioma principal do marketplace. Não
sellerId string XXXXXXXXXXXX Um identificador do parceiro de vendas, como uma conta de vendedor ou código de fornecedor. Observação: é necessário quando identifiersType é SKU. Não
pageSize número inteiro 10 Número de resultados a serem retornados por página. Não
pageToken string Um token para buscar uma determinada página quando há várias páginas de resultados. Não

Use o parâmetro pageToken para paginar os resultados. Veja mais informações em Paginação na resposta a uma pesquisa por itens no catálogo da Amazon.

Exemplo de solicitação:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items ?identifiers=XXXXXXXXX,YYYYYYYY,ZZZZZZZZ &identifiersType=ASIN &marketplaceIds=ATVPDKIKX0DER

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome Type Descrição
numberOfResults número inteiro O número total de produtos correspondidos pela consulta de pesquisa. Somente resultados até o limite de contagem de páginas serão retornados por solicitação, independentemente do número encontrado.
pagination Pagination Um objeto JSON contendo um ou mais tokens de página que podem ser usados para buscar a próxima página de resultados ou a anterior.
items matriz < Item > Uma lista de itens do catálogo da Amazon. As informações incluídas para cada item dependem do argumento apresentado para includedData. Consulte a Referência da API de itens do catálogo para obter mais informações.

Exemplo de resposta:

{ "numberOfResults": 3, "items": [ { "asin": "XXXXXXXXXX", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Fred Perry", "color": "Wht/Brt Red/Nvy", "itemClassification": "BASE_PRODUCT", "itemName": "Fred Perry Men's Twin Tipped Polo Shirt-M1200, WHT/BRT RED/NVY, X-Large", "manufacturer": "Fred Perry Men's Apparel", "modelNumber": "M1200", "packageQuantity": 1, "partNumber": "M1200-748", "size": "X-Large", "style": "Twin Tipped Polo Shirt-m1200", "websiteDisplayGroup": "apparel_display_on_website" } ] }, { "asin": "YYYYYYYYYYY", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Universal", "itemClassification": "BASE_PRODUCT", "itemName": "Dr. Seuss' The Lorax", "manufacturer": "Universal", "modelNumber": "ALE BOOK", "packageQuantity": 1, "partNumber": "MCAD61118810D", "websiteDisplayGroup": "dvd_display_on_website" } ] }, { "asin": "ZZZZZZZZZZZ", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Muck Boot", "itemClassification": "VARIATION_PARENT", "itemName": "Muck Boot Women's Muckster 2 Ankle Snow Boot, black", "manufacturer": "Muck Boot", "style": "Muckster 2 Ankle", "websiteDisplayGroup": "shoes_display_on_website" } ] } ] }

Tutorial: pesquise itens por palavras-chave

Pesquise e retorne uma lista de itens do catálogo da Amazon e informações associadas por identificador ou por palavras-chave.

Pré-requisitos

Para concluir este tutorial com sucesso, você deve ter:

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

  • 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.

Etapa 1: pesquise itens

Chame a operação searchCatalogItems com os seguintes parâmetros:

Parâmetros de consulta

Parâmetro Type Exemplo Descrição Obrigatório
brandNames < string > array(csv) Samsung Uma lista delimitada por vírgulas de nomes de marcas para refinar os resultados da pesquisa. Não
classificationIds < string > array(csv) 7141124011 Uma lista delimitada por vírgulas de identificadores de classificação para refinar os resultados da pesquisa. Não
keywords < string > array(csv) hello Uma lista de palavras-chave delimitadas por vírgulas a pesquisar no catálogo da Amazon. Observação: não pode ser usada com identifiers. Não
keywordsLocale string en_US Idioma das palavras-chave fornecidas, o padrão é o idioma do marketplace. Não
marketplaceIds < string > array(csv) ATVPDKIKX0DER Uma lista delimitada por vírgula dos identificadores do Site da Amazon para a solicitação. Sim
includedData < enum (IncludedData) > array(csv) summaries Uma lista delimitada por vírgulas dos detalhes do item a serem solicitados. Se nenhum for especificado, o padrão será retornar dados de summaries.
  • attributes: atributos de itens listáveis. Disponível para o proprietário da marca do item. Contém todos os atributos de itens listáveis presentes no item para seu tipo de produto específico. Consulte a API de definições de tipos de produto para obter mais informações sobre como recuperar esquemas JSON que descrevem o formato dos atributos retornados.
  • classifications - Procure classificações (também chamadas de *nós* ou *categorias de produtos*).
  • dimensions: dimensões do item e da embalagem.
  • identifiers: identificadores externos de itens, como código EAN, UPC, ISBN etc.
  • images: imagens do produto. Cada imagem do produto conterá o nome da variante da imagem, a resolução e um link para baixar a imagem.
  • productTypes: tipo de produto do item. Os atributos e os requisitos de dados de um item são definidos por seu tipo de produto, que pode ser obtido usando a API de definições de tipos de produto.
  • relationships: dados de relacionamentos de itens. Contém listas de códigos ASIN que representam os itens principais ou secundários relacionados a esse item.
  • salesRanks: dados de classificação de vendas de itens. Cada classificação de vendas conterá o nome da categoria, a classificação do item e um link para a página de classificação de vendas no site de varejo.
  • summaries: resumo dos dados do item. Atributos básicos, como nome do item, fabricante e marca.
  • vendorDetails: dados do fornecedor do item. Disponível para fornecedores. Contém informações sobre reabastecimento de itens, marca e fabricante.
Não
locale string
en_US Idioma para obter resumos localizados. O padrão é o idioma principal do marketplace. Não
sellerId string XXXXXXXXXXXX Um identificador do parceiro de vendas, como uma conta de vendedor ou código de fornecedor. Observação: é necessário quando identifiersType é SKU. Não
pageSize número inteiro 10 Número de resultados a serem retornados por página. Não
pageToken string Refer to the nextToken no exemplo de resposta. Um token para buscar uma determinada página quando há várias páginas de resultados. Não

Use o parâmetro pageToken para paginar os resultados. Veja mais informações em Paginação na resposta a uma pesquisa por itens no catálogo da Amazon.

Exemplo de solicitação:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items ?keywords=hello &marketplaceIds={{marketplaceIds}} &includedData=summaries &pageSize=10

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome Type Descrição
numberOfResults número inteiro O número total de produtos correspondidos pela consulta de pesquisa. Somente resultados até o limite de contagem de páginas serão retornados por solicitação, independentemente do número encontrado.
items matriz < Item > Uma lista de itens do catálogo da Amazon. As informações incluídas para cada item dependem do argumento apresentado para includedData. Consulte a Referência da API de itens do catálogo para obter mais informações.
pagination Pagination Um objeto JSON contendo um ou mais tokens de página que podem ser usados para buscar a próxima página de resultados ou a anterior.
refinements Refinements Um objeto JSON contendo refinamentos de pesquisa de marca e classificação.

Exemplo de resposta:

{ "numberOfResults": 1000, "pagination": { "nextToken": "9HkIVcuuPmX_bm51o3-igBfN45pxW4Ru7ElIM6GCECYCuXJKzT26f5Rj4j72myj91jtjou695yNwt_JvE7qiRtfLOKtyb2IDTpSxcFmiJaztoxrP6fPkv2x86yf7CWqwS7VtDkxYifP8CHvJEnH2oh1l1vj7KQoFIa7pWiOPHyaYWP7sBE9Fg7cGN2wE0an5ePw96h6ZL7m6olRxFOcqTWNanEVRjipq" }, "refinements": { "brands": [ { "numberOfResults": 328, "brandName": "Hello Kitty" }, { "numberOfResults": 139, "brandName": "Brand TOTOX" }, { "numberOfResults": 101, "brandName": "Sanrio" }, { "numberOfResults": 79, "brandName": "Vans" }, { "numberOfResults": 73, "brandName": "Commonwealth Editions" }, { "numberOfResults": 42, "brandName": "Webstore" }, { "numberOfResults": 38, "brandName": "Unknown" }, { "numberOfResults": 38, "brandName": "Web Store" }, { "numberOfResults": 37, "brandName": "FOCO" }, { "numberOfResults": 30, "brandName": "Skinit" } ], "classifications": [ { "numberOfResults": 859, "displayName": "Books", "classificationId": "1000" }, { "numberOfResults": 595, "displayName": "Clothing, Shoes & Jewelry", "classificationId": "7141124011" }, { "numberOfResults": 371, "displayName": "Home & Kitchen", "classificationId": "1063498" }, { "numberOfResults": 233, "displayName": "Toys & Games", "classificationId": "165795011" }, { "numberOfResults": 197, "displayName": "CDs & Vinyl", "classificationId": "301668" }, { "numberOfResults": 156, "displayName": "Baby Products", "classificationId": "165797011" }, { "numberOfResults": 153, "displayName": "Everything Else", "classificationId": "10304191" }, { "numberOfResults": 134, "displayName": "Electronics", "classificationId": "493964" }, { "numberOfResults": 125, "displayName": "Sports & Outdoors", "classificationId": "3375301" }, { "numberOfResults": 123, "displayName": "Movies & TV", "classificationId": "2625374011" } ] }, "items": [ { "asin": "B0013OMKRI", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "HELLO KITTY KT2052A Alarm Clock Radio with Night Light (Discontinued by Manufacturer)", "manufacturer": "HELLO KITTY", "modelNumber": "KT2052A", "packageQuantity": 1, "partNumber": "KT2052A", "websiteDisplayGroup": "ce_display_on_website" } ] }, { "asin": "B0015ESWHI", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "HELLO KITTY KT2053 AM/FM Stereo Alarm Clock Radio with Top Loading CD Player", "manufacturer": "HELLO KITTY", "modelNumber": "KT2053", "packageQuantity": 1, "partNumber": "KT2053", "websiteDisplayGroup": "ce_display_on_website" } ] }, { "asin": "B009NIYBCS", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "color": "Pink/White", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Kitty Ladies Golf Glove Set, Pink/White, 20cm", "manufacturer": "Hello Kitty Golf", "modelNumber": "GLOVE-HKG.M", "size": "20cm", "websiteDisplayGroup": "sports_display_on_website" } ] }, { "asin": "B002W7RDMM", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "HELLO KITTY KT2054 Projection Clock Radio (Discontinued by Manufacturer)", "manufacturer": "HELLO KITTY", "modelNumber": "KT2054", "packageQuantity": 1, "partNumber": "KT2054", "websiteDisplayGroup": "ce_display_on_website" } ] }, { "asin": "B00FFECUDQ", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Kitty Coffee Maker", "manufacturer": "Sakar Intl", "modelNumber": "APP-36209", "packageQuantity": 1, "style": "Coffee Maker", "websiteDisplayGroup": "kitchen_display_on_website" } ] }, { "asin": "1534418717", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Robots! (A Hello Book)", "manufacturer": "Little Simon", "websiteDisplayGroup": "book_display_on_website" } ] }, { "asin": "B001E0L3MO", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "HELLO KITTY 12009 Keychain Photo Frame", "manufacturer": "HELLO KITTY", "modelNumber": "12009", "packageQuantity": 1, "partNumber": "12009", "websiteDisplayGroup": "photo_display_on_website" } ] }, { "asin": "B00021HBU4", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Kitty - 2-Slice Wide slot toaster with cool Touch Exterior", "modelNumber": "KT5211", "packageQuantity": 1, "partNumber": "KT5211", "websiteDisplayGroup": "speakers_display_on_website" } ] }, { "asin": "B010VIOD0S", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Kitty School Bus Playset", "manufacturer": "Jada Toys - US", "modelNumber": "96981", "packageQuantity": 1, "partNumber": "96981", "websiteDisplayGroup": "toy_display_on_website" } ] }, { "asin": "B074NHRVD6", "summaries": [ { "marketplaceId": "ATVPDKIKX0DER", "brand": "Hello Kitty", "color": "Coral/Gold", "itemClassification": "BASE_PRODUCT", "itemName": "Hello Kitty 女童装饰短裙, 6, 珊瑚色", "manufacturer": "Hello Kitty", "modelNumber": "K3088751AM", "packageQuantity": 1, "partNumber": "K3088751AM-813-6", "size": "6", "style": "Hello Kitty Girls Embellished Tutu Dress", "websiteDisplayGroup": "apparel_display_on_website" } ] } ] }

Paginação na resposta a uma pesquisa por itens no catálogo da Amazon

Quando uma chamada para a operação searchCatalogItems produz uma resposta que excede pageSize, a paginação ocorre. Isso significa que a resposta é dividida em páginas individuais, em que cada página é retornada em chamadas sucessivas. Para recuperar a próxima página ou a página anterior, você deve passar o valor nextToken ou o valor previousToken como o parâmetro pageToken na próxima solicitação.

Você obtém a primeira página de resultados ao chamar a operação searchCatalogItems sem fornecer um token de página. Em seguida, você percorre o restante das páginas usando o token de página nextToken fornecido em respostas sucessivas.

Os tokens de página são valores especiais que são decodificados para determinar qual página é solicitada e quantas páginas estão antes ou depois.

Se a página seguinte ou anterior não estiver disponível, o atributo de token de página correspondente (nextToken ou previousToken, respectivamente) não estará presente no objeto pagination.

Exemplos:

Quando a resposta não excede o pageSize, não há paginação, então não há nextToken ou previousToken:

"pagination": { },

Quando a resposta excede o pageSize e a paginação ocorre:

Para a primeira página, não há página anterior, então não há previousToken:

"pagination": { "nextToken": "XXXXXX" },

Para a última página, não há próxima página, então não há nextToken:

"pagination": { "previousToken": "XXXXXX" },

Para todas as outras páginas:

"pagination": { "nextToken": "XXXXXX", "previousToken": "XXXXXX" },

📘

Observação

Os tokens de página são específicos da solicitação. Você não pode alterar o tamanho da página na próxima solicitação ao usar um token de página.

Observação: embora possa haver mais de 1.000 códigos ASIN que correspondam aos critérios de pesquisa, o número máximo de resultados que podem ser retornados e paginados é de 1.000. Por exemplo, se o chamador definir o pageSize para 10, o número máximo de páginas possíveis será 100.


Esta página ajudou você?