Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 28/08/2024

Recibe notificaciones

Algunos eventos se producen del lado de Mercado Libre y la única forma de conocerlos es a través de notificaciones. Recibir notificaciones te permite tener un feed en tiempo real de los cambios que se producen en los diferentes recursos de nuestra la API. Por ejemplo, si publicaste un artículo y más tarde fue pausado, si alguien formuló una pregunta, si compraron un artículo o incluso lo pagaron y/o solicitó envío. ¡Una manera eficiente sin tener que consultar permanentemente nuestra API!


Suscríbete a las notificaciones

Para comenzar a recibir notificaciones, debes realizar el login e ingresar a Mis aplicaciones, donde creaste tu aplicación por primera vez, editas detalles y especificas los topics que recibirás. Si aún no has creado tu aplicación, puedes hacerlo ahora.



Callback URL de notificaciones: configura el URL público del dominio donde quieres recibir notificaciones para los diferentes topics. Por ejemplo: “http://myshoes-app.com/callbacks”.

Topics: selecciona entre diferentes topics para recibir sus notificaciones.

Nota:
- Los topics payments y messaging no son utilizados para vehículos, inmuebles y servicios.
- Las notificaciones tienen la zona horária UTC.


Topics disponibles

items: recibirás notificaciones de cualquier cambio en un artículo que publicaste.

questions: recibirás notificaciones de todas las preguntas formuladas o respondidas.

payments: recibirás notificaciones cuando se crea un pago en una orden o el estado del mismo cambia.

messages: recibirás notificaciones de los mensajes nuevos que se generen teniendo como destinatario su user_id.

orders_v2: recibirás notificaciones desde la creación y cambios realizados en alguna de tus ventas confirmadas (recomendable).

shipments: recibirás notificaciones desde la creación y cambios realizados en los envíos (shippings) de tus ventas confirmadas.

orders feedback: recibirás notificaciones desde la creación y cambios realizados en feedbacks de tus ventas confirmadas.

quotations: recibirás notificaciones referidas a cotizaciones que sucedan en las publicaciones (aplica solo para integración de inmuebles en Mercado Libre Chile).

invoices: recibirás notificaciones relacionadas a invoices (notas fiscales) generadas mediante la facturación automática der Mercado Libre (aplica solamente a quien trabaja con el facturador de Mercado Envio Full *Solo disponible en Brasil).

claims: recibirás notificaciones relacionadas a reclamos que sean hechos por las ventas (trabajar con reclamos)

item competition: recibirás notificaciones cuando las publicaciones de catálogo que se encuentran compitiendo cambian de estado. Tanto de competidor a ganador y viceversa.

Nota:
Deberás usar el recurso de /price_to_win para revisar la condición del ítem y tomar las acciones necesarias para ganar la página de producto.

catalog_suggestions: recibirás notificaciones sobre los cambios de estado de las sugerencias de productos para nuestro catálogo - Brand Central.

VIS Leads: recibirás notificaciones sobre datos de contacto de los compradores interesados en sus publicaciones.

leads credits: recibirás notificaciones relacionadas a créditos aprobados o rechazados en Mercado Libre (se aplica para vehículos, e inmuebles).

stock fulfillment: recibirás notificaciones con el detalle de una operación en particular ejecutada sobre el stock que el seller tiene almacenado en los depósitos de FBM.

items_prices: recibirás notificaciones del item_id cada vez que el precio se crea, se actualiza o se borra.

public candidates: recibirás notificaciones cada vez que un ítem sea invitado a participar en una promoción.

public offers: recibirás notificaciones cuando se crea o cambia de estado una oferta en un ítem.

flex-handshakes: recibirás notificaciones cuando se realicen transferencias de paquetes entre transportistas y cuando lo escanee por primera vez (cuando se marca shipped).

stock_locations: recibirás notificaciones cuando se modifican las stock_locations del user_product, ya sea por incremento o decremento el campo quantity.

user products families: recibirás notificaciones cuando se modifican las familias del user_product, por modificación de atributos que impactan en eso.


¿Qué eventos disparan notificaciones?

Ten en cuenta que cualquier cambio que haya en el Json, en cualquier topic, serán enviadas las notificaciones correspondientes.

Es importante que siempre veas las notificaciones y, en seguida, hagas la consulta en el recurso correspondiente para verificar si hay algún cambio con su aplicación. Estos cambios pueden surgir desde otras fuentes, como la acción via front, Seller Central u otras aplicaciones, etc.


Consideraciones Importantes

Importante:
Actualiza tu integración para devolver un HTTP 200 antes de 500 milisegundos de recibida la notificación y evitar que desactivemos los tópicos de tus notificaciones. Caso contrario, deberás suscribirte nuevamente a los tópicos.
  • Enviaremos un POST a la callback URL y tu aplicación deberá confirmar mediante un HTTP 200 la recepción correcta. Caso contrario, el mensaje será considerado como “no recibido” y habrá una nueva tentativa de envío.
  • Los mensajes serán enviados y las tentativas de envío serán hechas en un intervalo de 1 hora. Después de este período, los mensajes que no fueron aceptados serán excluídos.
  • Teniendo en cuenta que puede haber una gran cantidad de notificaciones, es recomendable que trabajes con filas, donde el servidor deberá confirmar la recepción de las notificaciones (HTTP 200) instantáneamente y hacer la consulta del topic en el API, para evitar nuevas tentativas de notificaciones y evitar generar la sensación de notificaciones duplicadas.
  • Ten en cuenta que hay eventos no visibles para integradores que disparan notificaciones.


