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

1. Briefly describe the customer journey of the visit request.
2. Describe each of the webhooks and which variable domains it accepts.
3. 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

1. The professional seller account must be registered.
2. Register the application to obtain the token.
3. Authentication as seller or integrator as appropriate.
4. Generate seller settings.
5. List items on the platform.
6. Mark items as online leases.
7. 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
email	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:

1. Automatic for schedules that are cancelled by item life cycle.
2. Automatic upon completion of the highlight package.
3. Availability control mechanism executed by Mercado Libre or after finalizing a listing.
4. 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"
      }
    ]
  }
}