Variações

No Mercado Livre, uma publicação de imóvel pode ter variações, ou seja, a mesma publicação é apresentada com opções diferentes em atributos como área útil, número de quartos ou banheiros. Isso permite ao vendedor mostrar uma unidade em construção ou a construir com diversas alternativas, chamadas variações. Cada variação detalha uma possível unidade a construir, incluindo suas características, plantas e outros detalhes.

Essas variações são apresentadas apenas para categorias e países específicos; para a Argentina é Empreendimentos (MLA401806), assim como para Uruguai (MLU455673); para o Chile é a categoria de Projetos (MLC157523); para o México é a categoria de Empreendimentos (MLM170376).

Ao consultar essas categorias, por exemplo para a Argentina, com o seguinte comando curl:

curl --location 'https://api.mercadolibre.com/categories/MLA401806' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	String	Não	Token gerado no ponto 4.3 do guia
CATEGORY_ID	String	Não	ID da categoria a consultar

Na resposta obtida, você encontrará o atributo attribute_types com o valor variations, o que indica que nessa categoria você poderá publicar imóveis com variações.

Exemplo de resposta:

{
    "id": "MLA401806",
    "name": "Emprendimientos",
       "path_from_root": [
        {
            "id": "MLA1459",
            "name": "Inmuebles"
        },
        {
            "id": "MLA1472",
            "name": "Departamentos"
        },
        {
            "id": "MLA1474",
            "name": "Venta"
        },
        {
            "id": "MLA401806",
            "name": "Emprendimientos"
        }
    ],
    "children_categories": [],
    "attribute_types": "variations"
    ...
}

Se desejar saber mais sobre categorias, consulte a seção de categorias.

Publique imóveis com variações

Para publicar imóveis com variações com seu usuário de teste, considere o seguinte:

1. Privilégios e pacotes de Desenvolvimento: É necessário contar com alguns privilégios e ter um pacote de desenvolvimento. Para isso, envie o formulário de suporte, selecionando a opção “Privilégios e pacote de desenvolvimento”, informando o ID do seu usuário para solicitar a atribuição desses privilégios para esse tipo de publicação.

2. Consulta de atributos com variações: Para publicações com variações, é imprescindível utilizar o guia de atributos e o guia de localização de imóveis. Esses materiais detalham os parâmetros necessários e as variações aplicáveis à categoria da sua publicação.

Por exemplo, se você deseja criar uma publicação na Argentina (MLA) para Apartamentos à venda dentro da categoria de empreendimentos, utilize a categoria MLA401806. Para verificar os atributos necessários, use o comando a seguir.

curl --location 'https://api.mercadolibre.com/categories/MLA401806/attributes' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Você obterá uma resposta que inclui os atributos obrigatórios e aqueles que permitem variações. Esses atributos são identificados pela propriedade "allow_variations": true, que indica quais atributos podem ter variações; não se esqueça também dos atributos obrigatórios.

{
  "id": "BEDROOMS",
  "name": "Dormitorios",
  "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 principales del modelo"
},
{
  "id": "FULL_BATHROOMS",
  "name": "Baños",
  "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 principales del modelo"
}

Com os atributos obrigatórios e com variações identificados para sua publicação, monte o JSON. Inclua os atributos que variam no array attribute_combinations e os atributos comuns no array attributes. Siga o exemplo abaixo.

{
  "listing_type_id": "gold_premium",
  "title": "Item de prueba de variations",
  "available_quantity": 4,
  "category_id": "MLA157523",
  "currency_id": "CLP",
  "condition": "new",
  "site_id": "MLA",
  "price": 100000000,
  "location": {
    "address_line": "H-20, La Estrella, O'Higgins",
    "zip_code": "",
    "neighborhood": { "id": "", "name": "" },
    "city": { "id": "TUxDQ0xBWmE0Y2Zm", "name": "Buenos aires" },
    "state": { "id": "TUxDUE9IUzFjODg", "name": "Libertador B. O'Higgins" },
    "country": { "id": "AR", "name": "Argentina" },
    "latitude": -34.2065985,
    "longitude": -71.6742634
  },
  "attributes": [
    { "id": "POSSESSION_STATUS", "value_id": "242414" },
    { "id": "PROPERTY_CODE", "value_name": "COD123456" },
    { "id": "MODEL_NAME", "value_name": "Modelo XYZ" },
    { "id": "DEVELOPMENT_NAME", "value_name": "Desarrollo ABC" },
    { "id": "COVERED_AREA", "value_name": "60 m2" },
    { "id": "UNIT_NAME", "value_name": "Unidad 101" },
    { "id": "BALCONY_AREA", "value_name": "5 m2" },
    { "id": "UNIT_FLOOR", "value_name": "3" },
    { "id": "FACING", "value_name": "N" }
  ],
  "variations": [
    {
      "attribute_combinations": [
        { "id": "TOTAL_AREA", "value_name": "60 m²" },
        { "id": "PARKING_LOTS", "value_name": "1" },
        { "id": "BEDROOMS", "value_name": "3" },
        { "id": "FULL_BATHROOMS", "value_name": "1" }
      ],
      "price": 100000000,
      "available_quantity": 4,
      "sold_quantity": 0
    },
    {
      "attribute_combinations": [
        { "id": "TOTAL_AREA", "value_name": "80 m²" },
        { "id": "PARKING_LOTS", "value_name": "2" },
        { "id": "BEDROOMS", "value_name": "4" },
        { "id": "FULL_BATHROOMS", "value_name": "3" }
      ],
      "price": 105000000,
      "available_quantity": 10,
      "sold_quantity": 0
    }
  ]
}

