Empreendimentos Imobiliários

Na Argentina, são chamados de “emprendimientos inmobiliarios residenciales”; no México, “desarrollos habitacionales”; no Chile, “proyectos de vivienda”; e no Brasil, “empreendimentos residenciais”. Geralmente compartilham características como planejamento de áreas de lazer (praças, piscinas, academias), controle de acesso, integração com o ambiente urbano ou suburbano e, em projetos modernos, foco em sustentabilidade e design comunitário.

No Mercado Livre, uma publicação de Empreendimento Imobiliário ou Projeto permite ao vendedor exibir uma unidade em construção ou a ser construída. Essa unidade pode oferecer diferentes alternativas, chamadas de variações. Cada variação especifica uma possível unidade a ser construída, incluindo suas características, plantas e outros detalhes.

Para saber mais, consulte o guia de variações.

Como publicar um Empreendimento Imobiliário?

Quais pacotes você precisa ter habilitado como vendedor?

• O vendedor deve ter habilitado um pacote do tipo desenvolvimento. Para saber como gerenciar seu pacote desse e de outros tipos, siga a documentação em Gerenciar Pacotes de Imóveis.
• É importante observar que você só poderá habilitar um pacote desse tipo nos países onde a experiência de Empreendimentos Imobiliários estiver disponível.

Quais categorias devo usar para publicar o empreendimento imobiliário?

• Consulte a seção especial dedicada às categorias desse tipo.

Quais características as fotos dos imóveis devem ter?

• Consulte a seção especial dedicada às fotografias desse tipo.

Em quais países está habilitada a publicação de empreendimentos imobiliários?

• Chile
• México
• Argentina
• Uruguai

Para saber mais, consulte o guia publique imóveis com variações.

Categorias de um Empreendimento Imobiliário

Como em qualquer outra publicação no Mercado Livre, é necessário associar essa publicação à categoria correspondente. Para isso, primeiro precisamos identificá-la dentro das categorias habilitadas no país onde a publicação será criada.

Listamos as categorias do país:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/sites/$SITE_ID/categories

Parâmetros

Como parâmetro de caminho (path parameter), é necessário incluir no endpoint o ID do país para listar as categorias. Os valores possíveis são:

• MLA
• MLC
• MLM
• MLU

Também será necessário um token de acesso válido para autorizar a consulta. Como resultado, são retornadas todas as categorias do país. Na Argentina, geralmente a categoria Imóveis é o valor MLA1459 (isso pode variar entre países e ao longo do tempo. Recomenda-se realizar a consulta para confirmar).

Em seguida, para obter a categoria correspondente a Empreendimentos Imobiliários, é necessário visualizar o detalhe da categoria pai e, em seguida, buscar dentro das categorias filhas (children_categories).

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/categories/MLA1459

Exemplo parcial de resposta:

{
  "id": "MLA1459",
  "name": "Imóveis",
  "picture": "...",
  "permalink": "https://www.mercadolibre.com.ar/c/inmuebles",
  "total_items_in_this_category": ...,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Imóveis"
    }
  ],
  "children_categories": [
    {
      "id": "MLA401805",
      "name": "Empreendimentos",
      "total_items_in_this_category": ..
    },
    ...
  ]
}

Identificado o ID da categoria filha correspondente, este é o valor que deve ser utilizado para publicar os imóveis com essas características de Empreendimentos Imobiliários.

Fotografias de uma publicação para um empreendimento imobiliário

A publicação de um empreendimento imobiliário possui variações. As imagens que detalham cada variação devem ser geradas e associadas a cada uma dessas variações. Para isso, essas imagens devem ser criadas utilizando o recurso pictures, enviando-as no mesmo POST dentro do array correspondente.

As fotografias cujo ID não estiver presente nas variações correspondentes não serão exibidas na página principal do empreendimento. No entanto, aquelas que tiverem o ID corretamente referenciado na variação serão visíveis tanto na descrição quanto na cotação.

