Notificaciones

Configuración de notificaciones

URL de Retorno de Llamada (Callback URL):

Topicos:

Topicos

Actualmente, tenemos dos enfoques para la organización de los temas de notificaciones en la plataforma:

Modelo de Tema General: En este modelo, el tema agrupa y envía todas las notificaciones de una entidad, de forma más amplia y unificada, sin la visualización o segmentación de sub-temas. Es decir, no hay una estructura visible de filtros aplicados a esa entidad/tema, y todas las notificaciones se entregan de manera centralizada en una única entidad principal correspondiente a una funcionalidad.

Modelo con Subtemas (tipificado): A diferencia del modelo anterior y con la evolución de nuestra estructura, permitiremos en este nuevo modelo la visualización y organización de las notificaciones en subtemas (o filtros). Así, es posible segmentar las novedades conforme las acciones/atributos/filtros específicos que se apliquen, proporcionando mayor eficiencia, autonomía y control sobre qué notificaciones el usuario desea recibir.

Estructura Modelo con Subtópicos:

Entidad principal: Esta es la entidad principal que engloba todos los subtipos de notificaciones de un recurso.

Subtópicos (Filtros): Dentro de la Entidad principal, podrás configurar filtros específicos para segmentar las notificaciones. Cada filtro corresponde a una categoría de notificación.

Flujo de filtros/subtópicos

Cada subtópico puede tener notificaciones asociadas a eventos y acciones específicas. Estas novedades se disparan conforme las actividades que ocurren dentro de Mercado Libre, permitiendo que el integrador siga los cambios relevantes.

El nivel de especificidad de las notificaciones puede ajustarse según el filtro disponible. Esto ofrece al integrador la posibilidad de seleccionar directamente los eventos dentro de un tópico/entidad, pudiendo optar por eventos más específicos de su interés, según la necesidad de control y seguimiento en su integración.

Tópicos disponibles

Orders:

orders_v2: recibirás notificaciones a partir de la creación y modificaciones realizadas en alguna de tus ventas confirmadas. (recomendado)

feedback de pedidos: recibirás notificaciones sobre la creación y modificaciones hechas en los comentarios de tus ventas confirmadas.

Mensajes:

messages: recibirás notificaciones de los nuevos mensajes generados, teniendo como destinatario el user_id correspondiente (Comprador o Vendedor).

Mensajes de seguridad: Mensajes de seguridad.

Prices:

Sugerencia de precios: recibirás notificaciones sobre las sugerencias de precios en Mercado Libre.

Items:

Items: recibirás notificaciones sobre cualquier cambio en un artículo que hayas publicado.

Preguntas: recibirás notificaciones de preguntas y respuestas realizadas.

Cotizaciones: recibirás notificaciones sobre cotizaciones que ocurran en las publicaciones (aplicable solo para la integración de bienes raíces de Mercado Libre Chile).

Precios de artículos: recibirás notificaciones del item_id cada vez que el precio sea creado, actualizado o eliminado.

Ubicación de stock: recibirás notificaciones cuando las ubicaciones de stock del user_product sean modificadas, aumentando o disminuyendo el campo de cantidad.

Familias de productos del usuario: recibirás notificaciones cuando se modifiquen las familias de los productos del usuario, debido a un cambio en los atributos que impacten en ello.

Catalog:

Competencia de artículos: recibirás notificaciones cuando las publicaciones de catálogo competidoras cambien de estado. Tanto del competidor al ganador y viceversa. "Este tópico está disponible en Argentina, Brasil y México"

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

Shipments:

shipments: recibirás notificaciones a partir de la creación y modificaciones realizadas en los envíos (shippings) de tus ventas confirmadas.

Operaciones de stock FBM: notificaciones relacionadas a operaciones de stock del modelo FBM.

flex-handshakes: recibirás notificaciones cuando haya transferencias de paquetes entre transportistas y cuando se escaneen por primera vez (cuando se marque como enviado).

Promotions:

Public offers: recibirás notificaciones cuando se cree o modifique el estado de una oferta en un artículo.

Public Candidates:: recibirás notificaciones cuando un artículo sea candidato a una promoción.

VIS Leads:

Estructura Modelo con Subtópicos

Leads VIS: Al hacer clic, recibirás notificaciones de todos los subtópicos.

WhatsApp: Notifica cuando un comprador presiona el botón de WhatsApp.

Call: Notifica cuando un comprador presiona el botón de llamada.

Question: Notifica cuando un comprador hace una pregunta.

