Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

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

Receba notificações

Alguns eventos são produzidos apenas do lado do Mercado Livre e a única forma de conhecê-los é por notificações. Com as notificações você terá um feed em tempo real das mudanças produzidas nos diferentes recursos da nossa API. Por exemplo, se você anunciou um item e mais tarde decidiu pausá-lo, se alguém formulou alguma pergunta, se compraram um item ou até se pagaram e/ou solicitaram o envio. Uma maneira eficiente sem ter que consultar permanentemente nossa API!

Inscreva-se para receber notificações

Se quiser começar a receber notificações, você deverá acessar seu gerenciador de aplicativos, onde você criou seu aplicativo pela primeira vez, editar os detalhes especificando quais são os topics que você receberá. Caso você ainda não tenha criado seu aplicativo, acesse seção Criar a sua aplicação.

URL de retorno de chamada de notificação: configure a URL pública do domínio onde você quer receber notificações sobre os diversos tópicos. Por exemplo: “http://myapp.com/notifications”.

Tópicos: selecione dentre os diferentes tópicos para receber notificações.

Nota:

- Os topics created_orders, payments e messages não são utilizados para imóveis, serviços e automóveis.
- As notificações têm zona horária UTC.

Topics disponíveis

items: Você receberá notificações sobre qualquer mudança em um item que tiver publicado.

questions: Você receberá notificações de perguntas e respostas feitas.

payments: Você receberá notificações quando um pagamento for criado em uma ordem ou o status dela mudar.

messages: Você receberá notificações sobre novas mensagens geradas com seu user_id como destinatário.

orders_v2: Você receberá notificações a partir da criação e alterações realizadas em alguma de suas vendas confirmadas. (recomendável).

shipments: Você receberá notificações a partir da criação e alterações realizadas nos envios (shippings) de suas vendas confirmadas.

orders feedback: receberá notificações sobre a criação e alterações feitas nos feedbacks de suas vendas confirmadas.

quotations: Você receberá notificações referente a cotações que ocorram nas publicações (aplicável apenas para integração de imóveis de Mercado Libre Chile).

invoices: Você receberá notificações referente a invoices geradas (notas fiscais) através do faturamento automático feito pelo mercadolivre (aplicável somente a quem trabalha com o Faturamento com Mercado Envios Full).

claims: Você receberá notificações referente a reclamações que sejam feitas referente às vendas. Veja mais Trabalhar com reclamações.

item competition: você receberá notificações quando as publicações de catálogo concorrentes mudarem de status. Tanto do competidor para o vencedor e vice-versa.

Nota:

Você deve usar o recurso /price_to_win para verificar a condição do item e fazer as ações necessárias para ganhar a página do produto.

catalog_suggestions: você receberá notificações das mudanças de status das sugestões de produtos para nosso catálogo - Brand Central.

leads credits: receberá notificações relacionadas a créditos aprovados ou rejeitados no Mercado Livre (aplica-se a veículos, e imóveis).

stock fulfillment: Você receberá notificações com os detalhes de uma determinada operação executada nas ações que o vendedor armazenou nos depósitos de FBM.

public candidates: você receberá as notificações sempre que um item for convidado a fazer parte de uma promoção.

items_prices: receberá notificações do item_id cada vez que o preço for criado, atualizado ou excluído.

public offers: você receberá as notificações quando se cria ou altera o status de uma oferta em um item.

flex-handshakes: você receberá notificações quando houverem transferências de pacotes entre transportadoras e quando escanear pela primeira vez (quando for marcado como shipped).

stock_locations: Você receberá notificações quando os stock_locations do user_product forem modificados, aumentando ou diminuindo o campo de quantidade.

Quais eventos disparam notificações?

Tenha em conta que toda e qualquer mudança que houver no Json, em qualquer tópico, serão disparadas as notificações correspondentes às estas.
É importante que sempre escute as notificações e, em seguida, faça-se a consulta no recurso correspondente para verificar se há alguma mudança em relação à sua aplicação, pois as mudanças podem ocorrer também de outras fontes, como ação via front, Seller Central ou outras aplicações, etc.

Considerações Importantes

Importante:

Atualize sua integração para ter sempre retorno, HTTP 200 e em 500 milissegundos após o recebimento da notificação, com isso você evitará que os tópicos de suas notificações sejam desativados por fall back. Tenha em conta que caso ocorra a desativação, as notiifcações correspondentes a este período não serão salvas no my feeds, e você terá que se inscrever novamente nos tópicos.

Enviaremos um POST a callback URL e seu aplicativo deverá confirmar mediante um HTTP 200 o recebimento correto. Caso contrário, a mensagem será considerada não entregue e haverá uma nova tentativa de envio.
As mensagens serão enviadas e novas tentativas de envio serão feitas durante um intervalo de 1 hora. Depois desse período, se não forem aceitas pelo aplicativo, elas serão excluídas.
Sabendo que pode haver uma grande quantidade de notificações, é recomendável que se trabalhe com filas, onde seu servidor deverá confirmar o recebimento das notificações (HTTP 200) instantaneamente e apenas em seguida faça a consulta do tópico na API; assim, evita que sejam feitas novas tentativas de notificações e não gerará a sensação de notificações duplicadas.
Leve em conta que há eventos internos não visíveis para o integrador, porém estes disparam notificações.

Acesso aos detalhes

Depois de receber uma notificação sobre um tópico, você deverá fazer uma solicitação GET ao recurso para acessar os detalhes e, depois, se tiver salvado o JSON anterior, deverá comparar os dois.

items

Notification response:

{
   "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",    
   "resource": "/items/MLA686791111",
   "user_id": 123456789,
   "topic": "items",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:44:33.006Z",
   "received": "2017-10-09T13:44:32.984Z"
}

Com essas informações, você poderá realizar um GET para o recurso de items:

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

orders_v2

Resposta da notificação:

{
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",   
  "resource":"/orders/2195160686",
  "user_id": 468424240,
  "topic":"orders_v2",
  "application_id": 5503910054141466,
  "attempts":1,
  "sent":"2019-10-30T16:19:20.129Z",
  "received":"2019-10-30T16:19:20.106Z"
}

Com essas informações, você poderá realizar um GET para o recurso mensagens:

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

questions

Notification response:

{
   "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",   
   "resource": "/questions/5036111111",
   "user_id": 123456789,
   "topic": "questions",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:51:05.464Z",
   "received": "2017-10-09T13:51:05.438Z"
}

Con esta información podrás realizar un GET al recurso de questions:

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

payments

Notification response:

{
   "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",    
   "resource": "/collections/3043111111",
   "user_id": 123456789,
   "topic": "payments",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2017-10-09T13:58:22.081Z",
   "received": "2017-10-09T13:58:22.061Z"
}

Com essas informações, você poderá realizar um GET para o recurso de questions:

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

messages

Resposta da notificação:

{
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource": "3f6da1e35ac84f70a24af7360d24c7bc",
  "user_id": 268897726,
  "topic": "messages",
  "application_id": 2219612378080430,
  "attempts": 1,
  "sent": "2017-08-17T12:59:44.164Z",
  "received": "2017-08-17T12:59:44.131Z"
 }

Com essas informações, você pode executar um GET no recurso de mensagem:

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

quotations

Resposta da notificação:

{
    "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",       
    "resource":"/quotations/5013267",
    "user_id": 484630370,
    "topic":"quotations",
    "application_id": 5503910054141466,
    "attempts":1,
    "sent":"2019-10-30T14:04:14.584Z",
    "received":"2019-10-30T14:04:14.553Z"
}

Nota:

As notificações sobre cotações estão disponíveis apenas para o Mercado Libre Chile.

Com essas informações, você poderá realizar um GET para o recurso orders:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/quotations/$QUOTATION_ID?caller.type=seller

Onde caller.type é identificar quem é o gerador da ação. Pode ser um vendedor ou um usuário. Geralmente, para aplicativos de lançamento, será o do vendedor.

invoices

Notification response:

{
    "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",       
    "resource": "/users/123456789/invoices/$INVOICE_ID",
    "user_id": 123456789,
    "topic": "invoices",
    "application_id": 5503910054141466,
    "attempts": 1,
    "sent": "2018-03-21T20:51:11.906Z",
    "received": "2018-03-21T20:51:11.884Z"
}

Com essas informações, você poderá realizar um GET para o recurso /invoices:

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

claims

Notification response:

{
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource":"/v1/claims/1041417027",
  "user_id": 465432224,
  "topic":"claims",
  "application_id":5503910054141466,
  "attempts":1,
  "sent":"2019-10-29T17:46:24.606Z",
  "received":"2019-10-29T17:46:24.616Z"
}

