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 14/02/2025

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.

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.


Configuração de notificações

URL de Retorno de Chamada (Callback URL):

Especifique a URL pública onde o sistema enviará as notificações via HTTP POST. Essa URL deve estar acessível e configurada para receber dados dos tópicos selecionados. Exemplo: http://myapp.com/notifications.



Tópicos:

Escolha os tópicos de interesse para receber notificações específicas. Cada tópico corresponde a um tipo de evento no sistema, e ao configurá-los, as notificações enviadas serão restritas aos eventos desses tópicos.



Nota:
Os tópicos 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.

Tópicos

Atualmente, temos duas abordagens para a organização dos tópicos de notificações na plataforma:

Modelo de Tópico Geral: Neste modelo, o tópico agrupa e envia todas as notificações de uma entidade, de forma mais ampla e unificada, sem a visualização ou segmentação de sub-tópicos. Ou seja, não há uma estrutura visível de filtros aplicados a essa entidade/tópico, e todas as notificações são entregues de maneira centralizada em uma única entidade principal correspondente a uma funcionalidade.

Modelo com Subtópicos (tipificado): Ao contrário do modelo anterior e com a evolução de nossa estrutura, permitiremos neste novo modelo a visualização e organização das notificações em subtópicos (ou filtros). Assim, é possível segmentar as novidades conforme as ações/atributos/filtros específicos que se apliquem, proporcionando maior eficiência, autonomia e controle sobre quais notificações o usuário deseja receber.

Nota:
Estamos migrando gradualmente a estrutura de tópicos das notificações. Hoje, já contamos com alguns tópicos organizados com subtópicos (filtros), o que proporciona maior organização e controle sobre os filtros e os tipos de notificação. A partir de agora, continuaremos expandindo essa estrutura, permitindo uma segmentação e impactando no uso ainda mais eficiente das notificações. .

Estrutura Modelo com Subtópicos:

Entidade principal: Esta é a entidade principal que engloba todos os subtipos de notificações de um recurso.

Subtópicos (Filtros): Dentro do Entidade principal, você poderá configurar filtros específicos para segmentar as notificações. Cada filtro corresponde a uma categoria de notificação.


Fluxo de filtros/subtópicos


Cada subtópico pode ter notificações associadas a eventos e ações específicas. Essas novidades são disparadas conforme as atividades que ocorrem dentro do Mercado Livre, permitindo que o integrador acompanhe as mudanças relevantes.

O nível de especificidade das notificações pode ser ajustado conforme o filtro disponibilizado. Isso oferece ao integrador a possibilidade de selecionar diretamente os eventos dentro de um tópico/entidade, podendo optar por eventos mais específicos de seu interesse, conforme a necessidade de controle e acompanhamento em sua integração.


Topicos disponíveis

Orders:

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

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


Messages:

messages: você receberá notificações das novas mensagens que forem geradas, tendo como destinatário o user_id correspondente (Comprador ou Vendedor).

Insurance Messages: Mensagens de segurança.


Prices:

Price Suggestion: você receberá notificações sobre as sugestões de preços no Mercado Livre.


Items:

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.

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).

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

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

User Products Families: você receberá notificações quando forem modificadas as famílias do user_product, por mudança de atributos que impactem nisso.


Catalog:

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. "Este tópico está disponível na Argentina, Brasil e México"

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


Shipments:

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

FBM Stock Operations: notificações relacionadas a operações de estoque do modelo FBM.

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).


Promotions:

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

public Candidates: você receberá as notificações quando um item estiver candidato a uma promoção.


VIS Leads:

Estrutura Modelo com Subtópicos

Vis Leads: Ao clicar, será notificado de todos os subtópicos.

Whatsaapp: Notifica quando um comprador aperta o botão de WhatsApp.

Call: Notifica quando um comprador aperta o botão de ligar.

Question: Notifica quando um comprador faz uma pergunta.

visit_request: Notifica quando há uma solicitação de agendamento de uma visita em uma propriedade.

Nota:
Tenha em conta que as notificações de Questions podem ser geradas por dois fluxos: o tópico Items e o VIS_Leads - question. Quando ambos os tópicos estão selecionados, haverá duplicidade nos leads, pois as notificações serão enviadas por ambos os tópicos. Para integrações de VIS, ative apenas o tópico VIS_Leads para evitar esse problema. .

Post Purchase:

Estrutura Modelo com Subtópicos

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

claims_actions: você receberá notificações quando uma ação é executada no claim.

Importante:
O campo resource das notificações agora incluirá o prefixo /post-purchase no path, que antes não era enviado. Essa mudança pode afetar sua integração caso não seja ajustada para reconhecer o novo formato. Atualize sua implementação para garantir a compatibilidade.

Others:

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

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).

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


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.

Como consultar as notificações

Quando você receber uma notificação sobre um tópico, será necessário realizar uma solicitação GET ao recurso indicado para obter os detalhes completos. Se você tiver salvo uma versão anterior do JSON, é importante compará-la com a nova resposta para identificar mudanças.


Estrutura de Notificação tópico geral:

As notificações têm uma estrutura uniforme, o que facilita o acesso e a análise dos dados:


{
   "_id": "id_unico",
   "resource": "/caminho_do_recurso",
   "user_id": "id_do_usuario",
   "topic": "topico",
   "application_id": "id_da_aplicacao",
   "attempts": numero_tentativas,
   "sent": "timestamp_envio",
   "received": "timestamp_recebimento"
}

Como Acessar o Recurso:

  1. Identifique o resource: O campo resource na notificação indica a URL para a qual você deve fazer a solicitação GET.
  2. Determine o topic: O campo topic indica o tipo de recurso (por exemplo, items, orders, claims).
  3. Faça a Solicitação GET: Com base no resource, envie uma solicitação GET para acessar os detalhes completos do recurso.

Exemplo de Resposta de Notificação: Tópico geral:


{
   "_id": "f9f08571-1f65-4c46-9e0a-c0f43faa1557e",
   "resource": "/items/MLA686791111",
   "user_id": 123456789,
   "topic": "items",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2025-01-21T13:44:33.006Z",
   "received": "2025-01-21T13:44:32.984Z"
}

Com base no resource fornecido, você precisa fazer uma solicitação GET para obter detalhes do recurso. Aqui está como isso seria feito:

Chamada:

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

Resposta:

{
   "id": "MLA686791111",
   "title": "Produto Exemplo",
   "price": 100.0,
   "currency_id": "BRL",
   "available_quantity": 10,
   "sold_quantity": 2,
   "status": "active"
}

Exemplo de Resposta de Notificação: Estrutura Modelo com Subtópicos


{
  "id": "aaa123bbbbb",
  "resource": "/api/vis_leads/93a14ee6-0356-4e20-b0c6-f4ad8f80bfff",
  "user_id": 123456789,
  "topic": "vis_leads",
  "actions": ["visit_request"],
"application_id": 1111111111111111111,
  "attempts": 1,
  "sent": "2017-10-09T13:44:33.006Z",
  "received": "2017-10-09T13:44:32.984Z"
}

Nota:
Nesta estrutura, vemos o detalhe do filtro ou tipo da novidade no array de “actions”, demonstrando a que se refere essa notificação dentro de uma entidade/recurso. .

Com base na resource fornecida, você precisa fazer uma solicitação GET para obter detalhes do recurso:

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/vis/users/$USER_ID/leads'
Nota:
Com esses detalhes, você pode atualizar ou processar as informações conforme necessário em sua aplicação. .

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