visit_request: Notifica cuando haya una solicitud para agendar una visita en una propiedad.

Post Purchase:

Estructura Modelo con Subtópicos

Claims: Recibirás notificaciones sobre las reclamaciones que se realicen respecto a las ventas. Ver más sobre cómo trabajar con reclamaciones.

claims_actions: Recibirás notificaciones cuando se ejecute una acción sobre la reclamación.

Others:

payments: recibirás notificaciones cuando se cree un pago en una orden o cuando su estado cambie.

invoices: recibirás notificaciones sobre las facturas generadas (facturas fiscales) a través de la facturación automática realizada por Mercado Libre (aplicable solo a quienes trabajan con la Facturación de Mercado Envíos Full).

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

¿Qué eventos disparan notificaciones?

Ten en cuenta que cualquier cambio que ocurra en el JSON, en cualquier tema, disparará las notificaciones correspondientes a estos.
Es importante que siempre escuches las notificaciones y, luego, hagas la consulta en el recurso correspondiente para verificar si hay algún cambio respecto a tu aplicación, ya que los cambios también pueden provenir de otras fuentes, como acciones a través del front-end, Seller Central u otras aplicaciones, etc.

Consideraciones Importantes

• Enviaremos un POST a la URL de callback y tu aplicación deberá confirmar con un HTTP 200 la recepción correcta. De lo contrario, el mensaje se considerará no entregado y se intentará enviar nuevamente.
• Los mensajes serán enviados y nuevos intentos de envío se harán durante un intervalo de 1 hora. Después de este período, si no son aceptados por la aplicación, serán eliminados.
• Dado que puede haber una gran cantidad de notificaciones, se recomienda trabajar con colas, donde tu servidor debe confirmar la recepción de las notificaciones (HTTP 200) instantáneamente y solo después realizar la consulta del tema en la API; de esta forma evitarás nuevos intentos de notificación y no generará la sensación de notificaciones duplicadas.
• Ten en cuenta que existen eventos internos no visibles para el integrador, pero estos disparan notificaciones.

Cómo consultar las notificaciones

Cuando recibas una notificación sobre un tema, necesitarás realizar una solicitud GET al recurso indicado para obtener los detalles completos. Si has guardado una versión anterior del JSON, es importante compararla con la nueva respuesta para identificar cambios.

Estructura de Notificación tema general:

Las notificaciones tienen una estructura uniforme, lo que facilita el acceso y el análisis de los datos:

{
   "_id": "id_unico",
   "resource": "/camino_del_recurso",
   "user_id": "id_del_usuario",
   "topic": "tema",
   "application_id": "id_de_la_aplicación",
   "attempts": numero_intentos,
   "sent": "timestamp_envio",
   "received": "timestamp_recepcion"
}

Cómo Acceder al Recurso:

1. Identifica el resource: El campo resource en la notificación indica la URL a la que debes hacer la solicitud GET.
2. Determina el topic: El campo topic indica el tipo de recurso (por ejemplo, items, orders, claims).
3. Realiza la Solicitud GET: Basado en el resource, envía una solicitud GET para acceder a los detalles completos del recurso.

Ejemplo de Respuesta de Notificación: Tema general:

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

Basado en el resource proporcionado, necesitas hacer una solicitud GET para obtener los detalles del recurso. Aquí está cómo se haría:

Llamada:

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

Respuesta:

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

Ejemplo de Respuesta de Notificación: Estructura Modelo con Subtemas

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

Basado en el resource proporcionado, necesitas hacer una solicitud GET para obtener los detalles del recurso:

Llamada:

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

Prueba tus notificaciones

Puedes verificar si estás recibiendo notificaciones en tu integración, importando este enlace en Postman. Si tu URL funciona correctamente, recibirás una respuesta con el código 200 status ok, como se muestra en la imagen a continuación.

Historial de notificaciones

Verifica el historial de notificaciones perdidas para esos temas, haciendo un GET al siguiente endpoint:

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

Si estás utilizando algún tipo de filtro en tu aplicación, desde Mercado Libre generaremos 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 el tema por el cual se generó la notificación.

user_id: usuario que lo generó.

topic: tema de referencia de la notificación.

request: consulta realizada a la URL de las notificaciones, junto con sus respectivas URL, encabezado y datos.

response: respuesta del servidor que está recibiendo la notificación.

http_code: código HTTP devuelto por este servidor. Para que no intente nuevamente, debes enviar un 200.

Filtro por tema

Existe la posibilidad de filtrar por tema, lo cual es muy útil cuando tienes un gran número 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

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