Experiência para imóveis

No Mercado Livre, queremos criar uma nova experiência de aluguel e venda de imóveis para o comprador por meio de publicações que ofereçam uma experiência superior com foco em garantir a disponibilidade dos imóveis e assegurar a resposta a dúvidas e solicitações de agenda em tempo hábil.

Este guia tem como objetivo descrever e exemplificar como o Mercado Livre se conecta com os parceiros que hoje estão dentro do modelo de solicitação de visita, o customer journey e em qual etapa cada um dos atores envolvidos participa.

Objetivos

• Descrever brevemente o customer journey de solicitação de visita.
• Descrever cada um dos webhooks e quais são os domínios de variáveis que aceita.
• Fornecer diretrizes técnicas de como integrar-se com nosso sistema para utilizar as atualizações em tempo real e APIs.

Passos para iniciar a integração

1. A conta do vendedor profissional deve estar registrada.
2. Registrar a aplicação para a obtenção do token.
3. Autenticação como vendedor ou integrador, conforme aplicável.
4. Publicar itens na plataforma.
5. Marcar itens como solicitação de visita.
6. Obter detalhes da agenda para verificar o fluxo.

Atualizações em Tempo Real

Essas atualizações em tempo real são utilizadas pelo parceiro para obter mais informações sobre a intenção de visita. Ao mesmo tempo, também nos permitem fornecer mais informações sobre o estado da intenção de visita gerada pelo comprador.

É importante que o seller tenha configurado em seu sistema todos os endpoints da nossa API e realize as chamadas sempre que desejar alterar o estado de uma agenda. Assim que um comprador agendar uma visita, as informações são enviadas ao seller, que poderá começar a realizar as chamadas para nossa API para alterar o estado.

Configurações

As configurações são necessárias para operar nos fluxos de visita e, adicionalmente, informar sobre as condições de aluguel de cada seller em suas propriedades. Essa informação é exibida em cada publicação e dentro do fluxo de visita.

Criar configuração

Para os sellers que possuem APENAS propriedades em VENDA, os valores padrão devem ser os seguintes:

Chamada:

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,
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 4,
"allow_guest_login": true
}'

A seguir, são detalhadas as validações aplicadas em cada atributo.

Atualizar configuração

Chamada:

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 '{
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 10,
"email_notify_schedule": true,
"salary_multiplier": 3,
"allow_guest_login": true
}'

A seguir, são detalhadas as validações aplicadas em cada atributo:

Obtenção de configuração

Por provider_Id:

Chamada:

curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/$provider_Id' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Por seller_Id:

Chamada:

curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/configurations/seller/$seller_Id' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Resposta

Em ambos os casos, por providerId e sellerId, o JSON retornado será o seguinte:

{
"provider_id": "123456789",
"codebtor_required": false,
"latest_dependent_worker_payrolls": 6,
"latest_independent_worker_payrolls": 12,
"email_notify_schedule": true,
"salary_multiplier": 3,
"allow_guest_login": true
}

Descrição dos atributos

A seguir, são detalhadas as validações em cada parâmetro para obter uma configuração:

Marcação e Desmarcação de itens

Marcar e desmarcar itens

Este endpoint é utilizado para marcar itens que não estão com Solicitação de Visita para que sejam convertidos ao modelo com Solicitação de visita e vice-versa. Essa ação dependerá do campo enable_rex enviado. Caso já se tenha tentado marcar ou desmarcar e por algum motivo o processo falhe, é possível executar este endpoint para tentar marcá-lo novamente.

Durante o processo de marcação de itens, é possível obter um código de status 422, indicando que a solicitação foi aceita, mas não pôde ser processada, porque o seller não cumpre as condições para marcar itens.

Os parâmetros para realizar a chamada são os seguintes:

Chamada:

curl --location --request POST
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/items/tags' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "seller_id": 123123123,
  "item_ids": ["MLC123","MLC321"],
  "enable_rex": true
}'

E o JSON retornado será a lista de itens marcados/desmarcados:

[
        "MLC123",
        "MLC321"
]

APIs

Notificação de leads de agenda

Quando no marketplace do Mercadolibre.cl for acionada uma intenção de visita por parte do cliente (comprador) ou quando uma agenda for atualizada para qualquer outro estado, será enviada uma notificação por meio do tópico público VIS Leads, utilizando o filtro de Visit Request.

Para isso, é necessário acessar o aplicativo que recebe todos os leads e habilitar este filtro. A callback URL definida para receber as notificações receberá o conteúdo da seguinte forma:

{
  "_id": "abcd-qwer-1234",
  "topic": "vis_leads",
  "resource": "/vis/leads/{lead_id}",
  "user_id": 123456789,
  "application_id": 123456789123456789,
  "sent": "2025-01-27T18:21:06.159Z",
  "attempts": 1,
  "received": "2025-01-27T18:21:06.057Z",
  "actions": [
    "visit_request"
  ]
}

O campo lead_id corresponde ao identificador do Lead de agenda. Em seguida, deve-se realizar o API Call para consultá-lo:

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

Para mais detalhes, consulte a documentação na seção VIS Leads. Ao consultar o Lead, você poderá obter o ID da agenda associada fornecido pelo campo external_id. Com ele, poderá consultar a agenda e seu estado na seção Obtenção de detalhe de agenda.

Para os integradores que possuem "notification_url" definida em sua configuração e habilitaram o filtro "Visit Request" no tópico "VIS Leads", estarão recebendo a notificação de agenda tanto por nossos sistemas quanto em sua callback URL de notificações, ou seja, de forma duplicada.

Se desejar receber notificações apenas do tópico "VIS Leads", deve atualizar o campo "notification_url" e deixá-lo vazio.

{
  "notification_url": ""
}

Dessa forma, as agendas deixarão de ser notificadas pelo nosso sistema interno. Para mais detalhes sobre como alterar a configuração, acesse a seção Atualizar configuração

Visita

Gerar Agenda

Para realizar uma agenda pelo portal do Mercado Livre, deve-se fazê-la por URL:

https://www.mercadolibre.cl/agendar/visita-inmuebles/{itemId}

É importante destacar que esta URL deve ser utilizada diretamente no navegador, substituindo o parâmetro {itemId} pelo correspondente à publicação. Além disso, tanto o usuário quanto a publicação devem ser de teste, portanto não se devem utilizar dados produtivos.

O parâmetro para especificar a publicação sobre a qual criar a agenda é:

{itemId}

O qual representa o ID da publicação, exemplo: MLC916101223.

Obtenção de detalhe de agenda

Chamada:

curl --location --request GET
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules/$schedule_Id' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

O parâmetro para realizar a chamada é:

$schedule_Id

O qual representa o ID da agenda a consultar. O JSON retornado será o seguinte:

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

Seus respectivos tipos de dados são:

Atualização status agenda

Chamada:

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

A seguir, detalhamos o domínio da variável data:

(*) O estado scheduling_contacting serve para indicar que o seller já está se comunicando com o buyer para coordenar uma data e hora da visita. O objetivo de utilizar este estado é evitar o processo de expiração de agendas, conforme explicado na seção Agenda expirada. Este estado é utilizado quando um seller usa algum canal de contato como Whatsapp ou Call para contatar o buyer. Desde o Mercado Livre o processo está automatizado para detectar intenções de contato a partir do Painel de Pessoas interessadas, Emails e Whatsapp ao buyer.

Scheduling_canceled

O domínio da variável do Status_code: 2 (scheduling_canceled) é o seguinte:

(**) Estas razões são utilizadas para sinalizar aquelas agendas que foram canceladas pelos seguintes motivos:

• Automática para as agendas canceladas por ciclo de vida do item (18).
• Automática por finalização do pacote de destaque (19).
• Mecanismo de controle de disponibilidade executado pelo MercadoLibre ou após finalizar uma publicação. (24).
• Seller que finaliza manualmente seu item e este possui agendas associadas. (15, 20, 21).

Cabe destacar que estas razões são apenas de uso interno, portanto não deveriam ser usadas diretamente nas requests.

Como estas são razões de forma automática e interna, o estado do cancelamento será notificado conforme indicado na seção notificação de estados de agenda.

Razões do comprador

Esses códigos e razões correspondem à resposta fornecida pelo comprador. Não devem ser usados pelo integrador/vendedor.

Visit_success

Como indicado anteriormente, quando uma agenda não é gerenciada, o buyer é consultado se pôde ou não visitar a propriedade, caso indique que sim pôde visitar a propriedade, a agenda passará a Visita Realizada, junto com isso, indicamos a seguinte razão de por que uma agenda pode ser concluída pelo buyer:

Agenda expirada (processo automático interno)

O sistema conta com um processo automático que se encarrega de expirar todas as agendas que não foram gerenciadas e se encontram no estado de "agendas criadas", esta ação é executada após 3 dias consecutivos desde a data de intenção do buyer de visitar a propriedade.

Exemplo: o buyer gera uma solicitação de visita com a intenção de visitar a propriedade no dia 1 de novembro, após 3 dias consecutivos (4 de novembro), no 4º dia nas primeiras horas, se a agenda ainda não foi gerenciada, esta procederá a expirar. As agendas criadas que são expiradas ficam com a seguinte condição:

Como esta é uma razão de forma automática e interna, o estado da expiração será notificado conforme indicado na seção Notificação de leads de Agenda.

Unidades MultiFamily

Edição de preço, aumento ou diminuição de unidades

Este endpoint é utilizado para atualizar o preço das unidades, bem como aumentar ou diminuir o estoque das mesmas. Com o objetivo de que não sejam exibidas unidades na publicação que não estão disponíveis e, portanto, não sejam gerados novos agendamentos, e que, caso estejam novamente disponíveis, possam ser exibidas. Adicionalmente, oferece a opção de atualizar o preço das unidades.

O endpoint suporta a atualização de uma lista de unidades por meio do campo units no body.

Chamada:

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"
         }
      ]
   }
}'

O body é o seguinte:

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

A seguir são detalhados os valores de status_code e status_name.

A seguir é detalhado o domínio do atributo operation: