Experiência para imóveis

No Mercado Livre, queremos criar uma nova experiência de aluguel e venda de propriedades 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 agendamento de forma rápida e eficiente.

Este guia tem como objetivo descrever e exemplificar como o Mercado Livre se conecta com os parceiros que atualmente fazem parte do modelo de solicitação de visita, explicando a jornada do cliente e em que etapa cada um dos atores envolvidos participa desse processo.

Objetivos

• Descrever brevemente a jornada do cliente na solicitação de visita.
• Descrever cada um dos webhooks e quais são os domínios de variável que aceita.
• Fornecer diretrizes técnicas sobre como integrar-se ao nosso sistema para utilizar as atualizações em tempo real e APIs.

Considerações

Atualmente, temos dois ambientes disponíveis para integração:

• Ambiente de produção: este é o ambiente utilizado para acessar a versão em produção do nosso sistema.
• Ambiente de stage: este é o nosso ambiente de pré-produção, reservado para testes e desenvolvimento. Para acessá-lo, é necessário adicionar o parâmetro ?scope=stage à URL principal. Por exemplo: URL/?scope=stage.

Por favor, utilize este ambiente para testes e desenvolvimento antes de implementar qualquer mudança no ambiente de produção.

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 pelos parceiros para obter mais informações sobre a intenção de visita. Ao mesmo tempo, também nos permitem fornecer mais detalhes sobre o status da intenção de visita gerada pelo comprador.

É importante que o vendedor tenha configurado em seu sistema todos os endpoints da nossa API e realize as chamadas sempre que desejar alterar o status de uma agenda. Assim que um comprador agenda uma visita, a informação é enviada ao vendedor, que poderá então iniciar as chamadas à nossa API para atualizar o status.

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 vendedor em relação às suas propriedades. Essas informações são exibidas em cada publicação e dentro do fluxo de visita.

Criar configuração

Para aqueles vendedores que possuem apenas propriedades à VENDA, os valores padrão devem ser os seguintes:

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

Ambiente de produção:

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

Ambiente de stage:

curl --location --request PATCH 'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}?scope=stage' \n--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \n--header 'Content-Type: application/json' \n--data-raw '{
    "codebtor_required": false,
    "latest_dependent_worker_payrolls": 6,
    "latest_independent_worker_payrolls": 10,
    "email_notify_schedule": true,
    "salary_multiplier": 4,
    "allow_guest_login": true
}'

Ambiente de produção:

curl --location --request PATCH 'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}' \n--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \n--header 'Content-Type: application/json' \n--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 da Configuração

Por providerId:

curl --location --request GET 
'https://api.mercadolibre.com/vis-transactions-hub/configurations/provider/{providerId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \

Nota: é importante fazer a requisição com o ID do seller de teste e adicionar o queryParam scope=stage.

Ambiente de Produção:

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

Por sellerId:

curl --location --request GET 
'https://api.mercadolibre.com/vis-transactions-hub/configurations/seller/{sellerId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \

Nota: é importante fazer a requisição com o ID do seller de teste e adicionar o queryParam scope=stage.

Ambiente de Produção:

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

Resposta

Em ambos os casos, seja via providerId ou sellerId, o JSON retornado será o seguinte:

{
    "provider_id": "123456789",
    "fantasy_name": "Test Company",
    "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 de 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 para o modelo com Solicitação de Visita, e vice-versa. Essa ação dependerá do campo enable_rex enviado.

Se já foi tentado marcar ou desmarcar e, por algum motivo, o processo falhou, pode-se executar este endpoint para tentar marcá-lo novamente.

Nos ambientes de stage e produção, os parâmetros para fazer a chamada são os seguintes:

Nota: é importante fazer a chamada com o id de vendedor de teste e adicionar como queryParam scope=stage.

Ambiente de stage:

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

Ambiente de produção:

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 ítems marcados/desmarcados:

[
    
        "MLC123",
        "MLC321"

]

APIs

Notificação de leads de agenda

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

Para isso, é necessário acessar o aplicativo que recebe todos os leads e habilitar esse filtro.

O callback URL definido para receber as notificações receberá o conteúdo no seguinte formato:

{
  "_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 fazer a chamada à API para consultá-lo:

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

Para mais detalhes, consulte a documentação na seção VIS Leads

Por fim, ao consultar o Lead, será possível obter o ID da agenda associada através do campo external_id. Com ele, será possível consultar a agenda e seu estado na seção Obtenção de detalhes da agenda

Para os integradores que possuem o campo “notification_url” definido em sua configuração e ativaram o filtro “Visit Request” no tópico “VIS Leads”, a notificação de agenda será recebida tanto por nossos sistemas quanto na URL de callback de notificações, ou seja, de forma duplicada.

Se desejar receber notificações apenas pelo tópico “VIS Leads”, é necessário 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 essa configuração, acesse a seção Atualizar configuração

Visita

Gerar Agenda

Para simular uma agenda a partir do portal do Mercado Livre no ambiente de Stage, utilize a seguinte URL:

Ambiente de Stage:

https://www.mercadolibre.cl/agendar/visita-inmuebles/{itemId}?scope=stage

É importante destacar que essa URL deve ser usada 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, ou seja, não devem ser utilizados dados produtivos.

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

{itemId}

Esse parâmetro representa o ID da publicação. Exemplo: MLC916101223.

Obtenção de detalhes da agenda

Ambiente de Stage:

curl --location --request GET 
'https://api.mercadolibre.com/vis-transactions-hub/{providerId}/entities/schedules/{scheduleId}?scope=stage' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Nota: É importante realizar a requisição com o ID de vendedor de teste e adicionar o parâmetro de query scope=stage.

Ambiente de Produção:

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

Em ambos os casos, o parâmetro para realizar a chamada é:

{scheduleId}

Esse parâmetro representa o ID da agenda a ser consultada.
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"}],
 }

Os respectivos tipos de dados são:

Atualização de status da agenda

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

Ambiente de produção:

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 para a visita. O objetivo de utilizar este estado é evitar o processo de expiração das agendas, conforme explicado na seção Agenda expirada. Este estado é utilizado quando um seller usa algum canal de contato como Whatsapp, Call para contatar o buyer. O processo é automatizado pela Mercado Livre para detectar intenções de contato a partir do Painel de Pessoas Interessadas, Emails e Whatsapp com o buyer.

scheduling_canceled

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

(**) Estas razões são usadas para indicar as agendas que foram canceladas pelos seguintes motivos:

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

Vale ressaltar que essas razões são de uso interno apenas, portanto não devem ser usadas diretamente nas requisições.

Como essas razões são automáticas e internas, o status de 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.

Visita realizada

Como indicado anteriormente, quando uma agenda não é gerida, pergunta-se ao comprador se ele conseguiu ou não visitar a propriedade. Caso ele informe que conseguiu visitar a propriedade, a agenda passará para Visita Realizada, e junto com isso, indicamos a seguinte razão de por que uma agenda pode ser completada pelo comprador:

Agenda expirada (processo automático interno)

O sistema possui um processo automático que se encarrega de expirar todas as agendas que não foram geridas e estão no estado de "agendas criadas". Essa ação é executada após 3 dias consecutivos desde a data de intenção do comprador de visitar a propriedade.
Exemplo: o comprador 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 pela manhã, se a agenda continuar sem ser gerida, ela será expirada. As agendas criadas que são expiradas ficam com a seguinte condição:

Como essa é uma razão automática e interna, o status 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. O objetivo é que não sejam exibidas unidades na publicação que não estão disponíveis e, portanto, não gerem novos agendamentos. Caso fiquem disponíveis novamente, poderão 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 através do campo units no corpo da requisição.

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

Nota: É importante fazer a chamada com o id do seller de teste e inserir como queryParam scope=stage.

Ambiente de produção:

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

Em ambos casos 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 continuação se detalha os valores de status_code e status_name.

A continuação se detalha o dominio do atributo operation: