Developers

Documentação do Mercado Livre

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

Última atualização em 16/02/2024

Gestiona paquetes Inmuebles

Para publicar un anuncio en inmuebles, el vendedor debe haber contratado un paquete de publicación con Mercado Libre. Esta contratación se realiza directamente a través del equipo comercial. Una vez que el paquete es asignado, tanto el vendedor como el integrador están listos para publicar a través de la API o de nuestra plataforma. El tipo de paquete está representado en el campo listing_type de la publicación.

Nota:

Para realizar pruebas, deberás enviar el usuario de prueba al canal de soporte para que sea activado como real estate (inmobiliaria) y asignado a un paquete de publicación.

Tipos de Paquete

Hay 2 tipos de paquetes:
- Paquete de publicación - obligatorio para que el vendedor pueda realizar publicaciones. Este es el paquete Plata (silver), o sea, listing_type = silver.
- Paquete destacado - este paquete es opcional; el vendedor lo utiliza para aumentar la exposición de sus publicaciones. Puede ser Oro (listing_type = gold) u Oro Premium (listing_type = gold_premium).
Estos dos paquetes ofrecen cupos que se consumen con cada anuncio publicado (en el caso de un paquete de publicación) y cada vez que se realiza una actualización / destaque (en el caso de un paquete destacado). Es posible hacer upgrade y downgrade de la publicación y por este motivo debes pasar la opción para el seller.
Actualmente, cada usuario debe contratar los paquetes de publicaciones y destacados a través de un ejecutivo de cuentas de Mercado Libre. Esta acción no es posible a través de la API.
El listing_type utilizado para publicar un anuncio siempre será el más bajo: Plata, y, en caso de querer destacar la publicación, será necesario actualizarla con el listing_type deseado (con lo cual se consume una cuota en el paquete destacado).
Recuerda que en las llamadas GET al recurso de API classifieds_promotion_packs, puedes usar el parámetro package_content (tipo de paquete) para saber qué paquete quieres consultar:

Parámetro	Obligatorio	Default	Tipo	Valores
package_content	No	publications	String	tipo de paquete: publications: paquetes de publicación. upgrades: paquetes destacados. developments: paquetes de emprendimientos inmobiliarios. ALL: devuelve todos los paquetes disponibles.

Un cliente debe tener, obligatoriamente, un paquete de publicación para anunciar, pero los paquetes destacados son opcionales. El cliente también puede tener más de un paquete activo simultáneamente. Cada paquete activo tiene sus propias cuotas, fechas de vencimiento, etc.
Para saber cómo enviar una publicación, visita la página Publicación de Inmuebles, y recuerda: el anuncio debe ser primero enviado y publicado con un paquete de publicación, para después actualizarlo como paquete destacado, según se explica más adelante en esta página.

Consultar paquetes por categoría

Para consultar los paquetes disponibles para las categorías de clasificados, primero es necesario saber qué categoría será utilizada y de qué sitio. Por ejemplo, en Brasil, la categoría de inmuebles es MLA1459.

Llamada:

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

Ejemplo:

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

Respuesta:

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

Consultar paquetes de publicaciones contratados por un usuario

Esta consulta es importante, pues a través de ella es posible saber qué paquetes tiene un cliente y cuál es la cantidad de anuncios disponibles en cada uno, ingresando el id del usuario (cliente), el tipo de paquete (package content) y el token. A continuación, presentamos un ejemplo de llamada.

Llamada:

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

Ejemplo:

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

Respuesta:

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

Presta atención al campo status = active; a través de él solo es posible verificar los planes que todavía están activos. A través del package_content, es posible verificar si el paquete es de publicación (publications) o destacado (upgrades). Finalmente, a través del campo remaining_listings, es posible saber cuántas publicaciones el cliente todavía tiene disponibles. Esto es importante, ya que verás en tu sistema cuántos paquetes tiene el cliente y el número de anuncios que le quedan para publicar y destacar, antes de enviar una publicación a Mercado Libre.
Puedes utilizar las informaciones de status y package_content para filtrar los paquetes.

Ejemplo:

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

Descripción de recursos

