Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Categorias e Atributos
Categorias
O recurso /sites pode oferecer a estrutura de categorias de um país em particular, nesse caso, do Brasil.
Chamada:curl -X GET https://api.mercadolibre.com/sites/MLB/categories[
{
"id": "MLB5672",
"name": "Acessórios para Veículos"
},
{
"id": "MLB271599",
"name": "Agro"
},
{
"id": "MLB1403",
"name": "Alimentos e Bebidas"
},
{
"id": "MLB1071",
"name": "Animais"
},
{
"id": "MLB1367",
"name": "Antiguidades e Coleções"
},
{
"id": "MLB1368",
"name": "Arte, Papelaria e Armarinho"
},
{
"id": "MLB1384",
"name": "Bebês"
},
{
"id": "MLB1246",
"name": "Beleza e Cuidado Pessoal"
},
{
"id": "MLB1132",
"name": "Brinquedos e Hobbies"
},
{
"id": "MLB1430",
"name": "Calçados, Roupas e Bolsas"
},
{
"id": "MLB1039",
"name": "Câmeras e Acessórios"
},
{
"id": "MLB1743",
"name": "Carros, Motos e Outros"
},
{
"id": "MLB1574",
"name": "Casa, Móveis e Decoração"
},
{
"id": "MLB1051",
"name": "Celulares e Telefones"
},
{
"id": "MLB5726",
"name": "Eletrodomésticos"
},
{
"id": "MLB1000",
"name": "Eletrônicos, Áudio e Vídeo"
},
{
"id": "MLB1276",
"name": "Esportes e Fitness"
},
{
"id": "MLB263532",
"name": "Ferramentas e Construção"
},
{
"id": "MLB12404",
"name": "Festas e Lembrancinhas"
},
{
"id": "MLB1144",
"name": "Games"
},
{
"id": "MLB1459",
"name": "Imóveis"
},
{
"id": "MLB1499",
"name": "Indústria e Comércio"
},
{
"id": "MLB1648",
"name": "Informática"
},
{
"id": "MLB218519",
"name": "Ingressos"
},
{
"id": "MLB1182",
"name": "Instrumentos Musicais"
},
{
"id": "MLB3937",
"name": "Joias e Relógios"
},
{
"id": "MLB1196",
"name": "Livros, Revistas e Comics"
},
{
"id": "MLB1168",
"name": "Música, Filmes e Seriados"
},
{
"id": "MLB264586",
"name": "Saúde"
},
{
"id": "MLB1540",
"name": "Serviços"
},
{
"id": "MLB1953",
"name": "Mais Categorias"
}
]Para categorias do segundo nível, ou informações relacionadas com categorias específicas, você deverá utilizar o recurso /categories e enviar o ID da categoria como parâmetro na URL. Veja o que podemos encontrar na categoria MLB1743 “Carros, Motos e Outros”.
Chamada:
ccurl -X GET https://api.mercadolibre.com/categories/MLB1743Resposta:
{
"id": "MLB1743",
"name": "Carros, Motos e Outros",
"picture": "http://resources.mlstatic.com/category/images/e1a43666-ad57-4b8b-b405-f9d04dbbd8fc.png",
"permalink": "https://www.mercadolivre.com.br/veiculos/",
"total_items_in_this_category": 275080,
"path_from_root": [
{
"id": "MLB1743",
"name": "Carros, Motos e Outros"
}
],
"children_categories": [
{
"id": "MLB5839",
"name": "Caminhões",
"total_items_in_this_category": 15356
},
{
"id": "MLB1745",
"name": "Carros Antigos",
"total_items_in_this_category": 10338
},
{
"id": "MLB1744",
"name": "Carros e Caminhonetes",
"total_items_in_this_category": 192571
},
{
"id": "MLB10965",
"name": "Consórcios",
"total_items_in_this_category": 97
},
{
"id": "MLB7370",
"name": "Motorhomes",
"total_items_in_this_category": 475
},
{
"id": "MLB1763",
"name": "Motos",
"total_items_in_this_category": 20246
},
{
"id": "MLB1785",
"name": "Náutica",
"total_items_in_this_category": 7789
},
{
"id": "MLB47400",
"name": "Ônibus",
"total_items_in_this_category": 4905
},
{
"id": "MLB76421",
"name": "Veículos Pesados",
"total_items_in_this_category": 2829
},
{
"id": "MLB1907",
"name": "Outros Veículos",
"total_items_in_this_category": 20278
}
],
"attribute_types": "none",
"settings": {
"adult_content": false,
"buying_allowed": false,
"buying_modes": [
"classified"
],
"catalog_domain": null,
"coverage_areas": "not_allowed",
"currencies": [
"BRL"
],
"fragile": false,
"immediate_payment": "optional",
"item_conditions": [
"not_specified",
"used",
"new"
],
"items_reviews_allowed": false,
"listing_allowed": false,
"max_description_length": 50000,
"max_pictures_per_item": 15,
"max_pictures_per_item_var": 6,
"max_sub_title_length": 70,
"max_title_length": 60,
"maximum_price": null,
"minimum_price": null,
"mirror_category": null,
"mirror_master_category": null,
"mirror_slave_categories": [],
"price": "required",
"reservation_allowed": "mandatory",
"restrictions": [],
"rounded_address": false,
"seller_contact": "optional",
"shipping_modes": [
"not_specified",
"custom"
],
"shipping_options": [
"custom"
],
"shipping_profile": "not_allowed",
"show_contact_information": true,
"simple_shipping": "not_allowed",
"stock": "required",
"sub_vertical": null,
"subscribable": false,
"tags": [],
"vertical": "motors",
"vip_subdomain": "veiculo",
"buyer_protection_programs": [
"delivered",
"undelivered"
],
"status": "enabled"
},
"meta_categ_id": null,
"attributable": false,
"date_created": "2018-04-25T08:12:56.000Z"
}Você obtém os atributos “path_from_root” e "children_categories". Utilize esses atributos para explorar a árvore de categorias e encontrar a categoria específica de seu produto. Como você pode observar, as categorias são baseadas nos tipos de veículos. Essa chamada acima retornou as categorias como caminhões, motos e automóveis. Vamos fazer outra chamada, agora na categoria MLB1744, que é a categoria "Carros e Caminhonetes”.
Chamada:
curl -X GET https://api.mercadolibre.com/categories/MLB1744Resposta:
{
"id": "MLB1744",
"name": "Carros e Caminhonetes",
"picture": "http://resources.mlstatic.com/category/images/470e5a62-5d07-432a-8f00-6a67b2ffada8.png",
"permalink": null,
"total_items_in_this_category": 192571,
"path_from_root": [
{
"id": "MLB1743",
"name": "Carros, Motos e Outros"
},
{
"id": "MLB1744",
"name": "Carros e Caminhonetes"
}
],
"children_categories": [
{
"id": "MLB270644",
"name": "Agrale",
"total_items_in_this_category": 23
},
{
"id": "MLB6039",
"name": "Alfa Romeo",
"total_items_in_this_category": 55
},
{
"id": "MLB10356",
"name": "Asia",
"total_items_in_this_category": 30
},
{
"id": "MLB180276",
"name": "Aston Martin",
"total_items_in_this_category": 14
},
{
"id": "MLB5782",
"name": "Audi",
"total_items_in_this_category": 2313
},
{
"id": "MLB5783",
"name": "BMW",
"total_items_in_this_category": 3150
},
{ ...
}
],
"attribute_types": "attributes",
"settings": {
"adult_content": false,
"buying_allowed": false,
"buying_modes": [
"classified"
],
"catalog_domain": "MLB-CARS_AND_VANS",
"coverage_areas": "not_allowed",
"currencies": [
"BRL"
],
"fragile": false,
"immediate_payment": "optional",
"item_conditions": [
"not_specified",
"used",
"new"
],
"items_reviews_allowed": false,
"listing_allowed": false,
"max_description_length": 50000,
"max_pictures_per_item": 15,
"max_pictures_per_item_var": 6,
"max_sub_title_length": 70,
"max_title_length": 60,
"maximum_price": null,
"minimum_price": null,
"mirror_category": null,
"mirror_master_category": null,
"mirror_slave_categories": [],
"price": "required",
"reservation_allowed": "mandatory",
"restrictions": [],
"rounded_address": false,
"seller_contact": "optional",
"shipping_modes": [
"not_specified",
"custom"
],
"shipping_options": [
"custom"
],
"shipping_profile": "not_allowed",
"show_contact_information": true,
"simple_shipping": "not_allowed",
"stock": "required",
"sub_vertical": "cars",
"subscribable": false,
"tags": [],
"vertical": "motors",
"vip_subdomain": "carro",
"buyer_protection_programs": [
"delivered",
"undelivered"
],
"status": "enabled"
},
"meta_categ_id": null,
"attributable": true,
"date_created": "2018-04-25T08:12:56.000Z"
}Preditor de categorias
Para identificar a melhor categoria para o seu produto, faça uma chamada GET no recurso /domain_discovery com o título da sua publicação. A primeira resposta é a que tem maior probabilidade.
Parâmetros obrigatórios
site_id: é o site onde você publica.
q: é o título do artigo a prever e deve estar completamente no idioma do site.
Parâmetros opcionais
limit: o valor padrão será 4, mas pode chegar a 8, para que você possa definir um limite entre 1 e 8.
target: pode ser constituído por core ou classified, dependendo da vertical em que está sendo publicado.
Chamada:
curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/domain_discovery/search?q=$QExemplo:
curl -X GET https://api.mercadolibre.com/sites/MLB/domain_discovery/search?limit=1&q=fiat%20unoResposta
[
{
"domain_id": "MLB-CARS_AND_VANS",
"domain_name": "Carros e caminhonetes",
"category_id": "MLB24322",
"category_name": "Uno",
"attributes": []
}
]Campos da resposta
domain_id: ID do domínio previsto para o item.
domain_name: nome do domínio previsto.
category_id: ID da categoria prevista para o item.
category_name: nome da categoria prevista.
attributes: lista de atributos para a categoria prevista.
Atributos específicos das categorias
Para conhecer os atributos específicos e valores possíveis das categorias que você deve encaminhar para publicar um produto, consulte o recurso /attributes.
Chamada:
curl -X GET https://api.mercadolibre.com/categories/MLB1744/attributesResposta resumida:
[
{
"id": "BRAND",
"name": "Marca",
"tags": {
"catalog_required": true,
"required": true
},
"hierarchy": "PARENT_PK",
"relevance": 1,
"value_type": "string",
"value_max_length": 255,
"values": [
...
{
"id": "389168",
"name": "Chery"
},
{
"id": "58955",
"name": "Chevrolet"
},
{
"id": "66395",
"name": "Chrysler"
},
{
"id": "389169",
"name": "Citroën"
},
...
],
"attribute_group_id": "FIND",
"attribute_group_name": "Ficha técnica"
},
{
"id": "MODEL",
"name": "Modelo",
"tags": {
"catalog_required": true,
"required": true
},
"hierarchy": "PARENT_PK",
"relevance": 1,
"value_type": "string",
"value_max_length": 255,
"values": [
...
{
"id": "389394",
"name": "Aircross"
},
{
"id": "389395",
"name": "Airtrek"
},
{
"id": "71720",
"name": "Albea"
},
{
"id": "60597",
"name": "Alhambra"
},
{
"id": "64101",
"name": "Alliance"
},
...
],
"attribute_group_id": "FIND",
"attribute_group_name": "Ficha técnica"
},
{
"id": "VEHICLE_YEAR",
"name": "Año",
"tags": {
"required": true
},
"hierarchy": "PARENT_PK",
"relevance": 1,
"value_type": "number",
"value_max_length": 18,
"attribute_group_id": "FIND",
"attribute_group_name": "Ficha técnica"
},
{
"id": "TRIM",
"name": "Versión",
"tags": {
"catalog_required": true,
"required": true
},
"hierarchy": "PARENT_PK",
"relevance": 1,
"value_type": "string",
"value_max_length": 255,
"attribute_group_id": "FIND",
"attribute_group_name": "Ficha técnica"
},
{
...
}
]Atributos obrigatórios
Os atributos obrigatórios são configurados como “required” nos detalhes da categoria. No exemplo anterior, você pode observar que marca e modelo são obrigatórios; não são autorizadas áreas de cobertura e o seller_contact é opcional.
Valores mais utilizados (top values)
Com este recurso, você poderá saber quais são os valores mais utilizados para um atributo específico de um domínio. Também é possível pesquisar mais, indicando outros valores de atributo, para que apenas os valores que se apliquem a eles sejam listados.
Os vendedores poderão usar os valores obtidos para escolher o correto entre eles e melhorar a qualidade das publicações.
Parâmetros obrigatórios
omain_id: ID do domínio ao qual queremos nos referir.
attribute_id: ID do atributo do qual precisamos conhecer os valores mais usados.
Parâmetros opcionais
limit: o limite de resultados solicitados têm no máximo 1000.
metric_type: métrica pela qual os resultados serão ordenados, a princípio, apenas NOLs (novas publicações nos últimos 90 dias) são suportadas. O único parâmetro no momento é NOL_90. Novos critérios serão adicionados no futuro. Exemplo: metric_type = NOL_90.
Para identificar os atributos recomendados e conhecidos, deve executar um POST.
Chamada simples com um único atributo:
curl -X POST https://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/attributes/$ATTRIBUTE_ID/top_valuesExemplo:
curl -X POST https://api.mercadolibre.com/catalog_domains/MLB-CARS_AND_VANS/attributes/BRAND/top_valuesResposta:
[
{
"id": "60249",
"name": "Volkswagen",
"metric": 7987
},
{
"id": "66432",
"name": "Ford",
"metric": 5619
},
{
"id": "9909",
"name": "Renault",
"metric": 4659
},
{
"id": "58955",
"name": "Chevrolet",
"metric": 4319
},
{
"id": "60279",
"name": "Peugeot",
"metric": 4285
},
{
"id": "67781",
"name": "Fiat",
"metric": 4172
},
...
]Exemplo com mais de um atributo
Chamada
curl -X POST https://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/attributes/$ATTRIBUTE_ID/top_values
{
"known_attributes": [
{
"id": "attributes.id",
"value_id": "attributes.value_id"
}
]
}Exemplo
{
"known_attributes": [
{
"id": "BRAND",
"value_id": "60249"
}
]
}Nesse caso, o conteúdo da resposta será os modelos mais usados da marca Volkswagen 6249.
Dump de categorias
Lembre-se de que recomendamos o uso do preditor de categorias na sua aplicação. Mas se você preferir, pode solicitar o dump de toda a árvore de categorias para o site de um determinado país para processamento offline. A API retorna a árvore de categorias no formato JSON em uma resposta codificada em gzip. Para obter as categorias do Brasil, utilize a URL abaixo:
curl -X GET https://api.mercadolibre.com/sites/MLB/categories/allEssa URL contém dois cabeçalhos que podem ser utilizados para verificar quando foi gerado o último dump.
X-Content-Created: contém a data da última geração.
X-Content-MD5: contém a soma de verificação MD5 da última geração.
Chamada:
curl -X GET https://api.mercadolibre.com/sites/MLB/categories/allResposta
HTTP/2 200
content-type: application/json
content-length: 0
date: Wed, 29 Apr 2020 20:40:14 GMT
x-amz-id-2: VTcFVSUdn06VM4dbsuP5vZyHQ5fycw3kHjUgzRxEzSJxSJfEuYpr9DlHZ6ab+2DPvJ/SD97R7OQ=
x-amz-replication-status: COMPLETED
x-amz-request-id: 8BA998DE0241013D
x-amz-version-id: nhcoZXYi83Rh5CjxRYMmFLRIPO_cz7yl
x-content-type-options: nosniff
x-request-id: 071f0a43-1b95-4b04-accd-77646bd6dc3e
x-frame-options: DENY
x-xss-protection: 1; mode=block
access-control-allow-origin: *
access-control-allow-headers: Content-Type
access-control-allow-methods: PUT, GET, POST, DELETE, OPTIONS
access-control-max-age: 86400
accept-ranges: bytes
last-modified: Wed, 29 Apr 2020 20:01:12 GMT
cache-control: max-age=300
content-encoding: gzip
x-content-created: 2020-04-29T20:01:12.000Z
x-content-md5: 7526ed93467ec227359522beac126d82
x-cache: Miss from cloudfront
via: 1.1 b7b2667a8f791fb60d70bb1835ef9b2b.cloudfront.net (CloudFront)
x-amz-cf-pop: GRU1-C1
x-amz-cf-id: bvgXHVEFMS1BSLQCqEJxXmUL6zMRQQnCHBCCJMg78WUfPLVYGubO8Q==Busca por categorias
Na operação de busca aparecem produtos pertencentes a uma categoria de produto do Mercado Livre. Apesar de existirem toneladas de produtos em algumas categorias, não se preocupe: você poderá paginar os resultados. Leia sobre paginação dos resultados de busca. Para obter todos os produtos de uma determinada categoria, você precisa fazer o seguinte:
curl -X GET https://api.mercadolibre.com/MLB/search?category=MLB5726A resposta da busca tem uma enorme quantidade de parâmetros. Utilize o método http OPÇÕES para obter uma resposta codificada em JSON que descreverá a API com todos os métodos e conexões permitidos entre ele e a outra parte da API.
Paginação e dimensionamento dos resultados
Daqui em diante, este tutorial será útil para trabalhar com conjuntos específicos de resultados toda vez que você fizer uma chamada à API. A maior parte dos recursos apresentam parâmetros URL normais para paginar e dimensionar resultados: limit e offset.
Valores padrão
Os valores padrões são: offset=0 e limit=50.
curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatunoNa seção de paginação da resposta JSON, você pode visualizar a quantidade total de produtos que correspondem à busca e o valor de offset com o limit padrão aplicado.
.....
"paging": {
"total": 285,
"offset": 0,
"limit": 50,
}
.....Limit
Para reduzir o tamanho da página, você pode alterar o parâmetro do limite. Por exemplo, caso esteja interessado em recuperar somente os três primeiros produtos.
Exemplo:
curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&limit=3Essa ação recupera dados do JSON com um conjunto de três produtos, conforme mostrado a seguir:
Exemplo:
{
"site_id": "MLB",
"query": "fiatuno",
"paging": {
"total": 284,
"offset": 0,
"limit": 3,
},
"results": [
{...},
{...},
{...},
],
"sort": {...},
"available_sorts": [...],
"filters": [...],
"available_filters": [...],
}Offset
Ao usar o atributo offset, você pode mover o limite inferior do bloco de resultados. Por exemplo, se estiver interessado em recuperar os 50 produtos que seguem à resposta padrão.
Exemplo
curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&offset=50Resposta
{
"site_id": "MLB",
"query": "fiatuno",
"paging": {
"total": 285,
"offset": 50,
"limit": 50,
},
"results": [...],
"sort": {...},
"available_sorts": [...],
"filters": [...],
"available_filters": [...],
}A resposta acima recupera 50 produtos a partir dos primeiros cinquenta.
Definição de uma faixa de resultados
Ambos parâmetros podem ser combinados. Você pode recuperar produtos do terceiro ao sexto no resultado da busca original:
curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&offset=3&limit=3Essa ação recupera um dado do JSON com um conjunto de três produtos, conforme mostrado a seguir:
{
"site_id": "MLB",
"query": "fiatuno",
"paging": {
"total": 285,
"offset": 3,
"limit": 3,
},
"results": [
{...},
{...},
{...},
],