Personas Interesadas

El recurso /vis/users/$USER_ID/leads/buyers permite al vendedor obtener datos de contacto de los compradores interesados en sus publicaciones.

Consultar interesados en los ítems del vendedor

Ahora, el vendedor puede consultar todos los datos de contacto de los interesados, con la posibilidad de paginarlos mediante el parámetro offset, que indica la posición del primer elemento a traer, 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 dateFrom y dateTo. Para una búsqueda más específica, se puede utilizar el parámetro channels, que representa el tipo de contacto a retornar. Asimismo, el parámetro has_credit_line le permite al sistema determinar si se deben mostrar solamente aquellos usuarios que cuenten con una línea de crédito vigente.

Llamada:

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

Ejemplo:

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 dato	Descripción	Required	Valor por Defecto
userID	int	Identificador del vendedor.	Si	-
offset	int	Posición del primer elemento de la lista de ítems.	No	0
limit	int	Cantidad de elementos máximos del listado de ítems.	No	10
dateFrom	string	Fecha de inicio de la búsqueda. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	No	7 días antes a la fecha actual.
dateTo	string	Fecha de término de la búsqueda. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02	No	Fecha actual.
channels	string	Tipo de contactos a retornar.Si no se envía se retornan todos los tipos de contactos.	No	Todos los channels.
offset	int	Posición del primer elemento de la lista de ítems.	No	0
has_credit_line	boolean	Indicador de si el comprador interesado tiene línea de crédito.Si no se envía retornan los comprador con y sin línea de crédito.	No	-

Campos de la respuesta

• results: contiene listado de resultados.
• results.id: identificador del comprador.
• results.item_id: identificador del ítem.
• results.name: nombre del comprador. Solo si el acceso es público.
• results.email: email del comprador. Solo si el acceso es público.
• results.phone: teléfono del comprador. Solo si el acceso es público.
• results.leads: contiene listado de leads generados por el comprador.
• leads.uuid: identificador del lead.
• leads.external_id: identificador externo del lead.
• leads.channel: tipo de lead.
• leads.item_id: identificador del ítem.
• leads.created_at: fecha de creación del lead.
• leads.has_credit_line: indicador si el comprador tiene línea de crédito.
• leads.status: estado del lead.
• paging: contiene información del paginado.
• paging.offset: posición del primer elemento a retornar.
• paging.limit: cantidad de elementos máximos por página.
• paging.total: cantidad de elementos totales.
• date_from: fecha inicial de resultados.
• date_to: fecha final de resultados.

Respuesta:

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

Posibles errores

Errores en la búsqueda de interesados.

Error_code	Tipo	Mensaje del error	Motivos
400	Bad Request	{ "message": "invalid date range", "error": "bad_request", "status": 400, "cause": [ "start date is greater than end date" ] }	La fecha de inicio es después de la fecha de término de la búsqueda.
400	Bad Request	{ "message": "invalid start date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2021-01-021\": extra text: \"1\"" ] }	Fecha de inicio con formato inválido.
400	Bad Request	{ "message": "invalid end date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2024-01-022\": extra text: \"2\"" ] }	Fecha de término con 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 indicador de línea de crédito con formato inválido.
400	Bad Request	{ "code": "bad_request", "message": "invalid format userID" }	Identificador de usuario con 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 contacto inválido.
400	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token no pertenece al 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." }	Acceso al endpoint sin access token.
400	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Access token inválido o expirado.
400	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Demasiadas solicitudes realizadas. Por favor, espere un momento antes de intentar nuevamente.

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

Atributo	Tipo de dato	Descripción	Requerido	Valor por Defecto
leadID	string	Identificador del lead.	Si	-

Campos de la respuesta

• id: identificador del lead.
• contact_type: tipo de lead.
• item_id: identificador del ítem.
• buyer__has_credit_line: indicador si el comprador tiene línea de crédito.
• 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.

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

Posibles errores

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

Error_code	Tipo	Mensaje del error	Motivos
400	Bad Request	{ "code": "bad_request", "message": "missing lead_id" }	Identificador incorrecto o inexistente.
400	Bad Request	{ "code": "bad_request", "message": "invalid callerID" }	El caller id proporcionado no está presente o no es correcto.
400	Bad Request	{ "code": "bad_request", "message": "invalid clientID" }	El client id proporcionado no está presente o no es correcto.
403	Forbidden	{ "code": "forbidden", "message": "invalid token caller" }	Access token no pertenece al 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." }	Acceso al endpoint sin access token.
403	Forbidden	{ "code": "forbidden", "message": "invalid token" }	Access token inválido o expirado.
404	Not Found	{ "code": "not_found", "message": "lead not found" }	El identificador proporcionado no está asociado a ningún lead del usuario.
409	Too many requests	{ "code":"too_many_requests", "message":"quota exceeded" }	Demasiadas solicitudes realizadas. Por favor, espere un momento antes de intentar nuevamente.