Com essas informações, você poderá realizar um GET para o recurso /claims:

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

item competition

Importante:

Este tópico está disponível na Argentina, Brasil e México.

Notificação:

{
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource":"/items/ITEM_ID/price_to_win",
  "user_id": 123456789,
  "topic":"catalog_item_competition_status",
  "application_id":4806348059754779,
  "attempts":1,
  "sent":"2020-03-03T18:57:54.824Z",
  "received":"2020-03-03T18:57:54.819Z"
}

Com essas informações, você poderá realizar um GET para o recurso /price_to_win:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win

catalog suggestions

Notificação:

{

  "topic": "catalog_suggestions",
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource": "/catalog_suggestions/MLA123456",
  "user_id": 123456,
  "application_id": 5775857146034005,
  "attempts": 1,
  "recieved": "2021-12-05T17:13:53.617074685Z",
  "sent": "2021-12-05T19:22:31.579985295Z"
}

Com esta informação, poderá realizar um GET ao recurso de /catalog_suggestions:

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

Leads credits

Notificação:

{
  "_id": "15b0e685-65be-40b6-8d23-alkdjf6465a4f",
  "topic": "leads-credits",
  "resource": "/vis/loans/66e93589-2d10-11ed-ae7f-0aa30fafa621",
  "user_id": 123456789,
  "application_id": 874563217565897,
  "sent": "2022-09-13T21:03:24.581Z",
  "attempts": 2,
  "received": "2022-09-13T21:02:22.735Z"
}

Com essas informações, você pode executar um GET para o recurso /vis/loans:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/loans/$CREDIT_ID?seller_id=$SELLER_ID

stock fulfillment

Importante:

Este tópico está disponível na Argentina, Brasil, México, Chile y Colombia.

Notificação:

{
   "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",      
   "resource":"/stock/fulfillment/operations/9876",
   "user_id":1234,
   "topic":"fbm_stock_operations",
   "application_id":12341234,
   "attempts":1,
   "sent":"2017-10-09T13:58:23.347Z",
   "received":"2017-10-09T13:58:23.329Z"
}

Com essas informações, você poderá realizar um GET para o recurso /stock/fulfillment/operations:

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

public candidates

Notificação:

{
  "topic": "public_candidates",
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource": "/seller-promotions/candidates/CANDIDATE-MLA1111111111-11111111",
  "user_id": 2222222,
 "application_id": 5111111111111,
 "attempts": 1,
 "recieved": "2021-12-23T17:13:53.617074685Z",
 "sent": "2021-12-23T19:22:31.579985295Z"
}

Com esta informação você poderá realizar um GET no recurso /seller-promotions/candidates:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID

items_prices

Notificação:

{
   "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",
   "resource": "/items/MLA686791111/prices",
   "user_id": 123456789,
   "topic": "items",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2023-02-06T13:44:33.006Z",
   "received": "2023-02-06T13:44:32.984Z"
}

Com essas informações, você pode realizar um GET para o recurso /prices:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/prices

public offers

Notificação:

{
  "topic": "public_offers",
  "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",     
  "resource": "/seller-promotions/offers/1234567",
  "user_id": 2222222,
  "application_id": 5111111111111,
  "attempts": 1,
  "recieved": "2022-01-20T17:13:53.617074685Z",
  "sent": "2022-01-20T19:22:31.579985295Z"
}

Com esta informação você poderá realizar um GET no recurso /seller-promotions/offers:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID

flex transportadora

Notificação:

{
"_id": "495cac10-8496-45f8-a6f5-8bff0a948597",
"topic": "flex-handshakes",
"resource": "/flex/sites/MLA/shipments/407323124706/assignment/v1",
"user_id": 123456789,
"application_id": 213123389095511,
"sent": "2022-09-13T21:06:13.632Z",
"attempts": 4,
"received": "2022-09-13T20:59:13.911Z"
}

Chamada:

Com esta informação poderá realizar um GET ao seguinte recurso:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/shipments/$SHIPMENT_ID/assignment/v1

stock_locations

Notificação:

{
"_id": "495cac10-8496-45f8-a6f5-8bff0a948597",
"topic": "stock-location",
"resource": "/user-products/$USER_PRODUCT_ID/stock",
"user_id": 123456789,
"application_id": 213123389095511,
"sent": "2022-09-13T21:06:13.632Z",
"attempts": 4,
"received": "2022-09-13T20:59:13.911Z"
}