Accede a los detalles

Después de recibir una notificación sobre un tema, deberás realizar una solicitud GET al recurso para acceder a los detalles y luego, si guardaste el JSON anterior, comparar ambos.


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"
}

Con esta información podrás realizar un GET al siguiente recurso de ítems:

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

orders_v2

Notification response:

{
 "_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"
}

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

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

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"
}

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

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

messages

Notification response:

{
 "_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"
 }

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

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

quotations

Notification response:

{
 "_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:
Las notificaciones referidas a cotizaciones solo están disponibles para Mercado Libre Chile.

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

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

Donde caller.type es para identificar quién es el generador de la acción. Puede ser un vendedor o un usuario. Generalmente, para las aplicaciones de lanzamientos será el del 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"
}

Con esta información podrás realizar un GET al recurso de /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"
}

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

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

item competition

Notificación:

{
 "_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"
}

Con esta información podrás realizar un GET al recurso de /price_to_win.

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

catalog suggestions

Notificación:

{
 "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e", 
  "topic": "catalog_suggestions",
  "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"
}

Con esta información, podrás realizar un GET al recurso de /catalog_suggestions:

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

VIS Leads

Nota:
Ten en cuenta que las notificaciones de Questions pueden ser generadas por dos flujos: el tópico Items y el VIS_Leads - question. Cuando ambos tópicos están seleccionados, habrá duplicidad en los leads, ya que las notificaciones se enviarán por ambos tópicos. Para integraciones de VIS, activa solo el tópico VIS_Leads para evitar este problema. .

Notificación:

{
 "_id":"f9f08571-1f65-4c46-9e0a-c0f43faas1557e",
   "resource": "/vis/leads/14b52fd8-85dc-11eb-8436-2753cb1f9665",
   "user_id": 123456789,
   "topic": "vis_leads",
   "application_id": 2069392825111111,
   "attempts": 1,
   "sent": "2024-05-09T13:44:33.006Z",
   "received": "2024-05-09T13:44:32.984Z"
}

Con esta información, podrás realizar un GET al recurso de /vis/leads: 

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

Leads credits

Notificación:

{
  "_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"
}

Con esta información, podrás realizar un GET al recurso de /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á disponible en Argentina, Brasil, México, Chile y Colombia donde hay fulfillment.

Notificación:

{
 "_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"
}

Con esta información podrás realizar un GET al recurso de /stock/fulfillment/operations:

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

items_prices

Notificación:

{
   "_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"
}

Con esta información podrás realizar un GET al recurso /prices:

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

public candidates

Notificación:

{
  "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"
}

Con esta información puede realizar un GET en el recurso /seller-promotions/candidates: 

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

public offers

Notificación:

{
  "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"
}

Con esta información podrás realizar un GET al recurso /seller-promotions/offers:

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

flex transportistas

Notificación:

{
"_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"
}

Llamada:

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

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

stock_locations

Notificación:

{
"_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"
}

Llamada:

Con esta información podrás realizar un GET al recurso de User product ID.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock

user products families

Notificación:

{
"_id": "2e4f6253-ebcc-421d-9d0b-97f80290ac5d",
"topic": "user-products-families",
"resource": "/sites/$SITE_ID/user-products-families/$FAMILY_ID",
"user_id": 123456789,
"application_id": 213123389095511,
"sent": "2024-07-11T18:43:50.793Z",
"attempts": 1,
"received": "2024-07-11T18:43:50.699Z"
}

Llamada:

Con esta información podrás realizar un GET al recurso de consultar los user products de una familia.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/user-products-families/$FAMILY_ID


Prueba tus notificaciones

Puedes validar si estás recibiendo notificaciones en tu integración importando este link en Postman. Si tu URL funciona correctamente recibirás como respuesta code 200 status ok, como se muestra en la siguiente imagen.

Histórico de notificaciones

Consulta el historial de notificaciones perdidas de estos tópicos realizando un GET al siguiente endpoint:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=$APP_ID
Nota:
La respuesta contendrá información de las notificaciones que luego del quinto reintento (1 hora), no haya recibido un http code 200, es decir, que consideraremos la notificación como perdida.

Si estás utilizando algún tipo de filtro en tu aplicación, desde Mercado Libre generaremos las notificaciones con las siguientes direcciones IP:

- 54.88.218.97
- 18.215.140.160
- 18.213.114.129
- 18.206.34.84


Ejemplo:

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

Respuesta:

{
   "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 del recurso

resource: recurso completo, con tópico por el cual se generó la notificación.

user_id: usuario que la generó.

topic: tema referente de la notificación.

request: consulta realizada a la URL de notificaciones, junto con su respectivo url, header y data.

response: respuesta de parte del servidor que recibe la notificación.

http_code: código HTTP que devuelve dicho servidor, para que no se reintente tiene que enviar un 200.


Filtro por tópico

Existe la posibilidad de filtrar por tópico, es muy útil para cuando se tienen una gran cantidad de notificaciones.

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=3486171129139063&topic=payments
Nota:
Por defecto sólo se mostrarán 10 notificaciones pero, puedes utilizar LIMIT y OFFSET para modificar la cantidad que quieres recibir tal como se muestra a continuación:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/missed_feeds?app_id=$APP_ID&offset=1&limit=5