Atributo	Descripción
id	Identificador exclusivo del paquete.
user_id	ID único del usuario que contrató el paquete.
category_id	Categoría del paquete.
descripción	Nombre del paquete.
package_type	Detalles del paquete.
status	Los valores posibles del estado del paquete son: activo: el usuario puede utilizar este paquete para publicar. Se descontará una available_listing cuando lo haga. pendiente: el paquete aún no está activo. finalizado: paquete expirado.
date_created	Fecha de creación del paquete.
date_start	Fecha de activación del paquete.<./td>
date_expires	Fecha de expiración del paquete en que expiran los items publicados con ese paquete.
date_stopped	Fecha de finalización del paquete.
last_updated	Última actualización del paquete.
engagement_type	Los valores posibles son: ninguno (none): El paquete se contrató por única vez. -recontratación (re-engagement): Cuando el paquete expira, se contratará nuevamente de forma automática un package_type similar.
charge_id	ID único del cargo generado durante la contratación del paquete.
listing_details	Información detallada sobre tipos y disponibilidad de publicaciones.
listing_type_id	listing_type asociado con el paquete.
available_listings	Cantidad de publicaciones que el usuario obtiene con el paquete.
used_listings	publicaciones ya utilizadas.
remaining_listings	Publicaciones restantes disponibles.

Verificar si un usuario tiene un listing_type específico disponible

Esta es una forma más rápida de saber si el usuario cuenta con un 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

Actualizar una publicación (destacar)

Para destacar una publicación, tendrás que realizar el siguiente posteo. Recuerda que para poder realizar esta acción el usuario debe haber contratado previamente un paquete destacado.

Llamada:

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

Ejemplo:

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

En el ejemplo anterior, la publicación está siendo actualizado al listing type = gold_premium (Oro Premium). Recuerda también que no se genera ningún tipo de cobro al realizar esta llamada y que, en caso de deshacerse la actualización, la cuota destacada vuelve a quedar disponible. Tampoco es posible destacar una publicación sin que se haya contratado por lo menos un paquete destacado.

Nota:

- Paquetes Mixtos: deberá consultar el paquete de publicación que posee el user , de esta forma podrá verificar el listing type de los cupos para poder publicar. Tenga en cuenta que los paquetes MIXTOS para publicar (con cupos gold, gold premium y silver) no podrán utilizarse para destacar.
- Delay de actualización de Api de paquetes: los cupos pueden tardar unos minutos en liberarse, si el integrador finaliza los ítems y los vuelve a levantar o bien hace downgrade de todo y vuelve a hacer upgrade a los pocos minutos, es posible que los cupos no se le liberen para ese momento por lo que estaría perdiendo cupos.

Tiempo de vigencia de la publicación

Importante:

Esta condición aplica para departamentos y casas, sea alquiler o venta, publicado por usuarios profesionales (user_type: real_estate_agency).
A partir del día 14 de febrero se ajusta el periodo de ciclo de vida para publicaciones nuevas de MLA en venta de 180 a 270 días.

Existe un tiempo máximo de ciclo de vida del ítem. Es decir, para que un ítem esté publicado dependerá de dos condiciones principales:

Que tenga cupo activo del paquete de publicación correspondiente;
Que esté dentro del ciclo de vida esperado.

Para casas y departamentos en Venta la API finalizará el ítem luego de 180 días de publicados.

Departamento en Venta - Category ID: "MLC157522"
Casa en Venta - Category ID: "MLC157520"

Para casas y departamentos en alquiler, la API finalizará el ítem luego de 45 días de publicados. (Solo aplica alquiler, no aplica para alquiler temporal).

Departamento en alquiler - Category ID: MLC183186
Casa en alquiler - Category ID: MLC183184

Estas 2 últimas condiciones del ciclo de vida aplican solo para MLC.

Significado de los parámetros de tiempo de ciclo de vida del ítem para departamentos y casas:

start_time: la API lo define al momento de crear el item.

stop_time: la API lo define al momento de crear el ítem según la categoría (Ya sea venta o arriendo).

expiration_time: la API lo define al momento de crear el ítem de acuerdo a la duración del promotion pack. (Pack de publicaciones activo que tenga).

Cuando el ítem llegue al stop_time, la API finalizara el ítem, el estado del ítem pasa de active a closed con sub status expired.
Cuando el paquete está activo y cayó el ítem por closed/sub_status: expired, puede ser porque llego el ciclo de vida del ítem al final. El integrador puede revisar el start_time del ítem para confirmar o no eso.

Ejemplo:

Un ítem Departamento en Venta (Categoria MLC157522) que fue publicado con:

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

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

expiration_time: "2022-02-01T00:06:15.000Z", (vencimiento del paquete de publicaciones mensual),

Fue publicado el 01/01/2022 y se mantendrá activo mientras el paquete de publicaciones esté activo y esté dentro del ciclo de vida (ciclo de vida de 180 días por ser venta). Llegado el 01/06/2022 el ítem se finalizará.

Siguiente: Publica inmuebles