A quantidade máxima de imagens permitidas para envio é determinada pela categoria, especificamente nos campos max_pictures_per_item e max_pictures_per_item_var.

Exemplo da categoria de empreendimento imobiliário para a Argentina, especificamente “Apartamentos”

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/categories/MLA401806

Exemplo parcial de resposta:

{
  ...
  "max_pictures_per_item": 80,
  "max_pictures_per_item_var": 6,
  ...
}

Publicação de empreendimentos imobiliários

Nesta seção, você encontrará como publicar empreendimentos imobiliários no Mercado Livre. Para um empreendimento ou desenvolvimento imobiliário, é necessário pelo menos uma variação. Todos os atributos e combinações de variações podem ser obtidos através do recurso /attributes da categoria correspondente.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/categories/$CATEGORY_ID/attributes

Exemplo parcial de resposta:

...{
  "id": "ROOMS",
  "name": "Ambientes",
  "tags": {
    "allow_variations": true,
    "required": true,
    "catalog_listing_required": true
  },
  "hierarchy": "ITEM",
  "relevance": 1,
  "value_type": "number",
  "value_max_length": 18,
  "attribute_group_id": "MAIN_CHARACTERISTICS_OF_MODEL",
  "attribute_group_name": "Características principais do modelo"
}...

Em uma publicação de imóveis, os atributos do empreendimento em si estão no campo attributes, sendo DEVELOPMENT_NAME o título do desenvolvimento. Cada unidade específica é detalhada em variations. Dentro de cada variação, attribute_combinations atua como chave primária, garantindo que não existam duas unidades com a mesma combinação de valores nesses atributos (por exemplo, UNIT_NAME geralmente é um identificador único).

Além disso, cada variação possui atributos específicos que variam de acordo com o empreendimento.

"title": "Casas financiadas em pesos e planos de poupança",
"category_id": "MLA401805",
"price":"XXXXXX",
"currency_id":"ARS"

Publicação

Considerando todas as observações mencionadas anteriormente e seguindo detalhadamente o guia de publicação de imóveis com variações, o imóvel é publicado com essas características utilizando a API de Itens, executando um POST para gerar a publicação.

O exemplo a seguir mostra um POST de um empreendimento imobiliário fictício.

curl --location --request POST 'https://api.mercadolibre.com/items' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Item de teste - não ofertar - teste - Domus 2222",
  "category_id": "MLA401806",
  "price": 157000,
  "currency_id": "USD",
  "available_quantity": 2,
  "buying_mode": "classified",
  "listing_type_id": "gold_premium",
  "condition": "new",
  "location": {
    ...
  },
  "description": {"plain_text": "Uma descrição de teste  \n"},
  "pictures": [
    {
      "id": "872895-MLA26491094940_122017",
      "url": "http://mla-s2-p.mlstatic.com/872895-MLA26491094940_122017-O.jpg",
      "secure_url": "https://mla-s2-p.mlstatic.com/872895-MLA26491094940_122017-O.jpg",
      "size": "500x312",
      "max_size": "1200x750",
      "quality": ""
    },
    {
      "id": "681776-MLA26491106096_122017",
      "url": "http://mla-s2-p.mlstatic.com/681776-MLA26491106096_122017-O.jpg",
      "secure_url": "https://mla-s2-p.mlstatic.com/681776-MLA26491106096_122017-O.jpg",
      "size": "500x236",
      "max_size": "1200x567",
      "quality": ""
    },
    ...
  ],
  ...
  "seller_address": {
    "comment": "",
    "address_line": "Av. Libertador 4189",
    "zip_code": "1636",
    "city": {
      "id": "TUxBQ1ZJQ2E3MTQz",
      "name": "Vicente López"
    },
    "state": {
      "id": "AR-B",
      "name": "Buenos Aires"
    },
    "country": {
      "id": "AR",
      "name": "Argentina"
    }
  },
  "attributes": [
    {
      "id": "AVAILABLE_PARKING_SLOTS",
      "name": "Vagas disponíveis",
      "value_id": null,
      "value_name": "82",
      "value_struct": null,
      "attribute_group_id": "ADDITIONAL_CHARACTERISTICS_OF_DEVELOPMENT",
      "attribute_group_name": "Características adicionais do empreendimento"
    },
    {
      "id": "HAS_LIFT",
      "name": "Elevador",
      "value_id": "242084",
      "value_name": "Não",
      "value_struct": null,
      "attribute_group_id": "ADDITIONAL_CHARACTERISTICS_OF_DEVELOPMENT",
      "attribute_group_name": "Características adicionais do empreendimento"
    },
    ...
  ],
  "variations": [
    {
      "price": 158000,
      "attribute_combinations": [
        { "id": "ROOMS", "name": "Ambientes", "value_id": null, "value_name": "2", "value_struct": null },
        { "id": "FULL_BATHROOMS", "name": "Banheiros", "value_id": null, "value_name": "1", "value_struct": null },
        { "id": "PARKING_LOTS", "name": "Vagas de garagem", "value_id": null, "value_name": "0", "value_struct": null },
        { "id": "BEDROOMS", "name": "Quartos", "value_id": null, "value_name": "1", "value_struct": null },
        ...
      ],
      "available_quantity": 1,
      "sold_quantity": 0,
      "sale_terms": [],
      "picture_ids": ["674837-MLA26491070000_122017"]
    },
    {
      "price": 161000,
      "attribute_combinations": [
        { "id": "ROOMS", "name": "Ambientes", "value_id": null, "value_name": "1", "value_struct": null },
        ...
      ],
      "available_quantity": 1,
      "picture_ids": ["913036-MLA26491092856_122017"]
    }
  ]
}'