Você receberá uma resposta semelhante à que seria obtida ao publicar um item. Ela pode ser consultada no guia de publicação de Imóveis, mas neste caso a resposta incluirá alguns parâmetros específicos para variações, explicados a seguir:

Parâmetro	Tipo	Descrição
variations	Array	Apresenta um ID adicional, além do ID de publicação, para cada variação publicada, incluindo todas as informações específicas de cada variação.
id	String	Identificador único da variação.
attribute_combinations	String	Atributos mais detalhados e relacionados ao projeto/unidade.

Erros comuns ao publicar com variações

Existem alguns erros frequentes ao publicar um imóvel com variações. A seguir, listamos os mais comuns:

1. Omissão de atributos obrigatórios: Dada a diversidade de atributos disponíveis para publicação, é fácil omitir algum valor obrigatório. No entanto, a API possui validações para identificar os campos ausentes. Quando uma requisição é enviada de forma incorreta, a resposta retornará um erro 400 - Bad Request. No campo message, serão listados os atributos obrigatórios que não foram informados.

{
  "message": "Validation error",
  "error": "validation_error",
  "status": 400,
  "cause": [
    {
      "department": "items",
      "cause_id": 147,
      "type": "error",
      "code": "item.attributes.missing_required",
      "references": [ "item.attributes", "item.variations.attribute_combinations" ],
      "message": "Os atributos [POSSESSION_STATUS, PROPERTY_CODE, MODEL_NAME, DEVELOPMENT_NAME, COVERED_AREA, UNIT_NAME, BALCONY_AREA, UNIT_FLOOR, FACING] são obrigatórios para a categoria MLC157523 e canal marketplace. Verifique se o atributo está presente na lista de attributes ou em todas as attribute_combinations das variações."
    }
  ]
}

Para resolver, adicione no corpo da requisição os atributos mencionados na resposta.

2. Atributos posicionados incorretamente no JSON: É possível incluir atributos inválidos para uma determinada variação ou colocados na seção errada do JSON. Isso resultará em um erro retornado pela API, que fornecerá um feedback detalhado.

{
  "message": "Validation error",
  "error": "validation_error",
  "status": 400,
  "cause": [
    {
      "department": "items",
      "cause_id": 161,
      "type": "error",
      "code": "item.variations.variation_attributes.invalid",
      "references": [ "item.variations", "item.category_id" ],
      "message": "Os atributos [POSSESSION_STATUS] são inválidos nos atributos de variação para a categoria MLC157523 e canais [marketplace]. Verifique se eles existem e possuem a tag variation_attribute."
    }
  ]
}

Para resolver esse problema, consulte o recurso de /attributes. Lá você poderá verificar se um atributo específico possui a tag "allow_variations": true, o que indicará se ele deve ser incluído no parâmetro attribute_combinations ou se é um atributo geral da publicação.

3. Valor de atributo incorreto: Ao tentar definir os atributos por meio do endpoint /attributes, devem ser utilizados apenas os valores permitidos que são exibidos no recurso. Caso valores inválidos ou não autorizados sejam enviados, a API retornará uma resposta indicando o erro encontrado.

{
  "message": "Validation error",
  "error": "validation_error",
  "status": 400,
  "cause": [
    {
      "department": "structured-data",
      "cause_id": 3510,
      "type": "error",
      "code": "invalid.item.attribute.values",
      "references": [ "item.name" ],
      "message": "O atributo [FACING] não é válido. Valores enviados: [(null:NORTE)]"
    }
  ]
}

