Pessoas interessadas

O recurso /vis/users/$USER_ID/leads/buyers ermite ao vendedor obter os dados de contato dos compradores interessados nos seus anúncios.

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 dateFrom e dateTo. Para uma pesquisa mais específica, pode utilizar o parâmetro channels, que representa o tipo de contato a devolver. Além disso, o parâmetro has_credit_line permite que o sistema determine se deve exibir apenas os usuários que têm uma linha de crédito ativa.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?offset=$OFFSET&limit=$LIMIT&dateFrom=$DATE_FROM&dateTo=$DATE_TO&hasCreditLine=$HAS_CREDIT_LINE&channels=$CHANNELS

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&hasCreditLine=true&channels=credit,question,whatsapp

Valores de entrada

Atributo	Tipo de dados	Descrição	Obrigatório	Valor padrão
userID	int	Identificador do vendedor.	Sim	-
offset	int	Posição do primeiro elemento na lista de itens.	Não	0
limit	int	Número máximo de elementos na lista de itens.	Não	10
dateFrom	string	Data de início da pesquisa. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	Não	7 dias antes da data atual.
dateTo	string	Data do fim da pesquisa. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	Não	Data atual.
channels	string	Tipo de contatos a devolver.Se não for enviado, são devolvidos todos os tipos de contatos.	Não	Todos os canais.
offset	int	Se não for enviado, são devolvidos os compradores com e sem linha de crédito.	Não	0

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.leads: contém uma lista do leads gerados pelo comprador.
• leads.uuid: identificador do lead.
• leads.external_id: identificador externo do lead.
• leads.channel: tipo de lead.
• leads.item_id: identificador do item.
• leads.created_at: data de criação do lead.
• leads.has_credit_line: indica se o comprador tem uma linha de crédito.
• 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.

Resposta:

{
  "results": [
    {
      "id": 2678328,
      "name": "John Doe",  
      "email": "jhon@example.com",  
      "phone": "+5491198765432",  
      "item_id": "MLA1430828018",
      "leads": [
        {
          "uuid": "6b4aebf8-5570-47b8-9224-c1c177621575",
          "channel": "question",
          "item_id": "MLA1430828018",
          "has_credit_line": true,
          "created_at": "2023-07-12T22:17:02Z",
          "external_id": "12776297658",
          "status": "active"
        }
      ]
    }
  ],
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 20
  },
  "date_from": "2021-07-12T22:17:02Z",
  "date_to": "2021-07-12T22:17:02Z"
}

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.
400	Bad Request	{ "message": "invalid has credit line", "error": "bad_request", "status": 400, "cause": [ "strconv.ParseBool: parsing \"2021-01-021\": invalid syntax" ] }	Parâmetro do indicador de linha de crédito com formato inválido.
400	Bad Request	{ "code": "bad_request", "message": "invalid format userID" }	Identificador com formato inválido.
400	Bad Request	{ "message": "error decoding search params", "error": "bad_request", "status": 400, "cause": [ "schema: invalid path \"channel\"" ] }	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.
400	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token não pertence ao vendedor.
400	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.
400	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Access token inválido ou expirado.
400	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.
• buyer__has_credit_line: código que indica se o comprador tem uma linha de crédito.
• 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__has_credit_line": false,
    "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.
409	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Muitos pedidos realizados. Por favor, aguarde um momento antes de tentar novamente.