Gerenciamento de pacotes de imóveis

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 14/03/2023

Gerenciamento de pacotes de imóveis

Em imóveis, para publicar um anúncio, o vendedor precisa ter um pacote de publicação contratado com o Mercado Livre. Esta contratação é feita diretamente com a equipe comercial. Com o pacote alocado, tanto o vendedor (quanto o integrador) já estão prontos para publicar, seja via API, ou pela nossa plataforma. O tipo de pacote é representado pelo campo listing_type do anúncio.

Nota:

Para realizar testes, você deverá encaminhar o usuário de teste para o canal de suporte para este ser ativado como real estate (imobiliária) e alocado a um pacote de publicação.

Tipos de pacote

Existem 2 tipos de pacotes:
Pacote de publicação: obrigatório para que o vendedor possa publicar anúncios. Este pacote é o prata (silver), ou seja, listing_type = silver.
Pacote de destaque: este pacote é opcional, e o vendedor utiliza este pacote para aumentar a exposição dos seus anúncios. Pode ser o ouro (listing_type = gold) e o diamante (listing_type = gold_premium).
Ambos os pacotes contém quotas que são consumidas a cada publicação de anúncio (no caso de um pacote de publicação) e a cada vez que se realiza um upgrade / destaque (no caso de um pacote de destaque). É possível fazer upgrade e downgrade do anuncio e por este motivo você deve passar a opção para o vendedor.
Atualmente, todos os pacotes de publicações e pacotes de destaques devem ser contratados por um executivo de contas do Mercado Livre para cada usuário. Esta ação não é possível via API.
O listing_type usado para publicar um anúncio será sempre o mais baixo: "prata", e, se quiser destacar o anúncio, deverá atualizar o anúncio com o listing_type desejado (consumindo uma quota no pacote de destaque).
Lembre-se que nas chamadas GET ao recurso de API classifieds_promotion_packs, você pode usar o parâmetro package_content (tipo de pacote) para saber qual pacote você quer consultar:

Parâmetro	Obrigatório	Default	Tipo	Valores
package_content	Não	publications	String	tipo do pacote: publications: pacotes de publicação. upgrades: pacotes de destaque. developments: pacotes de empreendimentos imobiliários. ALL: retorna todos os pacotes disponíveis.

Um cliente, obrigatoriamente, deve ter um pacote de publicação para anunciar, mas os pacotes de destaques são opcionais. O cliente também pode ter mais de um pacote ativo ao mesmo tempo. Cada pacote ativo tem suas próprias quotas, datas de vencimento, etc..
Para saber como enviar uma publicação, visite a página Publicação de Imóveis, e lembre-se: o anúncio primeiramente deve ser enviado e publicado com um pacote de publicação, para posteriormente realizar um upgrade para um pacote de destaque, conforme explicado mais abaixo nesta página.

Pesquisar pacotes por categoria

Para consultar os pacotes disponíveis para as categorias de classificados, deve-se primeiramente saber qual a categoria a ser utilizada, de qual site. Por exemplo, para Brasil, categoria de imóveis é MLA1459.

Chamada:

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

Exemplo:

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

Resposta:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' [
  {
    "id": "IPILIMP30DF",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete Ilimitado propiedades",
    "price": 2804,
    "package_type": "unlimited",
    "package_content": "publications",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCGE",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100000
      }
    ]
  },
  {
    "id": "IPILIMP90DF",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete Ilimitado propiedades",
    "price": 7559,
    "package_type": "unlimited",
    "package_content": "publications",
    "duration": 90,
    "status": "active",
    "charge_type_id": "CCGJ",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100000
      }
    ]
  },
  {
    "id": "IPILIMP180DF",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete Ilimitado propiedades",
    "price": 14286,
    "package_type": "unlimited",
    "package_content": "publications",
    "duration": 180,
    "status": "active",
    "charge_type_id": "CCGO",
    "max_upgrades": 300,
    "quota_type": "reusable",
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100000
      }
    ]
  }
]

Pesquisar pacotes de anúncios contratados por um usuário

Esta consulta é importante, pois através dela você pode saber quais os pacotes um cliente tem e qual a quantidade de anúncios disponíveis em cada um, informando o id do usuário (cliente), o tipo de pacote (package content) e o token. Veja abaixo um exemplo de chamada. Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/users/526561644/classifieds_promotion_packs?package_content=ALL

