Personas Interesadas

El recurso /vis/users/$USER_ID/leads/buyers permite al vendedor obtener datos de contacto de los compradores interesados en sus publicaciones. Para recibir notificaciones sobre los clientes interesados, debes suscribirte al tópico VIS Leads, y después de recibir la notificación consultar el recurso de /leads.

Consultar interesados en los ítems del vendedor

El vendedor puede consultar todos los datos de contacto de los interesados en sus ítems, con la posibilidad de paginarlos mediante el parámetro offset, que indica la posición del primer elemento a recuperar, y el parámetro limit, que señala la cantidad máxima de elementos a obtener. Además, los datos pueden ser filtrados por un período de tiempo específico, usando los parámetros date_from y date_to. Para realizar una búsqueda más específica, se puede utilizar el parámetro contact_types, que representa el tipo de contacto a retornar.

Adicionalmente, el vendedor puede consultar los leads generados por usuarios no logueados utilizando el parámetro opcional include_guest=true, que agrega a la respuesta estándar dos nuevos nodos estructurales: guest y summary.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?offset=$OFFSET&limit=$LIMIT&date_from=$DATE_FROM&date_to=$DATE_TO&contact_types=$CONTACT_TYPES

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/3052668868/leads/buyers?offset=0&limit=10&date_from=2026-01-15&date_to=2026-01-22&contac_types=credit,question,whatsapp

Parámetros de la consulta

Respuesta de ejemplo:

{
    "results": [
        {
            "id": 2522572034,
            "item_id": "MLC3404674016",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "uuid": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "channel": "whatsapp",
                    "contact_type": "whatsapp",
                    "created_at": "2026-01-22T21:01:47Z",
                    "external_id": "",
                    "item_id": "MLC3404674016",
                    "status": "active"
                }
            ]
        },
        {
            "id": 2522572034,
            "item_id": "MLC3404028058",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "uuid": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "channel": "question",
                    "contact_type": "question",
                    "created_at": "2026-01-22T20:44:05.3Z",
                    "external_id": "13510887742",
                    "item_id": "MLC3404028058",
                    "status": "active"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 2
    },
    "date_from": "2026-01-15",
    "date_to": "2026-01-22"
}

Descripción de la respuesta

Ejemplo de llamada con el parámetro opcional include_guest=true

El objetivo es permitir que el vendedor cuantifique el volumen total de interés y clics en sus publicaciones provenientes de usuarios no registrados, facilitando para un análisis de métricas más completo y real.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/3052668868/leads/buyers?offset=0&limit=10&date_from=2026-01-15&date_to=2026-01-22&contact_types=credit,question,whatsapp&include_guest=true

Respuesta:

