Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 28/08/2024

Personas Interesadas

Importante:
Este recurso está disponible para vehículos e inmuebles en todos los sites.

El atributo "channels" será deprecado en nuestra API. En su lugar, "contact_types" será el nuevo estándar. Ambos atributos pueden ser utilizados por el momento, pero pronto solo estará disponible "contact_types". Por favor, actualicen sus llamadas de API para utilizar "contact_types" en lugar de "channels" en los valores de entrada.

El recurso /vis/users/$USER_ID/leads/seller permite al vendedor obtener datos de contacto de los compradores interesados en sus publicaciones. Para recibir notificaciones sobre los clientes interesados, debes suscribirte al tópico VIS Leads, y después de recibir la notificación consultar el recurso de /leads.


Importante:
En el caso que ya tengas una integración con el API de Preguntas y trates las preguntas como notificación de contacto (Leads), te recomendamos que cuando te suscribas al tópico de Leads no actives las notificaciones de Questions, esto para evitar duplicidad en los Leads.

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 date_from y date_to. Para una búsqueda más específica, se puede utilizar el parámetro contac_types, que representa el tipo de contacto a retornar.


Llamada:

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

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&contact_types=true&contac_types=credit,question,whatsapp

Valores de entrada

Atributo Tipo de dato Descripción Required Valor por Defecto
USER_ID int Identificador del vendedor. -
OFFSET int Posición del primer elemento en la lista de ítems. No 0
LIMIT int Cantidad de elementos máximos del listado de ítems. No 10
date_from string Fecha de início 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.
date_to 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 tipos de contacto.
contact_types string Tipo de contactos a retornar. Si no se envía se retornan todos los tipos de contactos. No Todos los tipos de contacto.
item_id string Identificador del item, formato MLX1234567. No -
buyer_ids int Identificador del comprador, para más de uno separar con coma. -
Nota:
*El atributo "channels" será deprecado en nuestra API. En su lugar, "contact_types" será el nuevo estándar .


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: número de identificación del comprador. Solo si el acceso es público.
  • results.identification_number: teléfono del comprador. Solo si el acceso es público.
  • results.identification_type: tipo de identificación del comprador. Solo si el acceso es público.
  • results.leads: contiene listado de leads generados por el comprador.
  • leads.id: identificador del lead.
  • leads.external_id: identificador externo del lead.
  • leads.contact_type: tipo de lead.
  • leads.item_id: identificador del ítem.
  • leads.created_at: fecha de creación del lead.
  • 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.

Tipos de Leads Disponibles (contact_types)

Importante:
No todos los tipos de contactos estarán disponibles para todos los usuarios. La disponibilidad de contactos puede variar según la vertical y el tipo de usuário .

  • whatsapp: un comprador apreta el botón de WhatsApp.
  • question: un comprador hace una pregunta.
  • call: un comprador apreta el botón de llamar.
  • credit: simulación de crédito.

Respuesta:

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

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 { "code": "bad_request", "message": "invalid format USER_ID" } Identificador de usuario con 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 contacto inválido.
403 Forbidden { "code": "forbidden", "message": "invalid token caller" } Access token no pertenece al 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." } Acceso al endpoint sin access token.
403 Forbidden { "code": "forbidden", "message": "invalid token" } Access token inválido o expirado.
429 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. -

Campos de la respuesta

  • id: identificador del lead.
  • contact_type: tipo de lead.
  • item_id: identificador del ítem.
  • 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_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.
429 Too many requests { "code":"too_many_requests", "message":"quota exceeded" } Demasiadas solicitudes realizadas. Por favor, espere un momento antes de intentar nuevamente.