Guia de uso
Introdução a API
O que é a API de catálogos?
Usando a API de parceiro de venda 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 a Referência da API de itens do catálogo para obter detalhes sobre as operações da API e os tipos de dados e esquemas associados.
Características principais
- Recuperar informações detalhadas do item: A API de itens do catálogo fornece detalhes sobre os itens no catálogo da Amazon, como detalhes resumidos do item, identificadores de produto, classificações de vendas, variações e imagens em miniatura. Os fornecedores podem obter detalhes adicionais específicos do fornecedor e os proprietários das marcas dos itens podem obter atributos adicionais e conteúdo de imagem.
- Pesquisar por itens: A API de itens do catálogo permite que você pesquise no catálogo da Amazon por itens existentes usando palavras-chave, incluindo identificadores de produto.
Termos usados
- ASIN: Número de identificação padrão da Amazon que identifica um item no catálogo da Amazon. * Variação: cada cor ou tamanho de um item do catálogo representa uma variação que é atribuída a um ASIN diferente. Eles são agrupados como variações de um ASIN pai.
Recuperar detalhes de um item no catálogo da Amazon
Tutorial
Use este tutorial para recuperar informações sobre um item no catálogo da Amazon para o ASIN e mercados fornecidos.
Pré-requisitos
Para concluir este tutorial, você precisará de:
- Autorização do parceiro de vendas para o qual você está fazendo ligações. Consulte o Selling Partner API Developer Guide para obter mais informações.
- Aprovação para a função da lista de produtos em seu perfil de desenvolvedor.
- A função da lista de produtos selecionada na página de registro do aplicativo para seu aplicativo.
1: Obtenha informações sobre um item do catálogo
Faça uma chamada em getCatalogItem, passando os seguintes parâmetros:
Path
Valor | Descrição |
---|---|
asin Obrigatório Tipo: String | Número de identificação padrão da Amazon para o item de interesse. Exemplo: 7896311762446 |
Query
Valor | Descrição |
---|---|
marketplaceIds Obrigatório Tipo: < String > array(csv) | Uma lista delimitada por vírgulas de identificadores de mercado da Amazon. Consulte o Bem-vindo a SP-API para obter a lista de identificadores do mercado Amazon. Exemplo: ATVPDKIKX0DER |
includedData Opcional Tipo: < enum (IncludedData) > array(csv) | Uma lista delimitada por vírgulas de detalhes do item a solicitar. Se nenhum for especificado, o padrão será summaries .Exemplo: summaries |
locale Opcional Tipo: String | Retorne resultados neste idioma, se disponível. Se este parâmetro não for especificado, os resultados serão retornados no idioma padrão do marketplace. Exemplo: 'pt_BR' |
https://sellingpartnerapi-na.amazon.com/catalog/2020-12-01/items/XXXXXXXXXX?marketplaceIds=ATVPDKIKX0DER
&includedData=attributes,identifiers,images,productTypes,salesRanks,summaries,variations,vendorDetails
Valor | Descrição |
---|---|
asin Tipo: ItemAsin | O ASIN solicitado. |
attributes Tipo: ItemAttributes | Um objeto JSON contendo dados detalhados do item do catálogo. Os valores de vários mercados são agrupados em uma lista sob cada nome de atributo. |
identifiers Tipo: ItemIdentifiers | Identificadores externos, como UPC, EAN, etc., se aplicável. |
images Tipo: ItemImages | Dados de imagem para o item. |
productTypes Tipo: ItemProductTypes | A categoria de tipo de produto do item no catálogo da Amazon. |
ranks Tipo: ItemSalesRanks | Os dados de classificação de vendas do item em cada categoria em que é rastreado. |
summaries Tipo: ItemSummaries | Resumo dos dados do item. |
variations Tipo: ItemVariations | Outros ASINs relacionados a este e se este é um ASIN pai ou filho ASIN. |
vendorDetails Tipo: ItemVendorDetails | Informações detalhadas do fornecedor para este produto. |
{
"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": "50400150",
"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 Electronics",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"generic_keyword": [
{
"language_tag": "en_US",
"value": "smart tv; 4k tv; roku tv ;lg tv; oled tv; 65 inch smart tv; 4k tv 65 inch; lg smart tv; nvidia shield tv 2018; tv 4k; oled tv 65; sony 4k tv; 4k smart tv; 4k hdr tv; nvidia shield tv; gaming tv; lg 65 inch 4k tv; tv 65 inch smart tv 4k; 65 inch 4k tv; sony 65 inch 4k tv; vizio 4k tv; uhd tv; uhd tv 4k",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "lg oled; 65 inch smart tv; samsung qled 75 inch tv; 85 inch 4k tv; lg smart tv; 4k tv 65 inch; samsung qled 82 inch tv; 8k tv; lg oled 65; lg smart tv; qled samsung 65 inch; 80 inch tv 4k; sony 4k tv; nvidia shield tv 2018",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "samsung q9fn qled 2018; vizio; lg oled; lg 4k; sony 4k; sony oled; toshiba; antenna; dvd player; outdoor tv; kitchen tv; fire tv; firetv; hdtv; hd tv; android; shield tv; gaming; deals; tv ears; roku; dvr; speakers; digital tv antenna; apple tv; android tv; frame; mount",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "4k hdr tv; 70" tv; nvidia shield tv; 90 inch tv; gaming tv; 75" tv; lg 65 inch 4k tv; tv 65 inch smart tv 4k; 65 inch 4k tv; sony 65 inch 4k tv; vizio 4k tv; uhd tv; uhd tv 4k;",
"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"
}
],
"item_type_name": [
{
"language_tag": "en_US",
"value": "TV",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"battery": [
{
"cell_composition": [
{
"value": "alkaline"
}
],
"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"
}
],
"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"
}
],
"item_package_weight": [
{
"unit": "kilograms",
"value": 62.142,
"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"
}
],
"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"
}
],
"refresh_rate": [
{
"unit": "hertz",
"language_tag": "en_US",
"value": "120",
"marketplace_id": "ATVPDKIKX0DER"
}
]
},
"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/51DZzp3w3vL.jpg",
"height": 333,
"width": 500
}
]
}
],
"productTypes": [
{
"marketplaceId": "ATVPDKIKX0DER",
"productType": "TELEVISION"
}
],
"ranks": [
{
"marketplaceId": "ATVPDKIKX0DER",
"ranks": [
{
"title": "Electronics",
"link": "http://www.amazon.com/gp/bestsellers/electronics",
"value": 61667
},
{
"title": "QLED TVs",
"link": "http://www.amazon.com/gp/bestsellers/electronics/21489946011",
"value": 84
}
]
}
],
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "Samsung Electronics",
"colorName": "Black",
"itemName": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility",
"manufacturer": "Samsung",
"modelNumber": "QN82Q60RAFXZA",
"sizeName": "82-Inch",
"styleName": "TV only"
}
],
"variations": [
{
"marketplaceId": "ATVPDKIKX0DER",
"asins": [
"B08J7TQ9FL"
],
"variationType": "CHILD"
}
],
"vendorDetails": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandCode": "SAMF9",
"categoryCode": "50400100",
"manufacturerCode": "SAMF9",
"manufacturerCodeParent": "SAMF9",
"productGroup": "Home Entertainment",
"replenishmentCategory": "OBSOLETE",
"subcategoryCode": "50400150"
}
]
}
Pesquise por itens no catálogo da Amazon
Tutorial
Use este tutorial para recuperar informações sobre um item no catálogo da Amazon para o ASIN e mercados fornecidos.
Pré-requisitos
Para concluir este tutorial, você precisará de:
- Autorização do parceiro de vendas para o qual você está fazendo ligações. Consulte o Selling Partner API Developer Guide para obter mais informações.
- Aprovação para a função da lista de produtos em seu perfil de desenvolvedor.
- A função da lista de produtos selecionada na página de registro do aplicativo para seu aplicativo.
1: Obtenha uma lista de itens do catálogo e informações associadas
Para pesquisar e retornar uma lista de itens do catálogo com as informações associadas opcionais que você especifica, faça a chamada em searchCatalogItems.
Query
Valor | Descrição |
---|---|
keywords Obrigatório Tipo: < String > array(csv) | Uma lista delimitada por vírgulas de palavras ou identificadores de itens para pesquisar no catálogo da Amazon. Exemplo: shoes |
marketplaceIds Obrigatório Tipo: < String > array(csv) | Uma lista delimitada por vírgulas de identificadores de mercado da Amazon. Consulte o Bem-vindo a SP-API para obter a lista de identificadores do mercado Amazon. Exemplo: ATVPDKIKX0DER |
includedData Opcional Tipo: < enum (IncludedData) > array(csv) | Uma lista delimitada por vírgulas de detalhes do item a solicitar. Se nenhum for especificado, o padrão será summaries .Exemplo: summaries |
brandNames Opcional Tipo: < String > array(csv) | Uma lista delimitada por vírgulas de nomes de marcas para limitar a pesquisa. Exemplo: 'Beautiful Boats' |
classificationIds Opcional Tipo: < String > array(csv) | Uma lista delimitada por vírgulas de identificadores de classificação aos quais limitar a pesquisa. Exemplo: 12345678 |
pageSize Opcional Tipo: Integer | Número de resultados a serem retornados por página. Exemplo: 9 (Por padrão 10) |
pageToken Opcional Tipo: String | Um token para buscar uma determinada página quando houver várias páginas com resultados. |
keywordsLocale Opcional Tipo: String | O idioma no qual as palavras-chave são fornecidas. As palavras-chave serão traduzidas para o local da resposta para pesquisa, se as duas forem diferentes. Exemplo: pt-BR |
locale Opcional Tipo: String | Retorne resultados neste idioma, se disponível. Se este parâmetro não for especificado, os resultados serão retornados no idioma padrão do marketplace. Exemplo: pt-BR |
https://sellingpartnerapi-na.amazon.com/catalog/2020-12-01/items
?keywords=red,polo,shirt
&marketplaceIds=ATVPDKIKX0DER
&includedData=summaries
&pageSize=5
Valor | Descrição |
---|---|
numberOfResults Tipo: Integer | O número total de produtos correspondidos pela consulta de pesquisa (apenas os resultados até o limite de contagem de páginas serão retornados por solicitação, independentemente do número encontrado). Exemplo: 3097 |
pagination Tipo: Pagination | Um objeto JSON contendo um ou mais tokens de página que podem ser usados para buscar a página de resultados seguinte ou anterior. |
refinements Tipo: Refinements | Um objeto JSON contendo chaves que podem ser usadas para refinar os resultados da pesquisa para certas marcas ou categorias. |
items Tipo: < Item > array | Uma lista de itens do catálogo da Amazon. |
{
"numberOfResults": 12247,
"pagination": {
"nextToken": "9HkIVcuuPmX_bm51o3-igBfN45pxW4Ru7ElIM6GCECYCuXJKzT26f-AlJJZYjIPp8wkOEmQdma1wt_JvE7qiRmNsKy7hH"
},
"refinements": {
"brands": [
{
"numberOfResults": 91,
"brandName": "Polo Ralph Lauren"
},
{
"numberOfResults": 79,
"brandName": "Eddie Bauer"
},
{
"numberOfResults": 46,
"brandName": "Cutter & Buck"
},
{
"numberOfResults": 39,
"brandName": "FILA"
},
{
"numberOfResults": 37,
"brandName": "Orvis"
}
],
"classifications": [
{
"numberOfResults": 1243,
"displayName": "Clothing, Shoes & Jewelry",
"classificationId": "7141124011"
},
{
"numberOfResults": 126,
"displayName": "Sports & Outdoors",
"classificationId": "3375301"
}
]
},
"items": [
{
"asin": "B002N36Q3M",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "Fred Perry",
"colorName": "Wht/Brt Red/Nvy",
"itemName": "Fred Perry Men's Twin Tipped Polo Shirt-M1200, WHT/BRT RED/NVY, X-Large",
"manufacturer": "Fred Perry Men's Apparel",
"modelNumber": "M1200",
"sizeName": "X-Large",
"styleName": "Twin Tipped Polo Shirt-m1200"
}
]
},
{
"asin": "B002N3ABSI",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "Fred Perry",
"colorName": "White/Bright Red/Navy",
"itemName": "Fred Perry Men's Twin Tipped Polo, White/Bright Red/Navy, SM",
"manufacturer": "Fred Perry Apparel Mens",
"modelNumber": "M1200-748",
"sizeName": "SM",
"styleName": "Twin Tipped Fred Perry Polo"
}
]
},
{
"asin": "B01N5B3598",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "NHL",
"colorName": "Red",
"itemName": "NHL New Jersey Devils Men's Polo, Small, Red",
"manufacturer": "Knight's Apparel",
"modelNumber": "H0MEE3ZAMZ",
"sizeName": "Small"
}
]
},
{
"asin": "B00HIVDUXI",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "adidas",
"colorName": "Bold Red/White",
"itemName": "Adidas Golf Men's Puremotion Textured Stripe Polo, Bold Red/White, Large",
"manufacturer": "TaylorMade - Adidas Golf Apparel",
"modelNumber": "TM3010S4",
"sizeName": "Large"
}
]
},
{
"asin": "B005ZZ12YS",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "RALPH LAUREN",
"colorName": "Black / Red Pony",
"itemName": "Polo Ralph Lauren Men's Long-sleeved T-shirt / Sleepwear / Thermal in Black, Red Pony (Large / L)",
"sizeName": "Large"
}
]
}
]
}
Paginação na resposta a uma pesquisa por itens no catálogo da Amazon
Quando uma chamada para a operação searchCatalogItems traz uma resposta que excede o pageSize
, ocorre a paginação. Isso significa que a resposta é dividida em páginas individuais, onde 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 quando chama a operação searchCatalogItems e não fornece nenhum token de página. Em seguida, você itera pelo 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 existem antes ou depois.
Se a página seguinte ou anterior não estiverem disponível, o atributo de token da página correspondente (nextToken
ou previousToken
respectivamente) não estará presente no objeto de paginação.
Quando a resposta não excede pageSize
, não há paginação, portanto, não há nextToken
ou previousToken
:
"pagination": {
},
Quando a resposta excede o pageSize e ocorre a paginação:
Para a primeira página, não há página anterior, portanto, não há previousToken
:
"pagination": {
"nextToken": "XXXXXX"
},
Para a última página, não há próxima página, portanto, não há nextToken
:
"pagination": {
"previousToken": "XXXXXX"
},
Para todas as outras páginas:
"pagination": {
"nextToken": "XXXXXX",
"previousToken": "XXXXXX"
},
Nota
Mesmo que possa haver mais de 1000 ASINs que correspondem aos critérios de pesquisa, o número máximo de resultados que podem ser retornados e paginados é limitado a 1000. Por exemplo, se definir o tamanho da página para 10, o número máximo de páginas possíveis é 100 resultados por página.
Updated about 2 years ago