{
    "results": [
        {
            "id": 2522572034,
            "item_id": "MLC3404674016",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "uuid": "b711e264-ec67-480e-90b2-444d8f47d5ed",
                    "channel": "whatsapp",
                    "contact_type": "whatsapp",
                    "created_at": "2026-01-22T21:01:47Z",
                    "external_id": "",
                    "item_id": "MLC3404674016",
                    "status": "active"
                }
            ]
        },
        {
            "id": 2522572034,
            "item_id": "MLC3404028058",
            "name": "Test Test",
            "email": "test_user_2030409702@testuser.com",
            "phone": "+56 01 1111-1111",
            "identification_number": "67602099-3",
            "identification_type": "RUT",
            "leads": [
                {
                    "id": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "uuid": "5a6732a1-6051-4281-a470-d81cb43acecb",
                    "channel": "question",
                    "contact_type": "question",
                    "created_at": "2026-01-22T20:44:05.3Z",
                    "external_id": "13510887742",
                    "item_id": "MLC3404028058",
                    "status": "active"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 2
    },
    "date_from": "2026-01-15",
    "date_to": "2026-01-22",
    "guest": [
        {
            "item_id": "MLC3404674016",
            "leads": [
                {
                    "id": "56c71b07-f347-41e2-8f63-4f81dda74491",
                    "contact_type": "whatsapp",
                    "status": "active",
                    "created_at": "2026-01-22T20:30:52Z"
                }
            ]
        }
    ],
    "summary": [
        {
            "item_id": "MLC3404674016",
            "total": 2,
            "user": 1,
            "guest": 1
        },
        {
            "item_id": "MLC3404028058",
            "total": 1,
            "user": 1,
            "guest": 0
        }
    ]
}

Campos adicionales al utilizar el parámetro include_guest=true

Tipos de Leads Disponibles (contact_types)

• whatsapp: un comprador apreta el botón de WhatsApp.
• question: un comprador hace una pregunta.
• call: un comprador apreta el botón de llamar.
• credit: simulación de crédito.
• contact_request: solicitudes de contacto dado el interés para generar una reserva.
• visit request: cuando un comprador solicita una solicitud de visita.
• reservation: reserva de un ítem.

Respuesta:

{
    "results": [
        {
            "id": 2678328,
            "item_id": "MLA1430828018",
            "name": "John Doe",
            "email": "jhon@example.com",
            "phone": "+5491198765432",
            "leads": [
                {
                    "id": "6b4aebf8-5570-47b8-9224-c1c177621575",
                    "contact_type": "question",
                    "created_at": "2024-05-14T14:15:39Z",
                    "external_id": "12776297658",
                    "item_id": "MLA1430828018",
                    "buyer_id": 2678328,
                    "status": "active"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 1
    },
    "date_from": "2024-05-14",
    "date_to": "2024-05-24"
}

Posibles errores

Errores en la búsqueda de interesados.

Obtener detalle de un lead

Cuando Mercado Libre notifica de la creación de un nuevo lead relacionado a los interesados, lo hace mencionando el ID en el mensaje, para obtener el detalle debes usar dicho identificador en el recurso /vis/leads/$LEAD_ID. El cual te proporcionará el detalle correspondiente.

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/3f2dedf2-dfbd-4981-a726-40b13aa172ff

Valores de entrada

Respuesta: HTTP 200

{
    "id": "44115522",
    "item_id": "MLB4037459422",
    "created_at": "2024-02-14T00:00:00Z",
    "contact_type": "whatsapp",
    "external_id": "13864821",
    "status": "active",
    "buyer_id": 1091441589,
    "name": "Test Test",
    "email": "john@example.com",
    "phone": "+55 01 1111-1111"
}

Campos de la respuesta

• id: identificador del lead.
• contact_type: tipo de lead.
• item_id: identificador del ítem.
• created_at: fecha de creación del lead.
• external_id: identificador externo del lead.
• status: estado del lead.
• buyer_id: identificador del comprador.
• name: nombre del comprador. Solo si el acceso es público.
• email: email del comprador. Solo si el acceso es público.
• phone: teléfono del comprador. Solo si el acceso es público.

Obtener detalle de un lead para “contact_request” y “reservation”

Cuando Mercado Libre notifica la creación de un nuevo lead de tipo “contact_request” o “reservation”, lo hace mencionando el ID en el mensaje. Para obtener el detalle, debes usar dicho identificador en el recurso /leads/$LEAD_ID/details, el cual te proporcionará la información correspondiente.

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/leads/3f2dedf2-dfbd-4981-a726-40b13aa172ff/details

Valores de entrada

Respuesta: HTTP 200

{
  "id": "a2039207-9185-453b-a02f-aac9fc9ffacb",
  "item_id": "MLB4037459422",
  "created_at": "2025-02-14T00:00:00Z",
  "contact_type": "contact_request",
  "status": "created",
  "buyer_id": 1091441589,
  "name": "Test Test",
  "email": "john@example.com",
  "phone": "+55 01 1111-1111",
  "identification_type": "CPF",
  "identification_number": "01011010110",
  "details": {
    "color": "Azul Moonlight Perolizado",
    "zip_code": "88000-000",
    "dealership": "COD001 - Nombre - Lugar - Calle 111"
  }
}

Campos de la respuesta

• id: identificador del lead.
• contact_type: tipo de lead.
• item_id: identificador del ítem.
• created_at: fecha de creación del lead.
• status: estado del lead.
• buyer_id: identificador del comprador.
• name: nombre del comprador (solo si el acceso es público).
• email: email del comprador (solo si el acceso es público).
• phone: teléfono del comprador (solo si el acceso es público).
• identification_type: tipo de documento de identificación del usuario (solo si el acceso es público).
• identification_value: valor del documento con el que se identifica al usuario (solo si el acceso es público).
• details: colección de datos adicionales que sirven para identificar el vehículo seleccionado y su ubicación.
• color: color del vehículo seleccionado por el comprador.
• zip_code: código de ubicación desde donde fue seleccionado el vehículo de interés.
• dealership: concesionaria de preferencia del comprador.

Posibles errores

Errores en la búsqueda del detalle de un lead.