Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
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. |