Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 05/12/2023

Mercado Ads

Nota:
Esta funcionalidad está disponible solo para integradores autorizados.

Esta API te permite crear campañas de publicidad para promocionar anuncios (publicaciones con publicidad) en Mercado Libre con el fin de obtener más visitas y ventas. A través de Mercado Ads lograrás potenciar el rendimiento e incrementar ventas.


Límites de presupuesto

Antes de armar una campaña, conoce los límites de presupuesto. Cada usuario tiene asignado una inversión mínima y máxima en publicidad. Puedes elegir libremente tu inversión diaria dentro de este rango.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/budgets/limits?campaign_type=default

Respuesta:

{
       "campaign_type": "default",
       "minimum": 100,
       "maximum": 50000,
       "maximum_percentage": 30,
       "minimum_percentage": 0.5,
       "recommended_minimum": 500
   }
  • campaign_type: tipo de campaña.
  • minimum: monto mínimo de inversión publicitaria.
  • maximum: monto máximo de inversión publicitaria.
  • maximum_percentage: máximo porcentaje.
  • minimum_percentage: mínimo porcentaje.
  • recommended_minimum: mínimo recomendado.
Nota:
Los valores están expresados en la moneda local. El presupuesto deberá estar dentro de ese rango. Los valores de los límites son presupuestos válidos. Los límites pueden cambiar a lo largo del tiempo.

Crear una campaña

Todos los anuncios deben estar agrupados en una campaña, cuyo presupuesto será repartido entre todos los anuncios que estén dentro de ella.


Parámetros

  • Budget: (obligatorio) debe estar dentro de los límites de presupuesto de tu usuario.
  • Status: (opcional) tiene valor active por defecto.
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns
{
  "budget": 20,
  "status": "active"|"paused",
}

Respuesta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:31:11.897Z",
    "date_created": "2018-08-23T18:31:11.897Z"
}

Modificar una campaña

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID
{
  "status": "active"|"paused",
  "budget":225
}

Consultar una campaña

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID

Ejemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/223493019

Respuesta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:56:33.000Z",
    "date_created": "2018-08-23T04:00:00.000Z"
}

Buscar campañas por usuario

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=$USER_ID

Ejemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=123456

Respuesta:

{  
   "paging":{  
      "total":1,
      "offset":0,
      "limit":10
   },
   "results":[  
      {  
         "id":223703005,
         "name":"Campanha Principal",
         "user_id":301254033,
         "type":"default",
         "status":"active",
         "budget":225.0,
         "last_updated":"2018-08-24T04:00:00.000Z",
         "date_created":"2018-08-24T04:00:00.000Z"
      }
   ]
}

Métricas de campaña

Puedes consultar métricas de una campaña con un rango de fechas que no supere los 90 días.


Parámetros obligatorios

  • date_from: con formato aaaa-mm-dd, ejemplo 2018-08-01
  • date_to: con formato aaaa-mm-dd, ejemplo 2018-08-10
  • campaign_id: id de la campaña

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD

Respuesta:

{
  "id": 289823066,
  "clicks": 4315,
  "impressions": 532218,
  "ctr": 0.81,
  "cost": 26200.179999999993,
  "cpc": 6.07,
  "sold_quantity_direct": 237,
  "sold_quantity_indirect": 84,
  "sold_quantity_total": 321,
  "amount_direct": 182859.14,
  "amount_indirect": 74808.53,
  "amount_total": 257667.67,
  "advertising_fee": 10.17,
  "share": 10.89,
  "organic_sold_items_quantity": 2424,
  "sold_items_quantity_direct": 200,
  "sold_items_quantity_indirect": 77,
  "sold_items_conversion": 277
}

