Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Product Ads
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.
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