Pessoas interessadas

O recurso /vis/users/$USER_ID/leads/seller 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

Agora, o vendedor pode consultar todos os dados de contato dos interessados, com a possibilidade de fazer paginação utilizando o parâmetro offset, que indica a posição do primeiro elemento a ser obtido, e o parâmetro limit, que indica o número máximo de elementos a obter. Além disso, os dados podem ser filtrados por um período específico, utilizando os parâmetros date_from e date_to. Para uma pesquisa mais específica, pode utilizar o parâmetro contac_types, que representa o tipo de contato a devolver.

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/806525693/leads/buyers?offset=0&limit=10&dateFrom=2023-06-15&dateTo=2023-06-22&contact_types=true&contac_types=credit,question,whatsapp

Valores de entrada

Campos de la respuesta

• results: contém uma lista de resultados.
• results.id: identificador do comprador.
• results.item_id: identificador do item.
• results.name: nome do comprador. Apenas se o acesso for público.
• results.email: e-mail do comprador. Apenas se o acesso for público.
• results.phone: número de telefone do comprador. Apenas se o acesso for público.
• results.identification_number: número de identificação do comprador. Apenas se o acesso for público.
• results.identification_type: tipo de identificação do comprador. Apenas se o acesso for público.
• results.leads: contém uma lista do leads gerados pelo comprador.
• leads.id: identificados do lead.
• leads.external_id: identificador externo do lead.
• leads.contact_type: tipo de lead.
• leads.item_id: identificador do item.
• leads.created_at: data de criação do lead.
• leads.status: estado do lead.
• paging: contém informações de paginação.
• paging.offset: posição do primeiro elemento a ser devolvido.
• paging.limit: número máximo de elementos por página.
• paging.total: número total de elementos.
• date_from: data inicial dos resultados.
• date_to: data final dos resultados.

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.

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.

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	-




Campos de la respuesta

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

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

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.