Resposta:

[
    {
     "id": 754985,
     "user_id": "135146148",
     "promotion_pack_id": "MPAB",
     "category_id": "MLU1743",
     "description": "Paquete 15 Básico",
     "package_type": "rotary",
     "package_content": "publications",
     "status": "active",
     "date_created": "2013-05-23T15:34:48.498-04:00",
     "date_start": "2013-05-23T15:34:47.544-04:00",
     "date_expires": "2013-06-22T15:34:47.544-04:00",
     "date_stopped": null,
     "last_updated": "2013-05-23T15:35:48.211-04:00",
     "engagement_type": "none",
     "charge_id": 822129921,
     "remaining_listings": 15,
     "used_listings": 0,
     "listing_details": [
        {
           "listing_type_id": "silver",
           "available_listings": 15,
           "used_listings": 0,
           "remaining_listings": 15
        }
     ]
    }
]

Atente-se que pelo campo status = active, você pode verificar apenas os planos que ainda estão ativos. Através do package_content, você descobre se o pacote é de publicação (publications) ou destaque (upgrades). Por fim, através do campo remaining_listings, você consegue saber quantas publicações o cliente ainda tem direito. Isso é importante, porque você pode mostrar em seu sistema quantos pacotes o cliente tem, e qual a quantidade de anúncios restantes, para publicar e destacar, antes de enviar uma publicação para o Mercado Livre.
Pode utilizar as informações de status e package_content para filtrar os pacotes.

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/405484761/classifieds_promotion_packs?package_content=upgrades&status=active

Respuesta:

[
    {
        "id": 2942184,
        "user_id": "405484761",
        "promotion_pack_id": "IPUPGGP306",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "30 Destaques Oro Premium",
        "package_type": "rotary",
        "status": "active",
        "date_created": "2020-02-20T10:00:33.386-04:00",
        "date_start": "2020-02-20T10:00:33.303-04:00",
        "date_expires": "2020-08-20T10:00:33.303-04:00",
        "date_stopped": null,
        "last_updated": "2020-02-20T10:00:33.386-04:00",
        "engagement_type": "re-engagement",
        "package_content": "upgrades",
        "charge_id": null,
        "bonus_id": null,
        "remaining_listings": 30,
        "used_listings": 0,
        "quota_type": "reusable",
        "next_promotion_pack_id": null,
        "parent_promotion_pack_id": null,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 30,
                "used_listings": 0,
                "remaining_listings": 30
            }
        ]
    },
    {
        "id": 2938710,
        "user_id": "405484761",
        "promotion_pack_id": "IPUPGG606",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "60 Destaques Oro",
        "package_type": "rotary",
        "status": "active",
        "date_created": "2020-02-17T13:37:37.692-04:00",
        "date_start": "2020-02-17T13:37:37.674-04:00",
        "date_expires": "2020-08-17T13:37:37.674-04:00",
        "date_stopped": null,
        "last_updated": "2020-02-17T14:00:26.016-04:00",
        "engagement_type": "re-engagement",
        "package_content": "upgrades",
        "charge_id": 5931516720,
        "bonus_id": null,
        "remaining_listings": 60,
        "used_listings": 0,
        "quota_type": "reusable",
        "next_promotion_pack_id": null,
        "parent_promotion_pack_id": null,
        "listing_details": [
            {
                "listing_type_id": "gold",
                "available_listings": 60,
                "used_listings": 0,
                "remaining_listings": 60
            }
        ]
    }
]

Descrição de recursos

Atributo	Descrição
id	Identificador exclusivo do pacote.
id	Identificador exclusivo do pacote.
user_id	ID exclusivo do usuário contratante do pacote.
category_id	Categoria do pacote.
descrição	Nome do pacote.
package_type	Detalhes do pacote.
status	Os valores possíveis de status do pacote são: active: o usuário pode usar esse pacote para publicar. Quando ele fizer a publicação, uma available_listing será descontada. pending: o pacote ainda não está ativo. finished: pacote expirado.
date_created	Data de criação do pacote.
date_start	Data de ativação do pacote<./td>
date_expires	Data de expiração do pacote em que expiram os ítems anunciados.
date_stopped	Data de finalização do pacote.
last_updated	Última atualização do pacote.
engagement_type	Os valores possíveis são: - none: o pacote é utlizado apenas pelo tempo contratado sem renovação automática. - re-engagement: quando o pacote expira e se contrata novamente automaticamente um package_type similar.
charge_id	ID exclusivo da cobrança gerada durante a contratação do pacote.
listing_details	Informações detalhadas sobre tipos de publicações e disponibilidade.
listing_type_id	listing_type associado ao pacote.
available_listings	Quantidade de publicações obtidas pelo usuário com o pacote.
used_listings	Publicações já enviadas.
remaining_listings	Publicações restantes disponíveis.

