Pessoas interessadas

O recurso /vis/users/$USER_ID/leads/buyers permite ao vendedor obter dados de contato dos compradores interessados em suas publicações. Para receber notificações sobre os clientes interessados, você deve se inscrever no tópico VIS Leads, e após receber a notificação, consultar o recurso de /leads.

Consultar interessados nos itens do vendedor

O vendedor pode consultar todos os dados de contato dos interessados em seus itens, com a possibilidade de paginá-los por meio do parâmetro offset, que indica a posição do primeiro elemento a ser recuperado, e do parâmetro limit, que indica a quantidade máxima de elementos a obter. Além disso, os dados podem ser filtrados por um período de tempo específico, utilizando os parâmetros date_from e date_to. Para realizar uma busca mais específica, pode-se utilizar o parâmetro contact_types, que representa o tipo de contato a ser retornado.

Adicionalmente, o vendedor pode consultar os leads gerados por usuários não logados utilizando o parâmetro opcional include_guest=true, que adiciona à resposta padrão dois novos nós estruturais: guest e summary.

Chamada:

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

Exemplo:

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 da consulta

Resposta de exemplo:

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

Descrição da resposta

Exemplo de chamada com o parâmetro opcional include_guest=true

O objetivo é permitir que o vendedor quantifique o volume total de interesse e cliques em suas publicações provenientes de usuários não registrados, facilitando para uma análise de métricas mais completa e 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

Resposta:

{
    "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 adicionais ao utilizar o parâmetro include_guest=true

Tipos de Leads Disponíveis (contact_types)

Importante:
Nem todos os tipos de contatos estarão disponíveis para todos os usuários. A disponibilidade de contatos pode variar de acordo com a vertical e o tipo de usuário.
• whatsapp: um comprador aperta o botão de WhatsApp.
• question: um comprador faz uma pergunta.
• call: um comprador aperta o botão de ligar.
• credit: simulação de crédito.
• contact_request: solicitações de contato geradas a partir do interesse em realizar uma reserva.
• visit_request: quando um comprador solicita uma visita.
• reservation: reserva de um item.

Resposta:

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

Erros possíveis

Erros na busca de interessados.

Error_code	Tipo	Mensagem de erro	Motivos
400	Bad Request	{ "message": "invalid date range", "error": "bad_request", "status": 400, "cause": [ "start date is greater than end date" ] }	A data de início é posterior à data de fim da pesquisa.
400	Bad Request	{ "message": "invalid start date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2021-01-021\": extra text: \"1\"" ] }	Data de início com formato inválido.
400	Bad Request	{ "message": "invalid end date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2024-01-022\": extra text: \"2\"" ] }	Data de fim com formato inválido.
Parâmetro do indicador de linha de crédito com formato inválido.
400	Bad Request	{ "code": "bad_request", "message": "invalid format USER_ID" }	Identificador com formato inválido.
400	Bad Request	{ "message": "error decoding search params", "error": "bad_request", "status": 400, "cause": [ "schema: invalid path \"contact_types\"" ] }	Parâmetro inválido.
400	Bad Request	{ "message": "invalid lead type", "error": "bad_request", "status": 400, "cause": [ "invalid lead type: invalid " ] }	Tipo de contato inválido.
403	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token não pertence ao vendedor.
403	Forbidden	{ "blocked_by": "PolicyAgent", "path": "/v1/users/806525693/leads/buyers?scope=test-public", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." }	Acesso ao endpoint sem access token.
403	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Access token inválido ou expirado.
429	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Foram efetuados muitos pedidos. Aguarde um momento antes de tentar novamente.




Obter detalhes de um lead

Quando o Mercado Livre notifica a criação de um novo lead relacionado com os interessados, o faz mencionando o ID na mensagem, para obter o detalhe você deve utilizar este identificador no recurso /vis/leads/$LEAD_ID. O qual proporcionará o detalhe correspondente.

Importante:
O endpoint /vis/leads/$LEAD_ID é válido apenas para a consulta de leads dos tipos whatsapp, call, question e visit_request.
Para os tipos de leads contact_request e reservation, a consulta deve ser realizada através do endpoint /leads/$LEAD_ID/details.

Chamada:

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

Exemplo:

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

Valores de entrada

Atributo	Tipo de dado	Descrição	Obrigatório	Valor padrão
leadID	string	Identificador do lead.	Sim	-




Resposta: 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 da resposta

• id: identificador do contato.
• contact_type: tipo de contato.
• item_id: identificador do item.
• created_at: data em que o lead foi criado.
• external_id: identificador externo do lead.
• status: status do lead.
• buyer_id: identificador do comprador.
• name: nome do comprador. Apenas se o acesso for público.
• email: e-mail do comprador. Apenas se o acesso for público.
• phone: telefone do comprador. Apenas se o acesso for público.



Obter detalhe de um lead para “contact_request” e “reservation”

Quando o Mercado Livre notifica a criação de um novo lead do tipo “contact_request” ou “reservation”, ele menciona o ID na mensagem. Para obter o detalhe, é necessário usar esse identificador no recurso /leads/$LEAD_ID/details, que fornecerá as informações correspondentes.




Chamada:

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

Exemplo:

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

Valores de entrada

Atributo	Tipo de dado	Descrição	Obrigatório	Valor padrão
leadID	string	Identificador do lead	Sim	-




Resposta: 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 - Nome - Local - Rua 111"
  }
}

Campos da resposta

• id: identificador do lead.
• contact_type: tipo de lead.
• item_id: identificador do item.
• created_at: data de criação do lead.
• status: status do lead.
• buyer_id: identificador do comprador.
• name: nome do comprador (somente se o acesso for público).
• email: e-mail do comprador (somente se o acesso for público).
• phone: telefone do comprador (somente se o acesso for público).
• identification_type: tipo de documento de identificação do usuário (somente se o acesso for público).
• identification_value: valor do documento com o qual o usuário se identifica (somente se o acesso for público).
• details: coleção de dados adicionais que servem para identificar o veículo selecionado e sua localização.
• color: cor do veículo selecionado pelo comprador.
• zip_code: código de localização de onde o veículo de interesse foi selecionado.
• dealership: concessionária de preferência do comprador.



Erros possíveis

Erros na pesquisa do detalhe do lead.

Error_code	Tipo	Mensagem de erro	Motivos
400	Bad Request	{ "code": "bad_request", "message": "missing lead_id" }	Identificador incorreto ou inexistente.
400	Bad Request	{ "code": "bad_request", "message": "invalid callerID" }	O caller ID não está presente ou não está correto.
400	Bad Request	{ "code": "bad_request", "message": "invalid clientID" }	O client ID proporcionado não está presente ou não está correto.
403	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token não pertence ao vendedor.
403	Forbidden	{ "blocked_by": "PolicyAgent", "path": "/vis/leads/142536", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." }	Acesso ao endpoint sem Access token.
403	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Access token inválido ou expirado.
404	Not Found	{ "code": "not_found", "message": "lead not found" }	O identificador proporcionado não está associado a nenhum lead do usuário.
429	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Muitos pedidos realizados. Por favor, aguarde um momento antes de tentar novamente.