Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Real estate experience
At Mercado Libre, we want to generate a new leasing experience focused on ensuring the availability of the properties and guaranteeing the response to doubts and schedule requests promptly.
This guide aims to describe and exemplify how Mercado Libre connects with the partners that today are within the online leasing model, describing each of the webhooks and which are the acceptable variable domains along with the technical guidelines on how to integrate with us in order to make use of the Webhooks and APIs.
Objectives
- Briefly describe the customer journey of the visit request.
- Describe each of the webhooks and which variable domains it accepts.
- Provide technical guidelines on how to integrate with our system to make use of real-time updates and APIs.
Considerations
Currently, we have two environments available for integration:
- Production environment: this is the environment used to access the production version of our system.
- Stage environment: this is our pre-production environment, reserved for testing and development. To access it, it is necessary to add the
?scope=stage
parameter to the main URL. For example:URL/?scope=stage
.
Please use this environment for testing and development before implementing any changes in the production environment.
Steps to start integration
- The professional seller account must be registered.
- Register the application to obtain the token.
- Authentication as seller or integrator as appropriate.
- Generate seller settings.
- List items on the platform.
- Mark items as online leases.
- Obtain details of the schedule to verify the flow.
Real time updates
These webhooks are used by the partner to obtain more information about the visit intention and the reservation made by the customer (buyer).
Also to provide more information regarding the status of the visit intention generated by the customer and thus to have a transparent journey for the buyer.
Settings
The settings are necessary to operate in the visit flows and additionally inform about the leasing conditions of each seller on their properties. This information is displayed in each listing and within the visit flow.
Create new settings
The validations applied to each parameter for new Settings are detailed below:
Parameter | Required | Min | Max | Tipe | Default | Description | seller_id | Yes | 1 | - | Long | - | Unique supplier or seller identifier. |
---|---|---|---|---|---|---|
notification_url | No | 0 | 150 | String | “” | URL to receive schedule notifications. |
codebtor_required | No | - | - | Boolean, valores permitidos true o false. | true | Codebtor endorsement requirement. |
latest_dependent_worker_payrolls | No | 0 | 12 | Integer | 3 | Number of dependent workers’ last payrolls. |
latest_independent_worker_payrolls | No | 0 | 24 | Integer | 6 | Number of independent worker pay slips. |
email_notify_schedule | No | - | - | Boolean, valores permitidos true o false. | true | Notification of schedule by mail to the partner. |
salary_multiplier | No | 1 | 10 | Double | 3 | Income multiplier factor. |
notification_header_token | No | 1 | 50 | String | “” | Authentication token to receive notifications of schedules and reservations. |
notification_token | No | 1 | 300 | String | “” | Header linked to the token to receive notifications of schedules and reservations. |
allow_guest_login | No | - | - | Boolean | false | Allows schedules of non-logged-in users. |
In the case of the notification_header_token and notification_token they must only be completed when a notification URL is configured and their value will be automatically encrypted when creating the setting.
Producción:
curl --location --request POST
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw '{
"seller_id": 123456789,
"notification_url": "https://notification-url.com",
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 4,
"notification_header_token": "Authorization",
"notification_token": "Bearer ANB7xKhiUZmwltVd3f1odcHHM9VAwg02kwmLwtZwHv3S",
"allow_guest_login": true
}'
Stage:
curl --location --request POST
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw '{
"seller_id": 123456789,
"notification_url": "https://notification-url.com",
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 4,
"notification_header_token": "Authorization",
"notification_token": "Bearer ANB7xKhiUZmwltVd3f1odcHHM9VAwg02kwmLwtZwHv3S",
"allow_guest_login": true
}'
Update Settings
The validations applied to each attribute are detailed below.
*Since this is a partial update, all fields are optional and only those that you want to update should be sent.
Parameter | Required | Min | Max | Tipe | notification_url | No | 1 | 150 | String |
---|---|---|---|---|
codebtor_required | No | - | - | Boolean, allowed values: true or false. |
latest_dependent_worker_payrolls | No | 0 | 12 | Integer |
latest_independent_worker_payrolls | No | 0 | 24 | Integer |
email_notify_schedule | No | - | - | Boolean, allowed values: true or false. |
salary_multiplier | No | 1 | 10 | Double |
allow_guest_login | No | - | - | Boolean, allowed values: true or false. |
notification_header_token | No | 1 | 50 | String |
notification_token | No | 1 | 300 | String |
Producción:
curl --location --request PATCH
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw '{
"notification_url": “https://notification-url.com”,
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 3,
"notification_header_token": "Authorization",
"notification_token": "Bearer ANB7xKhiUZmwltVd3f1odcHHM9VAwg02kwmLwtZwHv3S",
"allow_guest_login": true
}'
Stage:
curl --location --request PATCH
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw ''{
"notification_url": “https://notification-url.com”,
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 4,
"notification_header_token": "Authorization",
"notification_token": "Bearer ANB7xKhiUZmwltVd3f1odcHHM9VAwg02kwmLwtZwHv3S",
"allow_guest_login": true
}'
Obtaining settings
The validations for each parameter to obtain a setting are detailed below:
Variable | Tipe | Description | provider_id | String | Unique supplier or seller identifier. |
---|---|---|
notification_url | String | URL to receive schedule notifications. |
fantasy_name | String | Alias linked to the user. |
codebtor_required | Boolean | Codebtor endorsement requirement. |
latest_dependent_worker_payrolls | Integer | Number of dependent workers’ last payrolls. |
latest_independent_worker_payrolls | Integer | Number of independent worker pay slips. |
email_notify_schedule | Boolean | Notification of schedules by mail to the partner. |
salary_multiplier | Double | Income multiplier factor. |
notification_token | String | Authentication token to receive notifications of schedules and reservations. |
notification_header_token | String | Header linked to the token to receive notifications of schedules and reservations. |
allow_guest_login | Boolean | Allows schedules of non-logged-in users. |
With providerId
Stage:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
* Important to make the call with the user seller TEST and add within the queryParams scope=stage.
Producción:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
Through sellerId
URL Stage:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/seller/{sellerId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
* Important to make the call with the user seller TEST and add within the queryParams scope=stage.
Ambiente de producción:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/seller/{sellerId}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
In both cases, using provider ID and seller ID the JSON that will be returned will be the following:
Response:
{
"provider_id": "123456789",
"notification_url": "https://notification-url.com",
"fantasy_name": "Test Company",
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 12,
"email_notify_schedule": true,
"salary_multiplier": 3,
"notification_token": "gXt2x3qfL22UsqXLUY0egda32sffs2saj8UFyhw3Sw=="
"notification_header_token": "ne/GHVXAv2x9YxzJbCKzMA==",
"allow_guest_login": true
}
Checking and unchecking items
This endpoint is used to mark items that are under Traditional Lease to be converted to Online Lease and vice versa, this action will depend on the status sent.
In case you have already tried to check or uncheck and for some reason the process fails, you can run this endpoint to try to check it again.
In the case of stage and production, the parameters to make the request are the following:
Field | Description | Example | seller_id | ID of the seller to which the items belong. | 12345678 |
---|---|---|
status | Debe enviarse el status para marcar ítem como Solicitud de visita: - pending_approval -remove_approval |
The status must be sent to mark the item as an online lease.
- pending_approval. For the case of unchecking and converting the item to a traditional lease, the following must be sent -remove_approval |
operation_reason | This is the reason given by the Mercado Libre operator to reject the items. | This field must always be empty (""). |
item_ids | Corresponds to the items to be checked. | It must be an array where the IDs must be all together and separated by commas (,) e.g.: MLC123,MLC321
Note: the items to be checked must belong to the "seller_id" that has been entered. |
* Important to make the call by passing in the seller_id the user ID of the TEST user and to add the queryParams scope=stage-
URL Stage:
curl --location --request POST
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/item-candidates?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw '{
"seller_id": 123123123,
"operator_id": null,
"status": "pending_approval",
"operation_reason": "",
"item_ids": ["MLC123","MLC321"]
}'
Producción:
curl --location --request POST
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/item-candidates' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}} \
--header 'Content-Type: application/json' \
--data-raw '{
"seller_id": 123123123,
"operator_id": null,
"status": "pending_approval",
"operation_reason": "",
"item_ids": ["MLC123","MLC321"]
}'
And the JSON that will be returned will be the following:
[
{
"item_id": "MLC123",
"seller_id": 12345678,
"created_at": "2023-04-25T14:32:44.283691Z",
"last_updated": "2023-04-25T14:32:44.283706Z",
"status": "pending_approval",
"retries": 1,
"historical_events": [
{
"operation_date": "2023-04-25T14:32:44.281935Z",
"new_status": "pending_approval"
}
]
},
...
]
Obtaining status checked items
In the case of stage and production, the parameters for making the call are as follows:
Parameter | Description | Example | sellerId | ID of the seller to which the items belong. | 12345678 |
---|---|---|
item_ids | ID of the items to be searched. | They must be all together and separated by commas (,).ej: MLC123, MLC321 |
status | Statuses in which the checked items are found. | They must be all together and separated by commas (,)
e.g.: - approved - rejected. the possible statuses of the items are: - pending_approval - approved - rejected - remove_approval |
size | Size of the number of items to be obtained. | 100 |
from | This is the number of records you want to skip counting from the first one found, this is for paging. | e.g.: if I place 10, this is to skip the first 10 items. |
*field | It is the field by which you want to sort. | One of the following values must be chosen: - item_id - created_at - last_updated |
*field_type | Type of detail to be sorted. | One of the following values must be chosen: - text - date If “field” is selected “item_id”, the value of this parameter must be “text”. For “created_at” and “last_updated” the value must be “date”. |
*order | Type of data sorting. | One of the following values must be chosen: - asc - desc |
In case you want to sort the results, it is mandatory to fill in these last three parameters, otherwise, these parameters must be omitted.
URL Stage:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/item-candidates/seller/{sellerId}?scope=stage&item_ids={itemIds}&status={statusIds}&size={size}&from={from}&field={field}&field_type={field_type}&order={order}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
* Important to make the call with the user seller TEST and add within the queryParams scope=stage.
Producción:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/item-candidates/seller/{sellerId}?item_ids={itemIds}&status={statusIds}&size={size}&from={from}&field={field}&field_type={field_type}&order={order}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
And the JSON that will be returned will be the following:
{
"total": 5,
"result": [
{
"item_id": "MLC321",
"seller_id": 123123123,
"created_at": "2023-02-20T18:09:32.313833Z",
"last_updated": "2023-03-21T13:00:12.919943Z",
"status": "approved",
"retries": 4,
"api_reason": "Error"
},
{
"item_id": "MLC123",
"seller_id": 123123123,
"created_at": "2023-02-24T20:59:21.216387Z",
"last_updated": "2023-04-12T16:54:56.21958Z",
"status": "approved",
"retries": 1,
"operation_reason": "problema"
},
...
]
}
Their respective variable types are:
Variable | Tipe | item_id | String |
---|---|
seller_d | Long |
created_at | String |
last_updated | String |
status | String |
retries | Long |
operation_reason | String |
APIs
Schedule status notifications
When an intention to visit is made from the Real Estate Portal or the Mercadolibre.cl marketplace by the customer (buyer) or when a schedule is updated to any other status internally, they will be notified using a request to an endpoint (which must be exposed by each partner).
This endpoint must have the following suffix: /scheduling, for example:
https://api.partner.cl/api/v1/ao/scheduling
This is the body (POST method) ::
{
scheduling_id: 123456789,
status: “schedule_created”
}
Where the scheduling_id value corresponds to the schedule ID and the status value corresponds to the status that a schedule was updated.
For the status parameter it can have the following values:
Status | Description | schedule_created | Schedule created from Real Estate Portal or MercadoLibre.cl marketplace. |
---|---|
schedule_canceled | The schedule was cancelled internally due to finalized listing. |
schedule_expired | The schedule expired internally after 72 working hours from its creation due to non-management. |
Visit
Generate schedule
To simulate a schedule from the Mercado Libre portal in staging, you must use the following URL:
curl --location 'https://api.mercadolibre.com/oauth/token' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={{APP_ID}} \
--data-urlencode 'client_secret={{CLIENT_SECRET}}
URL Stage:
https://www.mercadolibre.cl/agendar/visita-inmuebles/{itemId}?scope=stage
It is important to highlight that this URL must be used directly in the search engine replacing the parameter {itemId} by the one corresponding to the listing and, on the other hand, both the user and the listing must be a test, so no productive details must be used.
The parameter to specify the listing on which to create the schedule is:
{itemId}
It represents the listing ID, for example: MLC916101223.
Obtaining schedule detail
URL Stage:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules/{scheduleId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
* It’s important to make the call with the user seller TEST and add within the queryParams scope=stage
Producción:
curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules/{scheduleId}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
In both cases, the parameter to make the request is:
{scheduleId}
Which represents the ID of the schedule to be checked.
And the JSON returned will be as follows:
{
"id": 27002,
"unit_name ":"1808-B",
"user_id": 1006753330,
"email": "useremail@email.cl",
"name": "Test Test",
"last_name": "",
"item_id": "MLC916101223",
"phone": "1111-1111",
"scheduling_date": ["2022-03-30"],
"scheduling_time_period": [{"from": "09:00:00","to": "12:00:00"}],
}
Their respective detail types are:
Variable | Tipe | id | Long |
---|---|
unit_name | String |
user_id | Long |
String | |
name | String |
last_name | String |
itemId | String |
phone1 | String |
phone2 | String |
scheduling_time | List (string) |
scheduling_time_period | List (string) |
Schedule status update
The variable domain of the {OBJ_DATA} body required for updating the status of the Schedule is detailed below:
Status_code | Status_name | Description | Body | 2 | scheduling_canceled | Agenda cancelada | { code: "string" reason: “string” } |
---|---|---|---|
3 | scheduling_modified | Time modified | { scheduling_date: date // "2022-03-30" scheduling_time: string // “12:00” } |
4 | visit_success | Successful visit | {} |
5 | visit_fail | Failed visit | { code: "string" reason: “string” } |
6 | scheduling_confirmed | Confirmed time | { scheduling_date: date scheduling_time: string } |
Scheduling_canceled
The variable domain of the Status_code: 2 (scheduling_canceled) is as follows:
Code | Reason | Description | 1 | buyer_cancelled | Cancelled by the buyer. |
---|---|---|
2 | buyer_out_of_reach | Can’t contact the buyer. |
3 | agent_cancelled | Cancelled by the agent. |
6 | requirements_not_met | The buyer doesn’t meet requirements. |
7 | buyer_not_need_rental | The buyer doesn’t need the property. |
8 | requirement_rent_not_met | The buyer doesn’t pay the rent. |
9 | requirement_dicom_not_met | The buyer doesn’t comply with DICOM. (Departamento de Investigación y Crédito y Mercado de Capitales). |
10 | other_buyer_approved | Property taken by another tenant (approved). |
11 | buyer_rent_another_property | The buyer rented another property. |
12 | buyer_stop_answering | The buyer stopped responding. |
13 | buyer_not_show_up | The buyer didn’t show up. |
14 | buyer_searching_for_later | The buyer is looking for later on. |
15** | property_not_available | Property not available. |
16 | buyer_cancel_visit | Cancelled by the buyer. |
17 | agent_not_attend_visit | The agent didn’t show up. |
18** | property_not_available_from_life_cycle | Property not available due to life cycle. |
19** | property_not_available_from_pack_finished | Unavailable property due to a set of finalized listings. |
20** | property_not_available_from_seller_finished | Unavailable property because the seller finalized it. |
21** | property_not_available_from_partner_finished | Unavailable property because the integrator finalized it. |
22** | property_not_available_from_feedback_seller | The property is not available due to feedback from the seller indicating that it is not available. |
23** | property_not_available_from_feedback_buyer | The property is not available due to feedback from the seller indicating that it is not available. |
24** | property_not_available_from_seller_penalty | Property not available due to sanction to the seller. |
(**) These reasons are used to indicate those agendas that were cancelled for the following reasons:
- Automatic for schedules that are cancelled by item life cycle.
- Automatic upon completion of the highlight package.
- Availability control mechanism executed by Mercado Libre or after finalizing a listing.
- A seller who manually finalizes their item and it has associated schedules.
It should be noted that these reasons are for internal use only and should not be used directly in requests.
As these reasons are automatic and internal, we will be notifying the status of the cancellation as indicated in the section schedule status notification.
Visit_fail
The variable domain of the Status_code: 5 (visit_fail) is as follows:
Code | Reason | Description | 1 | buyer_no_show | The buyer didn’t show up. |
---|---|---|
2 | agent_no_show | The agent didn’t show up. |
Producción:
curl --location --request PUT
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
--header 'Content-Type: application/json' \
--data-raw '{
"scheduling_id": 12345,
"status_code": 12345,
"status_name": "string",
"message": "string",
"timestamp": "ISO 8601",
"data": {}
}'
URL Stage:
curl --location --request PUT
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
--header 'Content-Type: application/json' \
--data-raw '{
"scheduling_id": 12345,
"status_code": 12345,
"status_name": "string",
"message": "string",
"timestamp": "ISO 8601",
"data": {}
}'
In both cases, the body is as follows:
{
scheduling_id: "int",
status_code: "int",
status_name: "string",
message: "string",
timestamp: "ISO 8601", // ej: 2011-10-05T14:48:00.000Z
data: {OBJ_DATA} // se detalla más adelante
}
Expired schedule (automatic internal process)
The system has an automatic process that is responsible for expiring all schedules that have not been managed and are in the status of "created schedules". This action is executed after 72 business hours.
The created schedules that are expired are left with the following condition:
Code | Reason | Description | 1 | seller_no_response | The schedule expired due to having no response from the seller within the SLA (72 hours). |
---|
As this is an automatic and internal reason, the expiration status will be notified as indicated in the schedule status notification section.
MultiFamily Units
Price editing, increase or decrease of units
This endpoint is used to update the price of the units as well as to increase or decrease their stock. With the objective of not showing units in the listing that are not available and therefore should not generate new schedules, in the case of being available again, they can be shown. Additionally, it offers the option to update the price of the units.
The endpoint supports the update of a list of units through its units field in the body.
The values of status_code and status_name are as follows:
Status_code | Status_name | 1 | update_units (actualizar unidades) |
---|
The domain of the body operation attribute:
Operation | Description | price_updated | Allows you to update the unit price. |
---|---|
unit_added | Allows the unit to be increased. |
unit_removed | Allows the unit to be decreased. |
URL Stage:
curl --location --request PUT
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/items?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
--header 'Content-Type: application/json' \
--data-raw '{
"item_id": ML123,
"status_code": 1,
"status_name": "string",
"message": "string",
"timestamp": "ISO 8601",
"data": {
"units": [
{
"unit_name": "string",
"price": 200000,
"operation": "string"
},
{
"unit_name": "string",
"price": 400000,
"operation": "string"
}
]
}
}'
* It’s important to make the call with the user seller TEST and add within the queryParam scope=stage.
Producción:
curl --location --request PUT
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/items' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}
--header 'Content-Type: application/json' \
--data-raw '{
"item_id": ML123,
"status_code": 1,
"status_name": "string",
"message": "string",
"timestamp": "ISO 8601",
"data": {
"units": [
{
"unit_name": "string",
"price": 200000,
"operation": "string"
},
{
"unit_name": "string",
"price": 400000,
"operation": "string"
}
]
}
}'
In both cases, the body is as follows:
{
item_id: "int",
status_code: "int",
status_name: "string",
message: "string",
timestamp: "ISO 8601", // ej: 2011-10-05T14:48:00.000Z
data: {
units: [
{
unit_name: "string",
price: "int",
operation:"string"
}
]
}
}