Conferir se um usuário tem um listing_type específico disponível

Esta é uma maneira mais rápida para saber se o usuário possui um listing_type específico.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/users/$USER_ID/classifieds_promotion_packs/$LISTING_TYPE?categoryId=$CATEGORY_ID

Realizar o upgrade de um anúncio (destacar)

Para destacar um anúncio, você deverá realizar a seguinte postagem; lembre que, para poder realizar esta ação, o usuário deve ter contratado previamente um pacote destaque. Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/items/$ITEM_ID/listing_type

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/items/MLA111111111/listing_type' -d '{"id":"listing_type"}'

No exemplo acima, o anúncio está fazendo o upgrade para o listing type = gold_premium (diamante). Lembre-se também que não é gerado nenhum tipo de cobrança ao realizar esta chamada, e que caso o upgrade seja desfeito, a quota de destaque volta a ficar disponível.
Também não é possível destacar uma publicação sem a contratação de pelo menos um pacote de destaques.

Nota:

- Pacotes Mixtos: deverá consultar o pacote de publicação que o usuário possui, desta forma poderá verificar o listing type das cotas para poder anunciar. Leve em conta que os pacotes MIXTOS para anunciar (com cotas gold, gold premium e silver) não podem ser utilizados para destacar.
- Atraso de atualização da Api de pacotes: as cotas podem demorar alguns minutos para serem liberadas, se o desenvolvedor finaliza os itens e os publica novamente ou faz Downgrade de todo e volta a fazer upgrade aos poucos minutos.

Tempo de validade da publicação

Importante:

Esta condição se aplica aos apartamentos e casas, sejam para aluguel ou venda, publicados por usuários profissionais (user_type: real_estate_agency)

Existe um tempo máximo de ciclo de vida para o item. Ou seja, para que um item seja publicado, ele dependerá de duas condições principais:

Você tem uma cota ativa do pacote de publicação correspondente;
Que está dentro do ciclo de vida esperado.

Para casas e apartamentos à venda, a API finalizará o item após 180 dias da publicação.

Apartamento para venda - Category ID: MLC157522
Casa para venda Category ID: MLC157520

Para aluguel de casas e apartamentos, a API encerrará o item após 45 dias da publicação (só se aplica a aluguéis, não se aplica a aluguéis temporários).

Apartamento para aluguel - CategoryID: MLC183186
Casa para alugar - Category ID: MLC183184

Significado dos parâmetros de tempo de ciclo de vida do item para apartamentos e casas:

"start_time": a API o define ao criar o item

"stop_time":a API o define no momento da criação do item de acordo com a categoria (seja venda ou locação).

"expiration_time": a API define ao criar o item de acordo com a duração do pacote promocional. (Pacote de publicação ativo que você possui)

Quando o item chegue ao Stop_time, a API finaliza o item; O status do item muda de ativo para closed substatus expired.
Quando o pacote está ativo e o item caiu por Closed/Sub_status:expired, pode ser porque o ciclo de vida do item chegou ao fim. O integrador pode verificar o start_time do item para confirmar isso.

Exemplo:

Um ítem Apartamento em Venda (Categoria MLC157522) que foi publicado com:

start_time: "2022-01-01T00:06:15.000Z",

stop_time: "2022-06-01T00:06:15.000Z",

expiration_time: "2022-02-01T00:06:15.000Z",(vencimento do pacote de publicações mensal),

Foi publicado em 01/01/2022 e permanecerá activo enquanto o pacote de publicação estiver activo e dentro do ciclo de vida (ciclo de vida de 180 dias por ser uma venda). Em 01/06/2022, o item será encerrado.

Próximo: Publicação de Imóveis