4. Cota não disponível: Ao solicitar a ativação de um pacote de desenvolvimento para projetos imobiliários que permite publicar imóveis com variações, é importante observar que esse pacote habilita a publicação apenas uma vez. Isso significa que, após publicar um imóvel com variações, não será possível repetir a operação até que o pacote seja reativado. Caso seja feita uma nova tentativa após o consumo do pacote, será retornada uma mensagem como a seguinte:

{
  "message": "Not available quota",
  "error": "bad_request",
  "status": 400,
  "cause": []
}

Consulte sua publicação com variações

Você pode consultar as variações do seu item fazendo a seguinte chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/items/$ITEM_ID?attributes=variations

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Lembre-se de usar o token gerado no ponto 4.3 do guia “Passos Rápidos para Publicar um Imóvel de Teste”.
ITEM_ID	String	Não	ID do item obtido como resposta ao publicar o imóvel.

Você receberá um JSON com as variações da sua publicação:

{
  "variations": [
    {
      "item_relations": [],
      "id": 18377456123,
      "attribute_combinations": [
        {
          "value_name": "1",
          "values": [{ "id": null, "name": "1", "struct": null }],
          "value_type": "number",
          "id": "FULL_BATHROOMS",
          "name": "Banheiros",
          "value_id": null
        },
        {
          "values": [{ "struct": null, "id": null, "name": "3" }],
          "value_type": "number",
          "id": "BEDROOMS",
          "name": "Dormitórios",
          "value_id": null,
          "value_name": "3"
        },
        {
          "id": "PARKING_LOTS",
          "name": "Vagas de estacionamento",
          "value_id": null,
          "value_name": "1",
          "values": [{ "id": null, "name": "1", "struct": null }],
          "value_type": "number"
        },
        {
          "values": [{
            "id": null,
            "name": "60 m²",
            "struct": { "number": 60, "unit": "m²" }
          }],
          "value_type": "number_unit",
          "id": "TOTAL_AREA",
          "name": "Área total",
          "value_id": null,
          "value_name": "60 m²"
        }
      ],
      "available_quantity": 4,
      "sold_quantity": 0,
      "seller_custom_field": null,
      "user_product_id": "MLCU3231182496",
      "price": 100000000,
      "sale_terms": [],
      "picture_ids": [],
      "catalog_product_id": null,
      "inventory_id": null
    }
  ]
}

A maioria dos atributos corresponde a uma publicação convencional — você pode consultá-los no guia de Publicação de Imóveis. Os demais são explicados a seguir:

Parâmetro	Tipo	Descrição
item_relations	Array	Lista de relações de itens.
id	Número	Identificador único da variação.
attribute_combinations	Array	Atributos detalhados relacionados ao projeto/unidade (ex.: dormitórios, banheiros).
value_name	String	Nome do valor de um atributo.
values	Array	Lista de detalhes do valor, incluindo nome e estrutura.
value_type	String	Tipo de valor (ex.: "number", "number_unit").
id	String	Identificador de um atributo (ex.: "FULL_BATHROOMS").
name	String	Nome de um atributo (ex.: "Banheiros").
value_id	Null	Identificador de um valor específico.
available_quantity	Número	Quantidade de unidades disponíveis para venda.
sold_quantity	Número	Quantidade de unidades já vendidas.
seller_custom_field	Null	Campo personalizado para o vendedor.
user_product_id	String	Identificador do produto do usuário.
price	Número	Preço do item.
sale_terms	Array	Termos de venda do item.
picture_ids	Array	Identificadores das imagens do item.
catalog_product_id	Null	Identificador do produto no catálogo.
inventory_id	Null	Identificador do item no inventário.

Se desejar consultar uma variação específica, você deve consultar o seu item e usar o recurso /variations, adicionando o ID da variação que deseja consultar, da seguinte forma:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/items/$ITEM_ID/variations/$Variation_id

Parâmetro	Tipo	Opcional	Valores
ACCESS_TOKEN	string	Não	Token gerado.
ITEM_ID	String	Não	ID do item obtido como resposta ao publicar o imóvel.
Variation_id	Número	Não	ID da variação a ser consultada.

Você receberá uma resposta igual à descrita anteriormente, porém contendo apenas a variação específica consultada.

Leituras recomendadas

• Atualize as variações do seu imóvel.
• Empreendimentos imobiliários
• Qualidade das publicações

Atualizações de versão

Esta seção resume o histórico de alterações do guia/API.

Data	Versão	Descrição
08/11/2025	1.0	Publicação inicial