Exemplo parcial de resposta:

{
  "id": "MLA843263657",
  "site_id": "MLA",
  "title": "Item De Prueba - No Ofertar - Test - Domus 2222",
  "subtitle": null,
  "seller_id": 534776711,
  "category_id": "MLA401806",
  "official_store_id": null,
  "price": 158000,
  "base_price": 158000,
  ...
  "condition": "new",
  "permalink": "http://departamento.mercadolibre.com.ar/MLA-843263657-item-de-prueba-no-ofertar-test-domus-2222-_JM",
  "pictures": [
    {
      "id": "872895-MLA26491094940_122017",
      "url": "http://mla-s1-p.mlstatic.com/872895-MLA26491094940_122017-O.jpg",
      "secure_url": "https://mla-s1-p.mlstatic.com/872895-MLA26491094940_122017-O.jpg",
      "size": "500x312",
      "max_size": "1200x750",
      "quality": ""
    },
    {
      "id": "681776-MLA26491106096_122017",
      "url": "http://mla-s1-p.mlstatic.com/681776-MLA26491106096_122017-O.jpg",
      "secure_url": "https://mla-s1-p.mlstatic.com/681776-MLA26491106096_122017-O.jpg",
      "size": "500x236",
      "max_size": "1200x567",
      "quality": ""
    },
    ...
  ],
  "video_id": null,
  "descriptions": [{ "id": "MLA843263657-2561842362" }],
  "accepts_mercadopago": false,
  "non_mercado_pago_payment_methods": [],
  "shipping": {...},
  "international_delivery_mode": "none",
  "seller_address": {
    "id": 1091410987,
    "comment": "",
    "address_line": "Test Address 123",
    "zip_code": "1414",
    "city": { "id": "", "name": "Palermo" },
    "state": { "id": "AR-C", "name": "Capital Federal" },
    "country": { "id": "AR", "name": "Argentina" },
    ...
  },
  "geolocation": { "latitude": -34.5101161, "longitude": -58.4765109 },
  "attributes": [
    {
      "id": "ITEM_CONDITION",
      "name": "Condición del ítem",
      "value_id": "2230284",
      "value_name": "Nuevo",
      "value_struct": null,
      "values": [{ "id": "2230284", "name": "Nuevo", "struct": null }],
      "attribute_group_id": "",
      "attribute_group_name": ""
    },
    {
      "id": "AVAILABLE_PARKING_SLOTS",
      "name": "Cocheras disponibles",
      "value_id": null,
      "value_name": "82",
      "value_struct": null,
      "values": [{ "id": null, "name": "82", "struct": null }],
      "attribute_group_id": "ADDITIONAL_CHARACTERISTICS_OF_DEVELOPMENT",
      "attribute_group_name": "Características adicionales del desarrollo"
    },
    ...
  ],
  "warnings": [
    {
      "department": "items",
      "cause_id": 314,
      "code": "item.price.dropped",
      "message": "Item price was changed by the lowest-price variation.",
      "references": ["item.price"]
    }
  ],
  "variations": [
    {
      "id": 52173477243,
      "attribute_combinations": [
        { "id": "ROOMS", "name": "Ambientes", "value_id": null, "value_name": "2", "value_struct": null, "values": [{ "id": null, "name": "2", "struct": null }] },
        { "id": "FULL_BATHROOMS", "name": "Baños", "value_id": null, "value_name": "1", "value_struct": null, "values": [{ "id": null, "name": "1", "struct": null }] },
        ...
      ],
      "price": 158000,
      "available_quantity": 1,
      "sold_quantity": 0,
      "sale_terms": [],
      "picture_ids": ["674837-MLA26491070000_122017"],
      ...
    },
    {
      "id": 52173477261,
      "attribute_combinations": [
        { "id": "ROOMS", "name": "Ambientes", "value_id": null, "value_name": "1", "value_struct": null, "values": [{ "id": null, "name": "1", "struct": null }] },
        ...
      ],
      "price": 161000,
      "available_quantity": 1,
      "sold_quantity": 0,
      "sale_terms": [],
      "picture_ids": ["913036-MLA26491092856_122017"],
      "seller_custom_field": null,
      "catalog_product_id": null,
      "attributes": [],
      "inventory_id": null,
      "item_relations": []
    }
  ],
  "thumbnail": "http://mla-s1-p.mlstatic.com/872895-MLA26491094940_122017-I.jpg",
  "secure_thumbnail": "https://mla-s1-p.mlstatic.com/872895-MLA26491094940_122017-I.jpg",
  "status": "active",
  "tags": ["test_item"],
  "catalog_listing": false
}