Campos de respuesta

  • id id de campaña.
  • clicks cantidad de clicks que recibió la campaña.
  • impressions cantidad de impresiones en el sitio que recibió la campaña.
  • ctr: click through rate, expresado en porcentaje, la división entre clicks e impressions.
  • cost: es el costo total de clicks del período, en moneda local.
  • cpc: el costo promedio de cada click, en moneda local.
  • sold_quantity_direct: cantidad de ventas directas.
  • sold_quantity_indirect: cantidad de ventas asistidas.
  • sold_quantity_total: cantidad de ventas en total.
  • amount_direct: suma del valor de las ventas directas obtenidas a través de tus Product Ads, en moneda local. Tienes una venta directa cuando un usuario hace clic en tu Product Ad y compra ese producto.
  • amount_indirect: suma del valor de las ventas asistidas obtenidas a través de tus Product Ads, en moneda local. Tienes una venta asistida cuando un usuario hace clic en tu Product Ad y compra otro de tus productos.
  • amount_total: suma del valor de las ventas obtenidas a través de tus Product Ads, en moneda local.
  • advertising_fee: expresado en porcentaje, la división entre inversión en publicidad sobre los ingresos obtenidos. cost / amount_total. Un valor más bajo implica un mejor rendimiento.
  • share: porcentaje de ventas por publicidad sobre ventas totales.
  • organic_sold_items_quantity: cantidad de ventas sin publicidad.
  • sold_items_quantity_direct: cantidad de ventas directas por publicidad.
  • sold_items_quantity_indirect: cantidad de ventas indirectas por publicidad.
  • sold_items_conversion: cantidad de ventas por publicidad.

Métricas de anuncios

Puedes consultar en un mismo request, implementando multiget hasta 50 Product Ads. También se deberá enviar un rango de fechas que no supere los 90 días.


Parámetros

  • date_from: campo requerido, con formato aaaa-mm-dd, ejemplo 2018-08-01.
  • date_to: campo requerido, con formato aaaa-mm-dd, ejemplo 2018-08-10.
  • campaign_id: campo requerido, id de la campaña.
  • ids: campo requerido, lista de hasta 50 item ids separados por coma, ejemplo MLA1234, MLA4321.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD&ids=$ITEM_ID_1,$ITEM_ID_2

Respuesta:

[{
  "id": "MLA1275028260",
  "clicks": 0,
  "impressions": 0,
  "cost": 0.0,
  "cost_usd": 0.0,
  "cpc": 0.0,
  "cpc_usd": 0.0,
  "ctr": 0.0,
  "sold_quantity_direct": 0,
  "sold_quantity_indirect": 0,
  "sold_quantity_total": 0,
  "amount_direct": 0.0,
  "amount_indirect": 0.0,
  "amount_total": 0.0,
  "amount_direct_usd": 0.0,
  "amount_indirect_usd": 0.0,
  "amount_total_usd": 0.0,
  "advertising_fee": 0.0,
  "organic_orders_quantity": 0,
  "share": 0.0,
  "organic_sold_items_quantity": 0,
  "sold_items_quantity_direct": 0,
  "sold_items_quantity_indirect": 0,
  "sold_items_conversion": 0
}]

Campos de la respuesta

  • id: id del anuncio.
  • impressions: cantidad de impresiones en el sitio que tuvo el Product Ad.
  • clicks: cantidad de clicks que recibió el Product Ad.
  • ctr: click through rate, expresado en porcentaje, la división entre clicks e impressions.
  • cost: es el costo total de clicks del período, en moneda local.
  • cpc: el costo promedio de cada click, en moneda local.
  • sold_quantity_direct: cantidad de unidades vendidas en ventas directas.
  • sold_quantity_indirect: cantidad de unidades vendidas en ventas asistidas.
  • sold_quantity_total: cantidad de unidades vendidas por publicidad.
  • amount_direct: suma del valor de las ventas directas obtenidas de tu Product Ad, en moneda local.
  • amount_indirect: suma del valor de las ventas asistidas obtenidas de tu Product Ad, en moneda local.
  • amount_total: suma del valor de las ventas obtenidas de tu Product Ad, en moneda local.
  • advertising_fee: expresado en porcentaje, la división entre inversión en publicidad sobre los ingresos obtenidos.
  • organic_orders_quantity: cantidad de unidades vendidas sin publicidad.
  • share: porcentaje de ventas por publicidad sobre ventas totales.
  • organic_sold_items_quantity: cantidad de ventas sin publicidad.
  • sold_items_quantity_direct: cantidad de ventas directas por publicidad.
  • sold_items_quantity_indirect: cantidad de ventas indirectas por publicidad.
  • sold_items_conversion: cantidad de ventas por publicidad.

