Busca de itens
Conteúdos
→Resumo dos recursos disponíveis
→Buscar itens por categoria
→Valores nos campos sold_quantity e available_quantity
↳sold_quantity
↳available_quantity
→Obter itens de uma consulta de busca
→Buscar itens por vendedor
↳Obter itens das listagens por vendedor
↳Por ID de vendedor
↳Por nickname
↳Por ID de vendedor para uma categoria específica
→Itens com perda de exposição
→Obtém itens da conta de um vendedor
↳Por user_id
↳Por SKU
↳Por estado
↳Com/sem product identifier
→Verifique os vendedores restritos
→Multiget
→Seleção de campos
→Modo de busca acima de 1000 registros
↳Trabalhar com Scan + Hash
Resumo dos recursos disponíveis
| Recurso | Descripción |
|---|---|
| /sites/$SITE_ID/search?category=$CATEGORY_ID | Obter itens listados numa categoria. |
| /sites/$SITE_ID/search?q=Motorola%20G6 | Obter itens de uma consulta de busca. |
| /sites/$SITE_ID/search?nickname=$NICKNAME | Obter itens das listagens por nickname. |
| /sites/$SITE_ID/search?seller_id=$SELLER_ID | Permite listar itens por vendedor. |
| /sites/$SITE_ID/search?seller_id=$SELLER_ID&category=$CATEGORY_ID | Obter itens das listagens por vendedor numa categoria específica. |
| /users/$USER_ID/items/search | Permite listar todos os itens da conta de um vendedor. |
| /items?ids=$ITEM_ID1,$ITEM_ID2 | Multiget com múltiplos números de itens. |
| /users?ids=$USER_ID1,$USER_ID2 | Multiget com múltiplos números de usuários. |
| /items?ids=$ITEM_ID1,$ITEM_ID2&attributes=$ATTRIBUTE1,$ATTRIBUTE2,$ATTRIBUTE3 | Multiget com múltiplos números de itens selecionando apenas os campos de interesse. |
| /users/$USER_ID/items/search?search_type=scan | Para obter mais de 1000 registros. |
Buscar itens por categoria
Leve em consideração que ao início dos resultados você verá os itens que pertençam a um catálogo identificando-os no campo catalog_listing: true.
Conheça mais detalhes sobre Categorias e Atributos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?category=$CATEGORY_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?category=MLA1055Resposta:
{
"site_id": "MLA",
"paging": {
"total": 90591,
"offset": 0,
"limit": 50,
"primary_results": 1039
},
"results": [
{
"id": "MLA811601010",
"site_id": "MLA",
"title": "Samsung Galaxy J4+ Dual Sim 32 Gb Negro (2 Gb Ram)",
"seller": {
"id": 451257294,
"power_seller_status": null,
"car_dealer": false,
"real_estate_agency": false,
"tags": []
},
"price": 19609,
"currency_id": "ARS",
"available_quantity": 1,
"sold_quantity": 1,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_pro",
"stop_time": "2039-08-22T04:00:00.000Z",
"condition": "new",
"permalink": "https://www.mercadolibre.com.ar/p/MLA13550363",
"thumbnail": "http://mla-s1-p.mlstatic.com/943469-MLA31002769183_062019-I.jpg",
"accepts_mercadopago": true,
"installments": {
"quantity": 6,
"amount": 3268.17,
"rate": 0,
"currency_id": "ARS"
},
"address": {
"state_id": "AR-B",
"state_name": "Buenos Aires",
"city_id": "TUxBQ0dFTjY4NTg",
"city_name": "General Rodríguez"
},
"shipping": {
"free_shipping": true,
"mode": "me2",
"tags": [
"mandatory_free_shipping"
],
"logistic_type": "drop_off",
"store_pick_up": false
},
"seller_address": {
"id": "",
"comment": "",
"address_line": "",
"zip_code": "",
"country": {
"id": "AR",
"name": "Argentina"
},
"state": {
"id": "AR-B",
"name": "Buenos Aires"
},
"city": {
"id": "TUxBQ0dFTjY4NTg",
"name": "General Rodríguez"
},
"latitude": "",
"longitude": ""
},
"attributes": [
{
"values": [
{
"source": 1,
"id": "206",
"name": "Samsung",
"struct": null
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"id": "BRAND",
"value_id": "206",
"value_name": "Samsung",
"value_struct": null,
"source": 1,
"name": "Marca"
},
{
"id": "CPU_MODEL",
"value_struct": null,
"values": [
{
"struct": null,
"source": 6587939990796619,
"id": "7657686",
"name": "4x1.4 GHz Cortex-A53"
}
],
"attribute_group_name": "Otros",
"name": "Modelo de CPU",
"value_id": "7657686",
"value_name": "4x1.4 GHz Cortex-A53",
"attribute_group_id": "OTHERS",
"source": 6587939990796619
},
{
"value_name": "Adreno 308",
"value_struct": null,
"values": [
{
"source": 4709228965570453,
"id": "7531831",
"name": "Adreno 308",
"struct": null
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"id": "GPU_MODEL",
"name": "Modelo de GPU",
"value_id": "7531831",
"source": 4709228965570453
},
{
"values": [
{
"id": "2230284",
"name": "Nuevo",
"struct": null,
"source": 8342579661593500
}
],
"id": "ITEM_CONDITION",
"value_struct": null,
"value_name": "Nuevo",
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 8342579661593500,
"name": "Condición del ítem",
"value_id": "2230284"
},
{
"value_id": "195973",
"value_name": "Galaxy J",
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "LINE",
"name": "Línea",
"value_struct": null,
"values": [
{
"source": 1,
"id": "195973",
"name": "Galaxy J",
"struct": null
}
]
},
{
"value_name": "J4+ Duos",
"values": [
{
"id": "6047739",
"name": "J4+ Duos",
"struct": null,
"source": 1
}
],
"id": "MODEL",
"name": "Modelo",
"value_id": "6047739",
"source": 1,
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"values": [
{
"struct": null,
"source": 6587939990796619,
"id": "2087879",
"name": "Snapdragon 425"
}
],
"attribute_group_name": "Otros",
"name": "Modelo del procesador",
"value_name": "Snapdragon 425",
"value_struct": null,
"attribute_group_id": "OTHERS",
"source": 6587939990796619,
"id": "PROCESSOR_MODEL",
"value_id": "2087879"
}
],
"differential_pricing": {
"id": 33669181
},
"original_price": null,
"category_id": "MLA1055",
"official_store_id": null,
"catalog_product_id": "MLA13550363",
"tags": [
"extended_warranty_eligible",
"good_quality_picture",
"good_quality_thumbnail",
"immediate_payment",
"cart_eligible"
],
"catalog_listing": true
},
{
"id": "MLA816019440",
"site_id": "MLA",
"title": "Apple iPhone Xr Dual Sim 128 Gb Blanco",
"seller": {
"id": 70894521,
"power_seller_status": null,
"car_dealer": false,
"real_estate_agency": false,
"tags": []
},
"price": 79470,
"currency_id": "ARS",
"available_quantity": 1,
"sold_quantity": 0,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"stop_time": "2039-09-15T04:00:00.000Z",
"condition": "new",
"permalink": "https://www.mercadolibre.com.ar/p/MLA12866684",
"thumbnail": "http://mla-s1-p.mlstatic.com/980849-MLA31002261498_062019-I.jpg",
"accepts_mercadopago": true,
"installments": {
"quantity": 12,
"amount": 10845.67,
"rate": 63.77,
"currency_id": "ARS"
},
"address": {
"state_id": "AR-C",
"state_name": "Capital Federal",
"city_id": "TUxBQlBBVDI0ODFa",
"city_name": "Paternal"
},
"shipping": {
"free_shipping": true,
"mode": "me2",
"tags": [
"mandatory_free_shipping"
],
"logistic_type": "drop_off",
"store_pick_up": false
},
"seller_address": {
"id": "",
"comment": "",
"address_line": "",
"zip_code": "",
"country": {
"id": "AR",
"name": "Argentina"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"city": {
"id": "TUxBQlBBVDI0ODFa",
"name": "Paternal"
},
"latitude": "",
"longitude": ""
},
"attributes": [
{
"source": 1,
"id": "BRAND",
"value_name": "Apple",
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"name": "Marca",
"value_id": "9344",
"value_struct": null,
"values": [
{
"struct": null,
"source": 1,
"id": "9344",
"name": "Apple"
}
]
},
{
"name": "Modelo de CPU",
"attribute_group_id": "OTHERS",
"source": 1,
"id": "CPU_MODEL",
"value_id": "6927770",
"value_name": "2x2.5 GHz Vortex/4x1.6 GHz Tempest",
"value_struct": null,
"values": [
{
"id": "6927770",
"name": "2x2.5 GHz Vortex/4x1.6 GHz Tempest",
"struct": null,
"source": 1
}
],
"attribute_group_name": "Otros"
},
{
"values": [
{
"name": "Nuevo",
"struct": null,
"source": 6808261514773724,
"id": "2230284"
}
],
"source": 6808261514773724,
"value_id": "2230284",
"value_name": "Nuevo",
"value_struct": null,
"attribute_group_name": "Otros",
"id": "ITEM_CONDITION",
"name": "Condición del ítem",
"attribute_group_id": "OTHERS"
},
{
"value_id": "58993",
"value_struct": null,
"values": [
{
"struct": null,
"source": 1,
"id": "58993",
"name": "iPhone"
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "LINE",
"name": "Línea",
"value_name": "iPhone"
},
{
"name": "Modelo",
"value_struct": null,
"values": [
{
"id": "5414260",
"name": "iPhone XR",
"struct": null,
"source": 1
}
],
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"id": "MODEL",
"value_id": "5414260",
"value_name": "iPhone XR",
"source": 1
},
{
"id": "PROCESSOR_MODEL",
"attribute_group_id": "OTHERS",
"values": [
{
"id": "6927771",
"name": "Apple A12 Bionic",
"struct": null,
"source": 1
}
],
"attribute_group_name": "Otros",
"source": 1,
"name": "Modelo del procesador",
"value_id": "6927771",
"value_name": "Apple A12 Bionic",
"value_struct": null
}
],
"original_price": null,
"category_id": "MLA1055",
"official_store_id": null,
"catalog_product_id": "MLA12866684",
"tags": [
"good_quality_picture",
"good_quality_thumbnail",
"immediate_payment",
"cart_eligible"
],
"catalog_listing": true
}
}
]
}
Com a tag "supermarket_elegible", é possível identificar os itens de Supermercado. A tag de supermercado é aplicada pelo Mercado Livre respeitando várias regras definidas comercialmente. De tal forma, que ela pode ser eliminada quando o item deixar de atender alguma das regras, sem prévio aviso ao seller.
Exemplo:
"sub_status": [],
"tags": [
"good_quality_thumbnail",
"supermarket_eligible",
"good_quality_picture",
"immediate_payment",
"cart_eligible"
]
Valores nos campos sold_quantity e available_quantity
Nos recursos públicos de Itens e Buscas a informacão dos campos "sold_quantity" y "available_quantity" serão referenciais com os seguintes valores:
sold_quantity
| Dato real | Referencia |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 3 |
| 4 | 4 |
| 5 | 5 |
| RANGO_6_25 | 5 |
| RANGO_26_50 | 25 |
| RANGO_51_100 | 50 |
| RANGO_101_150 | 100 |
| RANGO_151_200 | 150 |
| RANGO_201_250 | 200 |
| RANGO_251_500 | 250 |
| RANGO_501_5000 | 500 |
| RANGO_5001_50000 | 5000 |
| RANGO_50001_500000 | 50000 |
available_quantity
| Dato real | Referencia |
|---|---|
| RANGO_0_50 | 1 |
| RANGO_51_100 | 50 |
| RANGO_101_150 | 100 |
| RANGO_151_200 | 150 |
| RANGO_201_250 | 200 |
| RANGO_251_500 | 250 |
| RANGO_501_5000 | 500 |
| RANGO_5001_50000 | 5000 |
| RANGO_50001_99999 | 50000 |
Obter itens de uma consulta de busca
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?q=Motorola%20G6Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?q=Motorola%20G6
Resposta:
{
"site_id": "MLA",
"query": "Motorola G6",
"paging": {
"total": 916,
"offset": 0,
"limit": 50,
"primary_results": 916
},
"results": [
{
"id": "MLA810645375",
"site_id": "MLA",
"title": "Motorola G6 Plus 64 Gb Nimbus",
"seller": {
"id": 143125485,
"power_seller_status": "platinum",
"car_dealer": false,
"real_estate_agency": false,
"tags": []
},
"price": 17999,
"currency_id": "ARS",
"available_quantity": 100,
"sold_quantity": 0,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"stop_time": "2039-08-17T04:00:00.000Z",
"condition": "new",
"permalink": "https://www.mercadolibre.com.ar/p/MLA9452524",
"thumbnail": "http://mla-s2-p.mlstatic.com/795558-MLA31003306206_062019-I.jpg",
"accepts_mercadopago": true,
"installments": {
"quantity": 12,
"amount": 2456.41,
"rate": 63.77,
"currency_id": "ARS"
},
"address": {
"state_id": "AR-C",
"state_name": "Capital Federal",
"city_id": "TUxBQkJBTDMxMDZa",
"city_name": "Balvanera"
},
"shipping": {
"free_shipping": false,
"mode": "custom",
"tags": [],
"logistic_type": "custom",
"store_pick_up": true
},
"seller_address": {
"id": "",
"comment": "",
"address_line": "",
"zip_code": "",
"country": {
"id": "AR",
"name": "Argentina"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"city": {
"id": "TUxBQkJBTDMxMDZa",
"name": "Balvanera"
},
"latitude": "",
"longitude": ""
},
"attributes": [
{
"name": "Marca",
"value_id": "2503",
"value_name": "Motorola",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "BRAND"
},
{
"attribute_group_name": "Otros",
"source": 1,
"id": "CPU_MODEL",
"name": "Modelo de CPU",
"value_id": "7070889",
"value_name": "4x2.2 GHz Cortex-A53/4x1.8 GHz Cortex-A53",
"value_struct": null,
"attribute_group_id": "OTHERS"
},
],
"original_price": null,
"category_id": "MLA1055",
"official_store_id": 229,
"catalog_product_id": "MLA9452524",
"tags": [
"extended_warranty_eligible",
"good_quality_picture",
"good_quality_thumbnail",
"immediate_payment"
],
"catalog_listing": true
},
{
"id": "MLA805330648",
"site_id": "MLA",
"title": "Motorola G6 32 Gb Plata",
"seller": {
"id": 185702920,
"power_seller_status": "platinum",
"car_dealer": false,
"real_estate_agency": false,
"tags": []
},
"price": 14899,
"currency_id": "ARS",
"available_quantity": 1,
"sold_quantity": 0,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"stop_time": "2039-07-28T17:33:48.000Z",
"condition": "new",
"permalink": "https://www.mercadolibre.com.ar/p/MLA9652755",
"thumbnail": "http://mla-s1-p.mlstatic.com/685061-MLA31003463570_062019-I.jpg",
"accepts_mercadopago": true,
"installments": {
"quantity": 12,
"amount": 2033.34,
"rate": 63.77,
"currency_id": "ARS"
},
"address": {
"state_id": "AR-C",
"state_name": "Capital Federal",
"city_id": null,
"city_name": "Once"
},
"shipping": {
"free_shipping": true,
"mode": "me2",
"tags": [
"fulfillment",
"mandatory_free_shipping"
],
"logistic_type": "fulfillment",
"store_pick_up": false
},
"seller_address": {
"id": "",
"comment": "",
"address_line": "",
"zip_code": "",
"country": {
"id": "AR",
"name": "Argentina"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"city": {
"id": null,
"name": "Once"
},
"latitude": "",
"longitude": ""
},
"attributes": [
{
"name": "Marca",
"value_id": "2503",
"value_name": "Motorola",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "BRAND"
},
{
"value_id": "6936760",
"value_name": "8x1.8 GHz Cortex-A53",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "CPU_MODEL",
"name": "Modelo de CPU"
},
{
"value_name": "Snapdragon 450",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros",
"source": 1,
"id": "PROCESSOR_MODEL",
"name": "Modelo del procesador",
"value_id": "6936759"
}
],
"original_price": null,
"category_id": "MLA1055",
"official_store_id": null,
"catalog_product_id": "MLA9652755",
"tags": [
"good_quality_picture",
"good_quality_thumbnail",
"extended_warranty_eligible",
"immediate_payment",
"cart_eligible"
],
"catalog_listing": true
}
}
]
}
Buscar itens por vendedor
- /sites/$SITE_ID/search? poderá obter os resultados de itens ativos diretamente das listagens de Mercado Libre.
- /users/$USER_ID/items/search poderá obter uma listagem dos itens publicados por determinado vendedor desde sua conta.
Obter itens das listagens por vendedor
Esta busca se ajusta às regras das listagens da plataforma. Os resultados sempre serão de itens ativos.
Por ID de vendedor
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?seller_id=$SELLER_IDPor nickname
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?nickname=$NICKNAMEFiltros e ordenamentos também poderão ser aplicados.
Dentro de /sites/{site_id}/search? tem os campos "available_sorts" e "available_filters" quando adiciona um parâmetro.
Como ordenar? Neste caso, você deverá adicionar “sort” com o ID disponível da ordem que quiser aplicar, por exemplo: “price_asc”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?seller_id=$SELLER_ID&sort=price_ascComo filtrar? Por exemplo, para filtrar itens com envio sem custo extra, você achará entre os "available_filters" disponíveis o ID "shipping" e, dentro dele, o value com ID “free”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?seller_id=$SELLER_ID&shipping_cost=freePor ID de vendedor para uma categoria específica
Utilizando o seguinte exemplo, você poderá buscar dentro de uma categoria específica. Com a seguinte chamada, você poderá consultar as publicações de categorias específicas.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?seller_id=$SELLER_ID&category=$CATEGORY_ID
Itens com perda de exposição
Com o filtro a seguir, você poderá reconhecer os itens que estão perdendo ou podem perder exposição devido a reclamações ou cancelamentos. Você pode usar:
unhealthy: para identificar itens que já estão perdendo exposição.
warning: para quem pode perdê-lo e que ainda é possível recuperar.
healthy: para itens que não foram afetados.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?reputation_health_gauge=unhealthyExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/items/search?reputation_health_gauge=unhealthyResposta:
{
"seller_id":"123456789",
"query":null,
"paging":{
"limit":50,
"offset":0,
"total":1
},
"results":[
"MLA844702264"
],
"orders":[
{
"id":"stop_time_asc",
"name":"Order by stop time ascending"
}
],
"available_orders":[
{
"id":"stop_time_asc",
"name":"Order by stop time ascending"
},
{
"id":"stop_time_desc",
"name":"Order by stop time descending"
},
{
"id":"start_time_asc",
"name":"Order by start time ascending"
},
{
"id":"start_time_desc",
"name":"Order by start time descending"
},
{
"id":"available_quantity_asc",
"name":"Order by available quantity ascending"
},
{
"id":"available_quantity_desc",
"name":"Order by available quantity descending"
},
{
"id":"sold_quantity_asc",
"name":"Order by sold quantity ascending"
},
{
"id":"sold_quantity_desc",
"name":"Order by sold quantity descending"
},
{
"id":"price_asc",
"name":"Order by price ascending"
},
{
"id":"price_desc",
"name":"Order by price descending"
},
{
"id":"last_updated_desc",
"name":"Order by lastUpdated descending"
},
{
"id":"last_updated_asc",
"name":"Order by last updated ascending"
},
{
"id":"total_sold_quantity_asc",
"name":"Order by total sold quantity ascending"
},
{
"id":{
"id":"total_sold_quantity_desc",
"field":"sold_quantity",
"missing":"_last",
"order":"desc"
},
"name":"Order by total sold quantity descending"
},
{
"id":{
"id":"inventory_id_asc",
"field":"inventory_id",
"missing":"_last",
"order":"asc"
},
"name":"Order by inventory id ascending"
}
]
}
Obtém itens da conta de um vendedor
Já não mostramos o bloco correspondente aos campos “filters” e “available_filters” para melhorar os tempos de resposta. Se você precisar dessas informações, poderá obtê-las enviando o parâmetro include_filters=true no search.
Por user_id
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/searchPor SKU
- Seller_custom_field: se o item contém um SKU no campo “seller_custom_field”, você pode tentar na forma a seguir:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?sku=$SELLER_CUSTOM_FIELD- Seller_sku: Se o item contiver um SKU no campo/atributo “SELLER_SKU”, você pode tentar assim:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?seller_sku=$SELLER_SKUPor estado
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?status=activeCom/sem product identifier
Usando os parâmetros: - missing_product_identifiers=true você consulta publicações que não têm um identificador de produto carregado ou envio. Assim, você identifica quais publicações pode melhorar cumprindo um dos requisitos de qualidade mais importantes. - missing_product_identifiers=false você obtém a lista de publicações com PI carregado ou enviando.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?missing_product_identifiers=trueFiltra e ordena os resultados dos itens do vendedor
Dentro do recurso /users/{user_id}/items/search? não mostraremos os campos "filtros" e "disponíveis_filtros" para melhorar os tempos de resposta atuais. Para vê-los, você deve enviar o parâmetro include_filters=true e a resposta retornará os campos excluídos na chamada sem um parâmetro.
Exemplo de chamada sem parâmetro:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/searchResposta da chamada sem parâmetro:
{
"seller_id": "123456789",
"query": null,
"paging": {
"limit": 50,
"offset": 0,
"total": 1
},
"results": [
"MLA844702264"
],
"orders": [
{
"id": "stop_time_asc",
"name": "Order by stop time ascending"
}
],
"available_orders": [
{
"id": "stop_time_asc",
"name": "Order by stop time ascending"
},
{
"id": "stop_time_desc",
"name": "Order by stop time descending"
},
{
"id": "start_time_asc",
"name": "Order by start time ascending"
},
{
"id": "start_time_desc",
"name": "Order by start time descending"
},
{
"id": "available_quantity_asc",
"name": "Order by available quantity ascending"
},
{
"id": "available_quantity_desc",
"name": "Order by available quantity descending"
},
{
"id": "sold_quantity_asc",
"name": "Order by sold quantity ascending"
},
{
"id": "sold_quantity_desc",
"name": "Order by sold quantity descending"
},
{
"id": "price_asc",
"name": "Order by price ascending"
},
{
"id": "price_desc",
"name": "Order by price descending"
},
{
"id": "last_updated_desc",
"name": "Order by lastUpdated descending"
},
{
"id": "last_updated_asc",
"name": "Order by last updated ascending"
},
{
"id": "total_sold_quantity_asc",
"name": "Order by total sold quantity ascending"
},
{
"id": {
"id": "total_sold_quantity_desc",
"field": "sold_quantity",
"missing": "_last",
"order": "desc"
},
"name": "Order by total sold quantity descending"
},
{
"id": {
"id": "inventory_id_asc",
"field": "inventory_id",
"missing": "_last",
"order": "asc"
},
"name": "Order by inventory id ascending"
}
]
}Exemplo de chamada com parâmetro:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?include_filters=trueResposta da chamada com parâmetros:
{
"seller_id": "123456789",
"query": null,
"paging": {
"limit": 50,
"offset": 0,
"total": 1
},
"results": [
"MLA844702264"
],
"filters": [],
"available_filters": [
{
"id": "status",
"name": "Status",
"values": [
{
"id": "pending",
"name": "Inactive items for debt or MercadoLibre policy violation",
"results": 0
},
{
"id": "not_yet_active",
"name": "Items newly created or pending activation",
"results": 0
},
{
"id": "programmed",
"name": "Items scheduled for future activation",
"results": 0
},
{
"id": "active",
"name": "Active items",
"results": 1
},
{
"id": "paused",
"name": "Paused Items",
"results": 0
},
{
"id": "closed",
"name": "Closed Items",
"results": 0
}
]
},
{
"id": "sub_status",
"name": "Substatus",
"values": [
{
"id": "deleted",
"name": "Deleted substatus",
"results": 0
},
{
"id": "forbidden",
"name": "Forbidden substatus",
"results": 0
},
{
"id": "freezed",
"name": "Freezed substatus",
"results": 0
},
{
"id": "held",
"name": "Held substatus",
"results": 0
},
{
"id": "suspended",
"name": "Suspended substatus",
"results": 0
},
{
"id": "waiting_for_patch",
"name": "Waiting for patch substatus",
"results": 0
},
{
"id": "warning",
"name": "Warning items with MercadoLibre policy violation",
"results": 0
}
]
},
{
"id": "buying_mode",
"name": "Buying Mode",
"values": [
{
"id": "buy_it_now",
"name": "Buy it now",
"results": 1
},
{
"id": "classified",
"name": "Classified",
"results": 0
},
{
"id": "auction",
"name": "Auction",
"results": 0
}
]
},
{
"id": "listing_type_id",
"name": "Listing type",
"values": [
{
"id": "gold_pro",
"name": "Gold proffesional",
"results": 0
},
{
"id": "gold_special",
"name": "Gold special",
"results": 0
},
{
"id": "gold_premium",
"name": "Gold premium",
"results": 0
},
{
"id": "gold",
"name": "Gold",
"results": 0
},
{
"id": "silver",
"name": "Silver",
"results": 0
},
{
"id": "bronze",
"name": "Bronze",
"results": 0
},
{
"id": "free",
"name": "Free",
"results": 1
}
]
},
{
"id": "shipping_free_methods",
"name": "Shipping free methods",
"values": []
},
{
"id": "shipping_tags",
"name": "Shipping Tags",
"values": []
},
{
"id": "shipping_mode",
"name": "Shipping Mode",
"values": [
{
"id": "not_specified",
"results": 1
}
]
},
{
"id": "listing_source",
"name": "Listing Source",
"values": [
{
"id": "tucarro",
"name": "TuCarro",
"results": 0
},
{
"id": "tuinmueble",
"name": "TuInmueble",
"results": 0
},
{
"id": "tumoto",
"name": "TuMoto",
"results": 0
},
{
"id": "tulancha",
"name": "TuLancha",
"results": 0
},
{
"id": "autoplaza",
"name": "Autoplaza",
"results": 0
},
{
"id": "autoplaza_ml",
"name": "Autoplaza Premium",
"results": 0
}
]
},
{
"id": "labels",
"name": "Others",
"values": [
{
"id": "few_available",
"name": "Items with few availables",
"results": 0
},
{
"id": "with_bids",
"name": "Items with bids",
"results": 0
},
{
"id": "without_bids",
"name": "Items whithout bids",
"results": 1
},
{
"id": "accepts_mercadopago",
"name": "Items with MercadoPago",
"results": 1
},
{
"id": "ending_soon",
"name": "Items ending in 20 days or less",
"results": 0
},
{
"id": "with_mercadolibre_envios",
"name": "Items with MercadoLibre Envíos",
"results": 0
},
{
"id": "without_mercadolibre_envios",
"name": "Items without MercadoLibre Envíos",
"results": 1
},
{
"id": "with_low_quality_image",
"name": "Items with low quality image",
"results": 0
},
{
"id": "with_free_shipping",
"name": "Items with free shipping",
"results": 0
},
{
"id": "without_free_shipping",
"name": "Items with free shipping",
"results": 1
},
{
"id": "with_automatic_relist",
"name": "Items with automatic relist",
"results": 0
},
{
"id": "waiting_for_payment",
"name": "Items waiting for payment",
"results": 0
},
{
"id": "suspended",
"name": "Suspended items",
"results": 0
},
{
"id": "cancelled",
"name": "Items cancelled that can not be recovered",
"results": 0
},
{
"id": "being_reviewed",
"name": "Items under review",
"results": 0
},
{
"id": "fix_required",
"name": "Items waiting for user fix",
"results": 0
},
{
"id": "waiting_for_documentation",
"name": "Items waiting for user documentation",
"results": 0
},
{
"id": "without_stock",
"name": "Paused items that are out of stock",
"results": 0
},
{
"id": "incomplete_technical_specs",
"name": "Items with incomplete technical specs",
"results": 0
},
{
"id": "loyalty_discount_eligible",
"name": "Loyalty discount eligible items",
"results": 0
},
{
"id": "with_fbm_contingency",
"name": "Items in FBM contingency",
"results": 0
},
{
"id": "with_shipping_self_service",
"name": "Items with shipping self service logistic",
"results": 0
}
]
},
{
"id": "logistic_type",
"name": "Logistic Type",
"values": [
{
"id": "not_specified",
"results": 1
}
]
}
],
"orders": [
{
"id": "stop_time_asc",
"name": "Order by stop time ascending"
}
],
"available_orders": [
{
"id": "stop_time_asc",
"name": "Order by stop time ascending"
},
{
"id": "stop_time_desc",
"name": "Order by stop time descending"
},
{
"id": "start_time_asc",
"name": "Order by start time ascending"
},
{
"id": "start_time_desc",
"name": "Order by start time descending"
},
{
"id": "available_quantity_asc",
"name": "Order by available quantity ascending"
},
{
"id": "available_quantity_desc",
"name": "Order by available quantity descending"
},
{
"id": "sold_quantity_asc",
"name": "Order by sold quantity ascending"
},
{
"id": "sold_quantity_desc",
"name": "Order by sold quantity descending"
},
{
"id": "price_asc",
"name": "Order by price ascending"
},
{
"id": "price_desc",
"name": "Order by price descending"
},
{
"id": "last_updated_desc",
"name": "Order by lastUpdated descending"
},
{
"id": "last_updated_asc",
"name": "Order by last updated ascending"
},
{
"id": "total_sold_quantity_asc",
"name": "Order by total sold quantity ascending"
},
{
"id": {
"id": "total_sold_quantity_desc",
"field": "sold_quantity",
"missing": "_last",
"order": "desc"
},
"name": "Order by total sold quantity descending"
},
{
"id": {
"id": "inventory_id_asc",
"field": "inventory_id",
"missing": "_last",
"order": "asc"
},
"name": "Order by inventory id ascending"
}
]
}Como ordenar? Nesse caso, você deverá adicionar “orders” com o ID disponível da ordem que quiser aplicar, por exemplo: “start_time_desc”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?orders=start_time_descComo filtrar? Por exemplo, para filtrar itens com listing_type “gold_pro”, entre os ”available_filters" disponíveis achará o ID "listing_type_id" e, dentro dele, o value com ID “gold_pro”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?listing_type_id=gold_proVerifique os vendedores restritos
Você pode reconhecer se um vendedor tem mais de 200.000 itens e não receberá os campos “filters” e “available_filters” na resposta do recurso /search.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search/restrictionsExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/items/search/restrictionsResposta:
{
"aggregations_allowed":false,
"query_allowed":true,
"sort_allowed":true
}Se o campo aggregations_allowed tem valor false significa que o vendedor tem restrição de suas buscas por ter mais de 200.000 itens e sua busca não retornará os blocos “filters” e “available_filters”. Caso enviar o parâmetro “include_filters”=true em /search, retornaremos um status 206 e se não for enviado, obterá um status 200.
Multiget
Utiliza a função Multiget para melhorar a interação com os recursos de itens e users e poder acessar assim um máximo de 20 resultados com uma única chamada. Lembre que a resposta utilizando multiget será restituída no formato verbose, o que significa que, além do JSON com as informações, responderemos com um código que vai indicar se a consulta foi exitosa ou não, para cada uma das buscas.
Chamada a /itens:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=$ITEM_ID1,$ITEM_ID2Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=MLA599260060,MLA594239600Resposta:
[
{
"code": 200,
"body": {
"id": "MLA599260060",
"site_id": "MLA",
"title": "Item De Test - Por Favor No Ofertar",
"subtitle": null,
"seller_id": 303888594,
"category_id": "MLA401685",
"official_store_id": null,
"price": 130,
"base_price": 130,
"original_price": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
[...]
"automatic_relist": false,
"date_created": "2018-02-26T18:15:05.000Z",
"last_updated": "2018-03-29T04:14:39.000Z",
"health": null
}
},
{
"code": 200,
"body": {
"id": "MLA594239600",
"site_id": "MLA",
"title": "Item De Test - Por Favor No Ofertar",
"subtitle": null,
"seller_id": 303888594,
"category_id": "MLA401685",
"official_store_id": null,
"price": 120,
"base_price": 120,
"original_price": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
[...]
"automatic_relist": false,
"date_created": "2018-02-26T18:15:05.000Z",
"last_updated": "2018-03-29T04:14:39.000Z",
"health": null
}
}
]
Chamada a /users:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users?ids=$USER_ID1,$USER_ID2
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users?ids=401114259,287440999
Resposta:
[
{
"code": 200,
"body": {
"id": 401114259,
"nickname": "user_test234",
"registration_date": "2019-02-05T10:38:03.000-04:00",
"country_id": "BR",
"address": {
"city": null,
"state": null
},
"user_type": "normal",
"tags": [
"normal"
],
"logo": null,
"points": 0,
"site_id": "MLB",
"permalink": "http://perfil.mercadolivre.com.br/user_test234",
"seller_reputation": {
"level_id": null,
"power_seller_status": null,
"transactions": {
"canceled": 0,
"completed": 0,
"period": "historic",
"ratings": {
"negative": 0,
"neutral": 0,
"positive": 0
},
"total": 0
}
},
"buyer_reputation": {
"tags": [
]
},
"status": {
"site_status": "guest"
}
}
},
{
"code": 200,
"body": {
"id": 287440999,
"nickname": "user_test111",
"registration_date": "2019-03-06T00:16:08.000-04:00",
"country_id": "MX",
"address": {
"city": null,
"state": null
},
"user_type": "normal",
"tags": [
"normal"
],
"logo": null,
"points": 0,
"site_id": "MLM",
"permalink": "http://perfil.mercadolibre.com.mx/user_test111",
"seller_reputation": {
"level_id": null,
"power_seller_status": null,
"transactions": {
"canceled": 0,
"completed": 0,
"period": "historic",
"ratings": {
"negative": 0,
"neutral": 0,
"positive": 0
},
"total": 0
}
},
"buyer_reputation": {
"tags": [
]
},
"status": {
"site_status": "active"
}
}
}
]Seleção de campos
Outra alternativa que você pode implementar no GET para itens na seleção de campos, para receber somente aqueles que sejam necessários.
Para poder definir os campos que você queira receber, deverá adicionar o parâmetro attributes na forma seguinte:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=$ITEM_ID1,$ITEM_ID2&attributes=$ATTRIBUTE1,$ATTRIBUTE2,$ATTRIBUTE3Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items?ids=MLA599260060,MLA594239600&attributes={id,price,category_id,title}Resposta:
[
{
"code": 200,
"body": {
"id": "MLA599260060",
"title": "Item De Test - Por Favor No Ofertar",
"category_id": "MLA401685",
"price": 130
}
}
{
"code": 200,
"body": {
"id": "MLA594239600",
"title": "Item De Test - Por Favor No Ofertar",
"category_id": "MLA401685",
"official_store_id": null,
"price": 120,
}
}
]
Modo de busca acima de 1000 registros
Trabalhar com Scan + Hash
Todas as buscas que forem realizadas no API de Itens, Perguntas e Respostas da forma users/{user_id}/items/search ou /questions/search maior de 1000 deverão ter o novo parâmetro search_type=scan sem utilizar o parâmetro offset.
Siga os passos a seguir para consultar mais de 1000 resultados:
- Adicione search_type=scan à consulta e remova o offset.
- No resultado, vai obter um campo scroll_id que expira em 5 minutos.
- Deverá adicionar à consulta scroll_id igual ao campo obtido anteriormente.
- Obterá os resultados a partir de 1000.
- Se não utilizar o parâmetro limit, serão restituídos por defeito 50 itens do total. Você poderá adicionar um limite máximo de 100.
- Para continuar obtendo as próximas páginas de resultados, é só fazer o mesmo GET à chamada até chegar ao fim da listagem.
A seguir mostramos passo por passo como fazê-lo:
- Adicionar search_type=scan
Para obter o scroll_id:
Itens:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?search_type=scanQuestions:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/questions/search?search_type=scan&item=$ITEM_IDResposta:
"scroll_id": "YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ=="- Adicionamos o scroll_id= obtido no passo anterior:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items/search?search_type=scan&scroll_id=YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ==Para continuar obtendo as próximas páginas de resultados, você deverá fazer o mesmo GET à chamada até chegar ao final da listagem. Você saberá quando chegar ao final quando esse GET aparecer null.
Seguinte: Perguntas e Respostas.
Faça login ou registre-se para receber as últimas notícias sobre nossa API
