Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 04/12/2024

Consulta de usuários


Caso você já tenha conseguido registrar seu aplicativo, tenha feito a autenticação e gerado um usuário de teste, você deverá aprender a trabalhar com usuários (vendedores e compradores).


Consultar meus dados pessoais

Se você já tiver feito login no Mercado Livre e tiver um token, poderá fazer a seguinte chamada para saber quais são as informações relacionadas a seu usuário.


Exemplo:

 curl - X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/me

Resposta:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_50698062@testuser.com",
  "identification": {
    "type": "DNI",
    "number": "1111111"
  },
  "address": {
    "state": "AR-C",
    "city": "Palermo",
    "address": "Test Address 123",
    "zip_code": "1414"
  },
  "phone": {
    "area_code": "01",
    "number": "1111-1111",
    "extension": "",
    "verified": false
  },
  "alternative_phone": {
    "area_code": "",
    "number": "",
    "extension": ""
  },
  "user_type": "real_estate_agency",
  "tags": [
    "real_estate_agency",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "seller_experience": "ADVANCED",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 0,
      "completed": 0,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 0
      }
    }
  },
  "buyer_reputation": {
    "canceled_transactions": 0,
    "transactions": {
      "period": "historic",
      "total": null,
      "completed": null,
      "canceled": {
        "total": null,
        "paid": null
      },
      "unrated": {
        "total": null,
        "paid": null
      },
      "not_yet_rated": {
        "total": null,
        "paid": null,
        "units": null
      }
    },
    "tags": [
    ]
  },
  "status": {
    "site_status": "active",
    "list": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "buy": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "sell": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "billing": {
      "allow": true,
      "codes": [
      ]
    },
    "Mercado Pago_tc_accepted": true,
    "Mercado Pago_account_type": "personal",
    "Mercado Envios": "not_accepted",
    "immediate_payment": false,
    "confirmed_email": false,
    "user_type": "eventual",
    "required_action": ""
  },
  "credit": {
    "consumed": 100,
    "credit_level_id": "MLA1"
  }
}

Consultar dados de terceiros

Se você não sabe o id, mas sabe o apelido e o site ao qual um usuário pertence, você poderá obtê-lo fazendo a seguinte busca.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?nickname=$NICKNAME

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?nickname=TETE2870021

Resposta:

{
  "site_id": "MLA",
  "seller": {
  "id": 202593498,
  "seller_reputation": {
    "power_seller_status": null
  },
  "real_estate_agency": false,
  "car_dealer": false,
  "tags": [
  ]
  }

Se você quiser consultar dados de usuários, terceiros poderá identificar dois níveis de informações: dados públicos, aqueles que podem ser encontrados navegando pelo perfil no Mercado Livre de qualquer outro usuário, Ex.: http://perfil.mercadolibre.com.ar/TETE2870021 e dados privados, que não poderão ser visualizados, a menos que você tenha permissões de usuário e um token válido para trabalhar em nome dele. Em ambos os casos, a primeira coisa que você deverá conhecer é o id do usuário.


Obter o Id de usuário

Se você não sabe o id, mas sabe o apelido e o site ao qual um usuário pertence, você poderá obtê-lo fazendo a seguinte busca.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/search?nickname=$NICKNAME

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?nickname=TETE2870021

Resposta:

{
  "site_id": "MLA",
  "seller": {
  "id": 202593498,
  "seller_reputation": {
    "power_seller_status": null
  },
  "real_estate_agency": false,
  "car_dealer": false,
  "tags": [
  ]
  },
  "paging": {
  "total": 2,
  "offset": 0,
  "limit": 50
  },
  "results": [
  {
    "id": "MLA598903377",
    "site_id": "MLA",
    "title": "Test Item - Nao Ofertar",
    "subtitle": null,
    "seller": {
      "id": 202593498,
      "power_seller_status": null,
      "car_dealer": false,
      "real_estate_agency": false,
      "tags": [
      ]
    },
    "price": 200,
    "currency_id": "ARS",
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "stop_time": "2016-03-06T17:16:49.000Z",
    "condition": "new",
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-598903377-test-item-nao-ofertar-_JM",
    "thumbnail": "http://mla-s2-p.mlstatic.com/546311-MLA20539702714_012016-I.jpg",
    "accepts_mercadopago": true,
    "installments": {
      "quantity": 6,
      "amount": 42.33,
      "currency_id": "ARS"
    },
    "address": {
      "state_id": "AR-C",
      "state_name": "Capital Federal",
      "city_id": "",
      "city_name": "Palermo"
    },
    "shipping": {
      "free_shipping": false,
      "mode": "not_specified"
    },
    "seller_address": {
      "id": 175597910,
      "comment": "",
      "address_line": "",
      "zip_code": "",
      "country": {
        "id": "AR",
        "name": "Argentina"
      },
      "state": {
        "id": "AR-C",
        "name": "Capital Federal"
      },
      "city": {
        "id": "",
        "name": "Palermo"
     },
      "latitude": -34.571148,
      "longitude": -58.423298
    },
    "attributes": [
    ],
    "original_price": null,
    "category_id": "MLA374515",
    "official_store_id": null
  },
  {
    "id": "MLA599121050",
    "site_id": "MLA",
    "title": "Item De Test - No Ofertar",
    "subtitle": null,
    "seller": {
      "id": 202593498,
      "power_seller_status": null,
      "car_dealer": false,
      "real_estate_agency": false,
      "tags": [
      ]
    },
    "price": 1000,
    "currency_id": "ARS",
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "stop_time": "2016-03-07T20:12:41.000Z",
    "condition": "new",
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-599121050-item-de-test-no-ofertar-_JM",
    "thumbnail": "http://mla-s2-p.mlstatic.com/493311-MLA20538550251_012016-I.jpg",
    "accepts_mercadopago": true,
    "installments": {
      "quantity": 6,
        "amount": 211.65,
      "currency_id": "ARS"
    },
    "address": {
      "state_id": "AR-C",
      "state_name": "Capital Federal",
      "city_id": "",
      "city_name": "Palermo"
    },
    "shipping": {
      "free_shipping": false,
      "mode": "not_specified"
    },
    "seller_address": {
      "id": 175597910,
      "comment": "",
      "address_line": "",
      "zip_code": "",
      "country": {
        "id": "AR",
        "name": "Argentina"
      },
      "state": {
        "id": "AR-C",
        "name": "Capital Federal"
      },
      "city": {
        "id": "",
        "name": "Palermo"
      },
      "latitude": -34.571148,
      "longitude": -58.423298
    },
    "attributes": [
    ],
    "original_price": null,
    "category_id": "MLA90105",
    "official_store_id": null
  }
  ],
  "secondary_results": [
  ],
  "related_results": [
  ],
  "sort": {
  "id": "relevance",
  "name": "More relevant"
  },
  "available_sorts": [
  {
   "id": "price_asc",
    "name": "Lower price"
  },
  {
    "id": "price_desc",
    "name": "Higher price"
  }
  ],
  "filters": [
  ],
  "available_filters": [
  {
    "id": "category",
    "name": "Categories",
    "type": "text",
    "values": [
      {
        "id": "MLA1648",
        "name": "Computación",
        "results": 1
      },
      {
        "id": "MLA1430",
        "name": "Ropa y Accesorios",
        "results": 1
      }
    ]
  },
  {
    "id": "state",
    "name": "Location",
    "type": "text",
    "values": [
      {
        "id": "TUxBUENBUGw3M2E1",
        "name": "Capital Federal",
        "results": 2
      }
    ]
  },
  {
    "id": "accepts_mercadopago",
   "name": "MercadoPago filter",
    "type": "boolean",
    "values": [
      {
        "id": "yes",
        "name": "With MercadoPago",
        "results": 2
      }
    ]
  },
  {
    "id": "installments",
    "name": "Pago",
    "type": "text",
    "values": [
      {
        "id": "yes",
        "name": "Installments",
        "results": 2
      },
      {
        "id": "no_interest",
        "name": "Sin interés",
        "results": 0
      }
    ]
  },
  {
    "id": "condition",
    "name": "Condition filter",
    "type": "text",
    "values": [
      {
        "id": "new",
        "name": "New",
        "results": 2
      }
    ]
  },
  {
    "id": "buying_mode",
    "name": "Buying mode filter",
    "type": "text",
    "values": [
      {
        "id": "buy_it_now",
        "name": "Buy it now",
        "results": 2
      }
    ]
  },
  {
    "id": "has_pictures",
    "name": "Items with images filter",
    "type": "boolean",
    "values": [
      {
        "id": "yes",
        "name": "With pictures",
        "results": 2
      }
    ]
  }
  ]
}

Consultar informações públicas

Desse modo, você já conhece o Id do usuário, portanto pode realizar a chamada ao recurso users da seguinte maneira, obtendo as informações públicas do usuário que quiser.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/202593498

Resposta:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "country_id": "AR",
  "address": {
    "state": "AR-C",
    "city": "Palermo"
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 0,
      "completed": 0,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 0
      }
    }
  },
  "buyer_reputation": {
    "tags": [
    ]
  },
  "status": {
    "site_status": "active"
  }
}

Consultar informações privadas de um usuário que aceitou o uso de meu aplicativo

Para obter os dados privados de um usuário, você apenas deve adicionar o ACCESS_TOKEN do usuário ao final da chamada que fez anteriormente.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/202593498

Resposta:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_50698062@testuser.com",
  "identification": {
    "type": "DNI",
    "number": "1111111"
  },
  "address": {
    "state": "AR-C",
    "city": "Palermo",
    "address": "Test Address 123",
    "zip_code": "1414"
  },
  "phone": {
    "area_code": "01",
    "number": "1111-1111",
    "extension": "",
    "verified": false
  },
  "alternative_phone": {
    "area_code": "",
    "number": "",
    "extension": ""
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "seller_experience": "ADVANCED",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 0,
      "completed": 0,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 0
      }
    }
  },
  "buyer_reputation": {
    "canceled_transactions": 0,
    "transactions": {
      "period": "historic",
      "total": null,
      "completed": null,
      "canceled": {
        "total": null,
        "paid": null
      },
      "unrated": {
        "total": null,
        "paid": null
      },
      "not_yet_rated": {
        "total": null,
        "paid": null,
        "units": null
      }
    },
    "tags": []
  },
  "status": {
    "site_status": "active",
    "list": {
      "allow": true,
      "codes": [],
      "immediate_payment": {
        "required": false,
        "reasons": []
      }
    },
    "buy": {
      "allow": true,
      "codes": [],
      "immediate_payment": {
        "required": false,
        "reasons": []
      }
    },
    "sell": {
      "allow": true,
      "codes": [],
      "immediate_payment": {
        "required": false,
        "reasons": []
      }
    },
    "billing": {
      "allow": true,
      "codes": []
    },
    "mercadopago_tc_accepted": true,
    "mercadopago_account_type": "personal",
    "mercadoenvios": "not_accepted",
    "immediate_payment": false,
    "confirmed_email": false,
    "user_type": "eventual",
    "required_action": ""
  },
  "credit": {
    "consumed": 100,
    "credit_level_id": "MLA1"
  }
}

Como pode ver, dessa vez você obteve uma quantidade maior de dados do usuário: nome e sobrenome, e-mail, telefone, endereço etc. Solicitamos que não revele esses dados publicamente, pois isso pode prejudicar o usuário.


Gerencia bloqueios de compradores para perguntas

Chamada:


curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-type: application/json" -d '{
    "request": {
        "curl": "curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/questions_blacklist"
    }
}'
Importante:
Estamos migrando os endpoints usados para bloquear e desbloquear compradores nas funcionalidades de pedidos e perguntas. A data de desativação dos endpoints antigos e, portanto, de migração, é: 02/12/2024. Com isso, apenas a informação do próximo tópico será válida.

Endpoint block-api/search/users: Consultar usuários bloqueados para pedidos e perguntas:

O endpoint block-api/search/users permite consultar bloqueios associados a um usuário (Comprador) específico, retornando informações sobre o estado do bloqueio. Os serviços de bloqueio de perguntas e pedidos foram unificados em um único endpoint.

  • Blocked_by_questions: Para bloqueios relacionados a perguntas.
  • Blocked_by_order: Para bloqueios relacionados a pedidos.
Parâmetro TIPO Obrigatório Descrição
client.id string Opcional ID do cliente que realiza a solicitação
type string Obrigatório Tipo de bloqueio: blocked_by_questions ou blocked_by_order.
user_blocked int Opcional ID do usuário bloqueado (Comprador).
caller.id string Obrigatório ID do usuário que faz a solicitação.
offset int opcional padrão: 0
limit int opcional máximo 1000, padrão: 10

Chamada:


curl -X GET  'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/block-api/search/users/{user_id}

Exemplo de solicitação: blocked_by_questions


curl -X GET - location 'https://api.mercadolibre.com/block-api/search/users/123456?type=blocked_by_questions' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Resposta:


{
  "users": [
    {
      "id": 123456,
      "blocked_at": "2024-02-07T15:04:05Z"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10,
    "total": 1
  }
}

Código de Status: 200 OK - A solicitação foi processada com sucesso.


Exemplo de solicitação: blocked_by_order


curl -X GET -location 'https://api.mercadolibre.com/block-api/search/users/123456?type=blocked_by_order' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Resposta:


{
  "users": [
    {
      "id": 123456,
      "blocked_at": "2024-02-07T15:04:05Z"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10,
    "total": 1
  }
}

Código de Status: 200 OK - A solicitação foi processada com sucesso.


Exemplo de Resposta Sem Bloqueios (blocked_by_questions ou blocked_by_order)

Resposta:


{
  "users": [
    {
      "id": 123456,
      "blocked_at": "2024-02-07T15:04:05Z"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10,
    "total": 1
  }
}
  • users: Indica que não há usuários bloqueados relacionados nem com perguntas nem com pedidos para o usuário solicitado.
  • paging: Mostra que não há resultados, com total igual a 0.

Campos da Resposta:

Campo Tipo Descrição
users.id int ID do usuário bloqueado.
users.blocked_at string Data e hora da criação do bloqueio.
paging.offset int Número de bloqueios omitidos antes de retornar os resultados.
paging.limit int Quantidade máxima de bloqueios a recuperar (padrão 10, máximo 1000).
paging.total int Total de bloqueios recuperados.

Excluir usuário bloqueado

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$YOUR_CUST_ID/order_blacklist/$SELLER_ID

Códigos de erro comuns

206 – Conteúdo parcial: em alguns casos, o recurso da API de Usuários retornará um código 206 – Conteúdo parcial. Isso ocorrerá quando a solicitação falhar ao obter alguns dos dados (por exemplo, reputação do usuário), informando que você receberá uma resposta incompleta.