Consultar anuncio asociado a un ítem

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

Respuesta:

{
    "id": "MLA657316800",
    "campaign_id": 141072850,
    "user_id": 246460082,
    "site_id": "MLA",
    "status": "active",
    "title": "Item de Teste",
    "price": 200,
    "currency_id": "ARS",
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-657316800-item-de-testeo_JM"
    "thumbnail": "http://mla-s2-p.mlstatic.com/471325-MLA25424154856_032017-I.jpg",
    "picture_id": "471325-MLA25424154856_032017",
    "date_created": "2017-03-10T02:27:32.325+0000",
    "last_updated": "2017-03-10T02:27:32.325+0000"
}

Editar estado de anuncio

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
  "status": "paused" | "active"
}

Buscar anuncios por usuarios

Parámetros

  • user_id: requerido.
  • status: opcional, es el status de los Product Ads.
  • title: opcional, son palabras incluidas en el título del Product Ad.
  • campaigns: opcional, recibe un campaign id.
  • offset y limit: opcionales. El limit no podrá ser mayor a 100.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

Buscar +10.000 anuncios por usuario

Para aquellos usuarios con búsquedas de más 10.000 anuncios tendrán una nueva forma de consultar.


1. Realizar la primer búsqueda normalmente:


Parámetros obligatorios

  • user_id: id del usuario, tipo long.
  • site_id: sitio del país del usuario, tipo string.
  • limit: límite de resultados por búsqueda, tipo integer.

Parámetro opcional

channel: canal del ítem (marketplace/mshops) – Por defecto es marketplace, tipo string.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

Respuesta:

{
   "results": [
       {
           "id": "MLA000000000",
           "campaign_id": 10000000,
           "user_id": 10000000,
           "site_id": "MLA",
           "cpc": 0.01,
           "status": "active",
           "title": "Description",
           "price": 100.45,
           "currency_id": "USD",
           "permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
           "thumbnail": "http://mla-s2-p.mlstatic.com/test.jpg",
           "picture_id": "ABCD_12345_ZYX",
           "channel": "marketplace",
           "date_created": "2022-05-07T21:11:05.000-04:00",
           "last_updated": "2022-11-22T11:22:20.000-04:00"
       }
   ],
   "paging": {
           "offset": 0,
           "last_item_id": "MLA000000001",
           "total": 12,
           "limit": 1
   }
}

Campos de respuesta

Contiene la cantidad de ítems definida por limit.

  • total: total de elementos que posee el usuario.
  • limit: cantidad de elementos por página de búsqueda.
  • last_item_id: último item_id de la lista que servirá para la próxima petición y comenzar a mostrar los siguientes elementos dependiendo del limit especificado.

2. Identificar el last_item_id (último item_id de la lista) que servirá para la próxima petición.


3. Hacer la segunda búsqueda con el último ítem de la lista como elemento pivote para la siguiente página de resultados. Para esta búsqueda no debes enviar el parámetro offset, dado que si se envía junto al last_item_id, se producirá un error.


Parámetros obligatorios

  • user_id: id del usuario, tipo long.
  • site_id: sitio del país del usuario, tipo string.
  • limit: límite de resultados por búsqueda, tipo integer.
  • last_item_id: último ítem de la lista que servirá como elemento pivote para la siguiente página de resultados. Si no se coloca, volverá al comienzo de todo el listado. Tipo string.

Parámetro opcional

channel: Canal del ítem (marketplace/mshops) – Por defecto es marketplace, tipo string.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE&last_item_id=$LAST_ITEM_ID