Chamada:

Com esta informação poderá realizar um GET ao recurso de User product ID.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/ultron/public/sites/$SITE_ID/shipments/$SHIPMENT_ID/assignmen

Teste suas notificações

Você pode conferir se está recebendo notificações em sua integração, importando o este link em Postman. Caso sua URL funcione corretamente, você vai receber como resposta code 200 status ok, como mostrado na imagem abaixo.

Histórico das notificações

Verifique o histórico de notificações perdidas para esses tópicos, fazendo um GET para o seguinte endpoint:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=$APP_ID

Nota:

A resposta conterá informações sobre as notificações que após a oitava tentativa (1 hora), não tenham recebido o código http 200, ou seja, consideraremos a notificação perdida.

Se você estiver usando algum tipo de filtro em sua aplicação, a partir do Mercado Livre geraremos notificações com os seguintes endereços IP:

- 54.88.218.97
- 18.215.140.160
- 18.213.114.129
- 18.206.34.84

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=3486171129139063

Resposta:

{
   "messages": [
       {
           "_id": "5da8a1b24be30a49eb66c52a",
           "resource": "a35cf79864a845ca9a3bf6aee59bb4d7",
           "user_id": 465432224,
           "topic": "messages",
           "application_id": 3486171129139063,
           "attempts": 1,
           "sent": "2019-10-17T17:15:30.279Z",
           "received": "2019-10-17T17:15:30.259Z",
           "request": {
               "url": "https://YOUR_URL",
               "headers": {
                   "accept": "application/json",
                   "content-type": "application/json",
                   "content-length": 207
               },
               "data": "{\"resource\":\"a35cf79864a845ca9a3bf6aee59bb4d7\",\"user_id\":\"465432224\",\"topic\":\"messages\",\"application_id\":3486171129139063,\"attempts\":1,\"sent\":\"2019-10-17T17:15:30.279Z\",\"received\":\"2019-10-17T17:15:30.259Z\"}"
           },
           "response": {
               "req_time": 260,
               "http_code": 400,
               "body": "[object Object]",
               "headers": {
                   "date": "Thu, 17 Oct 2019 17:15:30 GMT",
                   "content-length": "141",
                   "content-type": "text/plain; charset=utf-8",
                   "connection": "close"
               }
           }
       },
       {
           "_id": "5da87eea5b35b865994cfd7d",
           "resource": "/items/MLA820048955",
           "user_id": 468424240,
           "topic": "items",
           "application_id": 3486171129139063,
           "attempts": 1,
           "sent": "2019-10-17T14:47:06.414Z",
           "received": "2019-10-17T14:47:06.375Z",
           "request": {
               "url": "https://YOUR_URL",
               "headers": {
                   "accept": "application/json",
                   "content-type": "application/json",
                   "content-length": 189
               },
               "data": "{\"resource\":\"/items/MLA820048955\",\"user_id\":468424240,\"topic\":\"items\",\"application_id\":3486171129139063,\"attempts\":1,\"sent\":\"2019-10-17T14:47:06.414Z\",\"received\":\"2019-10-17T14:47:06.375Z\"}"
           },
           "response": {
               "req_time": 498,
               "http_code": 200,
               "body": "[object Object]",
               "headers": {
                   "content-type": "application/json; charset=utf-8",
                   "date": "Thu, 17 Oct 2019 14:47:06 GMT",
                   "content-length": "190",
                   "connection": "close"
               }
           }
       }

}

Campos do recurso

resource: recurso completo, com o tópico pelo qual a notificação foi gerada.

user_id: usuário que o gerou.

topic: questão de referência da notificação.

request: consulta feita ao URL das notificações, juntamente com seus respectivos URL, header e dados.

response: resposta do servidor que está recebendo a notificação.

http_code: código HTTP retornado por esse servidor, para que ele não tente novamente, você deve enviar um 200.

Filtro tópico

Existe a possibilidade de filtrar por tópico, é muito útil quando você tem um grande número de notificações.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=$APP_ID&topic=$TOPIC

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=3486171129139063&topic=payments

Nota:

Por padrão, só serão mostradas 10 notificações, porém, você pode utilizar LIMIT e OFFSET para modificar o número que quer receber, como mostrado abaixo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=$APP_ID&offset=1&limit=5