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 12/07/2024

Interested persons

Important:
This resource is available for vehicles and real estate on all websites.

The resource /vis/users/$USER_ID/leads/buyers allows the buyer to obtain contact details of buyers interested in their listings.



Check interested users in the seller’s

Now, the seller can check all the contact details of the interested users, with the possibility of paginating them by means of the offset parameter, which indicates the position of the first item to fetch, and the limit parameter, which indicates the maximum number of items to fetch. In addition, the details can be filtered by a specific time period, using the "dateFrom" and "dateTo" parameters. For a more specific search, the channels parameter can be used, which represents the type of contact to return. Also, the "has_credit_line" parameter allows the system to determine whether to display only those users who have an active credit line.


Request:

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

Example:

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

Input values

Attribute Type of detail Description Required Default value
userID int Seller identifier. Yes -
offset int Position of the first element of the list of items. No 0
limit int Number of maximum elements of the list of items. No 10
dateFrom string Search start date. Allowed formats: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02 No 7 days before the current date.
dateTo string Search end date. Allowed formats: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02 No Current date.
channels string Type of contacts to provide. If it's not sent, all types of contacts are provided. No All channels.
offset int Position of the first item in the list of items. No 0
has_credit_line boolean Indicates whether the interested buyer has a credit line. If it's not sent, buyers with and without credit lines are provided. No -

Response fields

  • results: contains list of results.
  • results.id: buyer identifier.
  • results.item_id: item identifier.
  • results.name: buyer identifier. Only if access is public.
  • results.email: buyer’s email. Only if access is public.
  • results.phone: buyer’s phone number. Only if access is public.
  • results.leads: contains a list of the leads generated by the buyer.
  • leads.uuid: lead identifier.
  • leads.external_id: external lead identifier.
  • leads.channel: type of lead.
  • leads.item_id: item identifier.
  • leads.created_at: lead creation date.
  • leads.has_credit_line: indicates if the buyer has a credit line.
  • leads.status: status of the lead.
  • paging: contains pagination information.
  • paging.offset: position of the first element to provide.
  • paging.limit: number of maximum elements per page.
  • paging.total: number of total elements.
  • date_from: results start date.
  • date_to: results end date.

Response:

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

Possible errors

Errors in the search of interested users.

Error_code Tipo Message of the error Reasons
400 Bad Request { "message": "invalid date range", "error": "bad_request", "status": 400, "cause": [ "start date is greater than end date" ] } The start date is after the end date of the search.
400 Bad Request { "message": "invalid start date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2021-01-021\": extra text: \"1\"" ] } Start date with invalid format.
400 Bad Request { "message": "invalid end date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2024-01-022\": extra text: \"2\"" ] } End date with invalid format.
400 Bad Request { "message": "invalid has credit line", "error": "bad_request", "status": 400, "cause": [ "strconv.ParseBool: parsing \"2021-01-021\": invalid syntax" ] } Indicator parameter of credit line with invalid format.
400 Bad Request { "code": "bad_request", "message": "invalid format userID" } User ID with invalid format.
400 Bad Request { "message": "error decoding search params", "error": "bad_request", "status": 400, "cause": [ "schema: invalid path \"channel\"" ] } Invalid parameter.
400 Bad Request { "message": "invalid lead type", "error": "bad_request", "status": 400, "cause": [ "invalid lead type: invalid " ] } Invalid contact type.
400 Forbidden { "code": "forbidden", "message": "invalid token caller" } Access token doesn’t belong to the seller.
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." } Access to the endpoint without access to the token.
400 Forbidden { "code": "forbidden", "message": "invalid token" } Invalid or expired access token.
400 Too many requests { "code":"too_many_requests", "message":"quota exceeded" } Too many requests. Please wait a moment before trying again.

Get details of a Lead

When Mercado Libre notifies the creation of a new lead related to interested users, it does so by mentioning the ID in the message. To obtain the details you have to use that identifier in the resource "/vis/leads/{$LEAD_ID}", which will give you the corresponding details.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/$LEAD_ID

Exmaple:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/3f2dedf2-dfbd-4981-a726-40b13aa172ff

Entry values

Attribute Type of detail Description Required Default value
leadID string Lead identifier. Yes -

Response fields

  • id: lead identifier.
  • contact_type: type of lead.
  • item_id: item identifier.
  • buyer__has_credit_line: indicates if the buyer has a credit line.
  • created_at: lead creation date.
  • external_id: external lead identifier.
  • status: status of the lead.
  • buyer_id: buyer identifier.
  • name: buyer name. Only if access is public.
  • email: buyer email. Only if access is public.
  • phone: buyer’s phone number. Only if access is public.

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

Possible errors

Errors in the search of the detail of a lead.

Error_code Tipo Message of the error Reasons
400 Bad Request { "code": "bad_request", "message": "missing lead_id" } Incorrect or non-existent identifier.
400 Bad Request { "code": "bad_request", "message": "invalid callerID" } The caller ID provided is not the right one.
400 Bad Request { "code": "bad_request", "message": "invalid clientID" } The client ID provided isn’t available or isn’t correct.
403 Forbidden { "code": "forbidden", "message": "invalid token caller" } Access token doesn’t belong to the buyer.
403 Forbidden { "blocked_by": "PolicyAgent", "path": "/vis/leads/142536", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." } Access to the endpoint without access to the token.
403 Forbidden { "code": "forbidden", "message": "invalid token" } Invalid or expired access token.
404 Not Found { "code": "not_found", "message": "lead not found" } The identifier provided is not associated with any user lead.
409 Too many requests { "code":"too_many_requests", "message":"quota exceeded" } Too many requests. Please wait a moment before trying again.