Gestão de Interessados / Contatos em Empreendimentos Imobiliários

A gestão das consultas de potenciais compradores para Empreendimentos Imobiliários segue o mesmo processo utilizado para outros tipos de imóveis. Para obter mais detalhes, consulte o guia de Leads.

Assim como em outros imóveis, existem várias maneiras pelas quais o usuário comprador pode entrar em contato para obter mais informações sobre o imóvel. Por exemplo, no canto superior direito da galeria de imagens da publicação ou em cada um dos modelos do empreendimento.

Em todos os casos, um e-mail é enviado ao vendedor ou à imobiliária com informações semelhantes às seguintes:

Olá Imobiliária XYZ
Você recebeu uma pergunta no Mercado Livre na publicação MLA1111

"Olá, bom dia. Tenho interesse no empreendimento denominado Empreendimento Fictício, por favor entre em contato comigo. Obrigado!

Dados de contato:
Nome: [Nome do Comprador]
E-mail: seuemail@dominio.com
Telefone: 01-1111-1111"

Esse e-mail será acompanhado por uma notificação para o vendedor ou imobiliária na conta do usuário. No perfil, será possível visualizar todas essas notificações no canto superior direito.

Eventualmente, será permitido que usuários não registrados possam solicitar informações sobre o empreendimento imobiliário por meio de um formulário de contato que os identifique. Nas publicações desse tipo, o formulário será semelhante ao seguinte:

É importante lembrar que o número de telefone pode não aparecer, pois não é um campo obrigatório no formulário de contato, e o usuário pode optar por fornecê-lo ou não.

Gestão de Cotações

O usuário comprador tem a possibilidade de solicitar uma cotação para obter informações sobre os detalhes e o valor do imóvel de interesse. Uma cotação ocorre quando o interessado realiza uma consulta em um anúncio do tipo “Empreendimento Imobiliário”.

O usuário escolhe a planta e a unidade (no caso de um empreendimento de apartamentos) e, a partir disso, pode visualizar o preço da unidade. Uma cotação é um documento que contém informações do vendedor, do imóvel e do comprador no momento em que é criada.

Quando o usuário solicita uma cotação, as informações do item ou da publicação do imóvel são congeladas e mantidas para garantir o preço vigente no momento da cotação. Em alguns processos ou casos de uso, o integrador deve enviar a variável caller.type para identificar quem é o gerador da ação. Pode ser um vendedor ou um usuário. Geralmente, em aplicativos de lançamentos, será o vendedor.

Cotações Mercado Livre — Como uma “quotation” é notificada à sua aplicação?

Para receber notificações em tempo real sobre a criação de cotações (quotations), você deve se registrar em nosso feed de quotations. Esse evento é originado no Mercado Livre.

Para isso, acesse o gerenciador de aplicações onde sua aplicação foi criada (Argentina, Brasil, Chile, México, Colômbia, Uruguai, Peru, Equador e Venezuela), faça login com o usuário que configurou a aplicação e edite as configurações. Na seção “Tópicos”, você encontrará subseções nas quais poderá ativar as notificações.

Na parte inferior, será habilitado um campo para definir uma Callback URL: insira a URL pública do domínio onde deseja receber todas as notificações do Mercado Livre.

Se precisar de mais informações sobre notificações, consulte este link.

Buscar uma cotação

Ao consultar os dados do lead , a resposta incluirá o campo "external_id", que corresponde ao identificador da cotação. Utilize o valor de "external_id" como QUOTATION_ID na seguinte chamada para obter os detalhes da cotação:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/quotations/$QUOTATION_ID?caller.type=seller

Parâmetros

Exemplo de resposta:

{
  "id": 5992689,
  "user": {
    "id": 535115061,
    "nickname": "TESTIIU8DDRW",
    "registration_date": "2020-03-11T16:53:15Z",
    ...
  },
  "item": {
    "id": "MLA843263657",
    "site_id": "MLA",
    "title": "Item de Teste - Não Ofertar - Teste - Domus 2222",
    "price": 158000,
    ...
  },
  "variation": {...},
  "disclaimer": "Nota: As informações fornecidas ...",
  "created_at": "2020-03-11T17:01:10Z",
  "is_guest": false
}

Estrutura de resposta esperada:

Buscar uma cotação por ID do item

Para obter a quantidade de cotações que um item recebeu, execute o comando:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/quotations/items_ids?query=$ITEMID&caller.type=seller

Para consultar vários itens de uma só vez:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/quotations/items_ids?query=ItemId1,Itemid2,Itemid3&caller.type=seller

Parâmetros

Exemplo de resposta:

{
  "paging": {"total": 3, "offset": 0, "limit": 10},
  "results": ["MLA843263657"]
}

Consultar relatório de cotações por vendedor

Para obter a quantidade de cotações recebidas por um vendedor, utilize o ID do seller com o seguinte comando:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/quotations/report?seller.id=$SELLER.ID

Parâmetros

Exemplo de resposta:

{
  "seller_id": 534776711,
  "total": 8,
  "results": [{ "date": "2020-03-11T00:00:00Z", "total": 1 }]
}

Excluir uma cotação

Você pode excluir uma cotação utilizando o seguinte comando PUT da API:

curl -X PUT \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"delete": true}' \
  "https://api.mercadolibre.com/quotations/$QUOTATION_ID?caller.type=seller"

Parâmetros

Você receberá uma resposta com status 200 OK.

Leituras recomendadas

• Variações
• Leads

Atualizações de versão

Esta seção fornece informações sobre as atualizações da API, incluindo:

Histórico de alterações