Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Display Ads
Tipos de campañas y objetivos
Tipo de campaña | Objetivo | Métricas clave |
---|---|---|
Programmatic | Awareness: incrementa la exposición de una marca o producto entre usuarios de tu interés. | Alcance y frecuencia: permiten medir cuántos usuarios has alcanzado con tus anuncios y la cantidad de veces que los han visto en un determinado periodo. *Con creativo video disponible. |
Programmatic | Consideration: aumenta las visitas y acciones de usuarios en una marca o producto. | Clicks and VPP: permiten medir cuántas veces se hizo clic en tus anuncios y cuántas visitas generaron a la página del producto. |
Programmatic | Conversion: aumenta las ventas de productos de tu marca con publicidad. | Ingresos y ventas: permiten cuantificar las ventas generadas luego que los usuarios visualicen o hagan clic en tus anuncios. |
Guaranteed | Son creadas y gestionadas por el equipo de operaciones de Mercado Libre. | Permiten planificar y comprar una cierta cantidad de impresiones a un CPM fijo. |
Flujo técnico recomendado
- Anunciantes (advertiser id) de display
- Campañas de anunciantes
- Métricas de una campaña
Panel de campaña en Mercado Ads
Consultar anunciante
Los anunciantes (advertiser_id) son quienes invierten un presupuesto para la creación y distribución de anuncios publicitarios, con el objetivo de promocionar sus productos o servicios. Consulta el listado de anunciantes que tiene acceso a un usuario, según el tipo de producto que se requiera.
Parámetros obligatorios
product_id: tipo de producto. Valores disponibles: PADS (Product Ads), DISPLAY, BADS (Brand Ads).
Parámetros opcionales
sort_by: ordena por atributo (advertiser_id, site_id). Default advertiser_id.
sort_order: orden (asc, desc). Default es desc.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=$PRODUCT_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=DISPLAY
Respuesta:
{
"advertisers": [
{
"advertiser_id": 000,
"site_id": "MLB",
"advertiser_name": "Advertiser AAA",
"account_name": "MLB - XZY"
},
{
"advertiser_id": 111,
"site_id": "MLM",
"advertiser_name": "Advertiser BBB",
"account_name": "MLM - XYZ"
},
{
"advertiser_id": 222,
"site_id": "MLA",
"advertiser_name": "Advertiser CCC",
"account_name": "MLA - XYZ"
},
{
"advertiser_id": 333,
"site_id": "MLC",
"advertiser_name": "Advertiser DDD",
"account_name": "MLC - XYZ"
}
]
}
Glosario
advertiser_id: identificador del anunciante. Lo utilizarás para el resto de solicitudes.
site_id: identificador del país. Consulta la nomenclatura de los sites de Mercado Libre y sus respectivas monedas.
advertiser_name: nombre del anunciante.
account_name: nombre de la cuenta.
Consultar campañas de un anunciante
Parámetros opcionales
sort_by: ordena por atributo (id, name, start_date, end_date). Default es id.
sort_order: orden (asc, desc). Default es desc.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns?sort_by=start_date&sort_order=desc
Respuesta:
{
"results": [
{
"id": 80,
"name": "CONVERSION_ENERO2022_MLA",
"start_date": "2022-01-12T17:00:00",
"end_date": "2022-01-31T23:59:00",
"advertiser_id": 61,
"type": "GUARANTEED",
"status": "paused",
"site_id": "MLA"
}
]
}
Campos de respuesta
id: id de campaña. Utiliza el id para consultar métricas de campañas.
name: nombre de la campaña.
start_date: fecha de inicio de la campaña.
end_date: fecha de finalización de la campaña.
advertiser_id: id del advertiser
type: tipo de la campaña: Programática o Garantizada.
status: estado de la campaña.
site_id: país.
strategy: objetivo de campaña. Próximamente disponible.
Consultar métricas de una campaña
Los resultados de este endpoint serán las métricas por día y un summary por el rango de fecha de la campaña. Puedes consultar hasta 90 días atrás, considerando como fecha inicial el día 1 de septiembre de 2022.
Parámetros obligatorios
date_from: fecha desde de la consulta en formato YYYY-MM-DD.
date_to: fecha hasta de la consulta en formato YYYY-MM-DD.
Parámetros opcionales
sort_by: ordena por atributo: id, name, start_date, end_date. Por default es id.
sort_order: orden ascendente (asc) o descendente (desc). Por default es desc.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns/80/metrics?date_from=2024-04-01&date_to=2024-04-15
Respuesta:
{
"metrics": [
{
"date": "2024-02-01",
"site_id": "MLM",
"currency": "MXN",
"prints": 17961,
"clicks": 186,
"active_views": 0,
"completed_views": 0,
"reach": 10079,
"ctr": 0.01,
"consumed_budget": 57449.13,
"cpm": 3198.55,
"cpc": 308.87,
"average_frequency": 1148.98,
"event_time": {
"cpa_order": 1083.95,
"cpa_ppv": 135.81,
"roas": 10.03,
"units_quantity": 75,
"direct_amount": 576150,
"direct_item_quantity": 53,
"attribution_ppv": 423,
"attribution_add_to_cart": 26,
"attribution_bookmark": 33,
"attribution_checkout": 24,
"attribution_leads": 0,
"cpl": 0.0
},
"touch_point": {
"cpa_order": 1148.98,
"cpa_ppv": 125.16,
"roas": 12.36,
"units_quantity": 70,
"direct_amount": 710324,
"direct_item_quantity": 50,
"attribution_ppv": 459,
"attribution_add_to_cart": 26,
"attribution_bookmark": 35,
"attribution_checkout": 28,
"attribution_leads": 0,
"cpl": 0.0
}
}
],
"summary": {
"site_id": "MLM",
"currency": "MXN",
"prints": 170462,
"clicks": 2033,
"active_views": 0,
"completed_views": 0,
"reach": 48957,
"ctr": 0.01,
"consumed_budget": 605406.93,
"cpm": 3551.57,
"cpc": 297.79,
"average_frequency": 1509.74,
"event_time": {
"cpa_order": 1513.52,
"cpa_ppv": 128.59,
"roas": 9.48,
"units_quantity": 586,
"direct_amount": 5741691,
"direct_item_quantity": 400,
"attribution_ppv": 4708,
"attribution_add_to_cart": 263,
"attribution_bookmark": 375,
"attribution_checkout": 219,
"attribution_leads": 0,
"cpl": 0.0
},
"touch_point": {
"cpa_order": 1509.74,
"cpa_ppv": 125.66,
"roas": 9.49,
"units_quantity": 586,
"direct_amount": 5746421,
"direct_item_quantity": 401,
"attribution_ppv": 4818,
"attribution_add_to_cart": 270,
"attribution_bookmark": 352,
"attribution_checkout": 225,
"attribution_leads": 0,
"cpl": 0.0
}
}
}
Campos de respuesta
date: fecha de la campaña.
site_id: identificador del país. Consulta la nomenclatura de los sites de Mercado Libre y sus respectivas monedas.
currency: identificador de moneda.
prints: impresiones. Es la cantidad de veces que se mostraron tus anuncios.
clicks: cantidad de veces que los usuarios hicieron clic en tus anuncios.
active_views (vistas activas): cantidad de veces que los usuarios vieron los primeros 6 segundos de tu anuncio de Social y Video.
completed_views (vistas completas): cantidad de veces que los usuarios vieron tu anuncio completo de Social y Video.
reach: Alcance. Es la cantidad de usuarios únicos a los que se le mostraron tus anuncios.
ctr: Click-Through Rate. Tasa de clics obtenidos sobre el total de impresiones.
consumed_budget: Inversión: Es la cantidad de dinero efectivamente gastado para mostrar tus anuncios.
cpm: costo promedio que se paga por cada mil impresiones de los anuncios.
cpc: Costo por clic. Es el costo promedio que se paga por cada clic que recibieron los anuncios.
average_frequency: Frecuencia promedio. Promedio de la cantidad de veces que a un mismo usuario se le mostraron tus anuncios.
Las métricas de atribución tienen dos formas de ser presentadas:
Métricas atribuidas por Fecha de acción (event_time): las métricas se mostrarán asociadas a la fecha exacta en que la acción fue realizada (Ej: Ventas).
Métricas atribuidas por Fecha de visualización (touchpoint): las métricas se mostrarán asociadas a la fecha de clic o impresión visible a la que fueron atribuidas.
- cpa_order: (ventas): costo promedio para cada venta en función de la inversión.
- cpa_ppv: costo promedio de cada vista a la página de producto en función de la inversión.
- roas: retorno de dinero que se obtiene sobre la inversión.
- units_quantity: cantidad de unidades de tus productos que se han vendido entre todas las compras atribuidas a tus anuncios.
- direct_amount (ingresos): valor total de las ventas atribuidas a tus anuncios.
- direct_item_quantity: cantidad de veces que los usuarios realizaron una compra después de ver o hacer clic en tus anuncios.
- attribution_ppv (vistas a páginas de producto): cantidad de veces que los usuarios vieron tu página de producto después de ver o hacer clic en tus anuncios.
- attribution_add_to_cart: cantidad de veces que los usuarios agregaron al carrito de compra tus productos promocionados después de ver o hacer clic en tus anuncios.
- attribution_bookmark: contactos generados por los clientes potenciales después que vieron o hicieron clic en tus anuncios.
- attribution_checkout: cantidad de veces que los usuarios iniciaron un proceso de compra de tus productos promocionados después de ver o hacer clic en tus anuncios.
- attribution_leads: contactos generados por los clientes potenciales después que vieron o hicieron clic en tus anuncios.
- cpl: costo promedio de cada lead en función de la inversión.
Line items de una campaña
El line item define los parámetros de compra del anuncio: el perfil de usuario a quien querés llegar, su ubicación geográfica, el dispositivo desde donde navega, entre otras. Cada line item está asociado a una única campaña y consume de su presupuesto.
Parámetros opcionales
sort_by: valores posibles: id, name, start_date, end_date.
sort_order: valores posibles: asc, desc.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/line_items?sort_by=start_date&sort_order=asc
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/123456/display/campaigns/987654/line_items?sort_by=start_date&sort_order=asc
Respuesta:
{
"results": [
{
"line_item_id": 1,
"name": "Name_Line_Item_Test",
"start_date": "2022-01-12T17:00:00",
"end_date": "2022-01-31T23:59:00",
"campaing_id": 987654,
"type": "Social",
"status": "paused"
}
]
}
Campos de respuesta
line_item_id: id del line item.
name: nombre del line item.
start_date: fecha de inicio del line item.
end_date: fecha de fin del line item.
type: tipo de line item. Varían de acuerdo al creativo asignado.
- Display: banner nativo de imagen y texto. Apto para distintos espacios publicitarios de Mercado Libre y Mercado Pago
- Social: video en formato vertical con banner inferior. Disponible para los espacios de Clips de Mercado Libre.
- Video: video en formato horizontal. Disponible para las plataformas de streaming integradas con Mercado Ads. Este tipo de line item solo está habilitado para campañas con objetivo Awareness.
status: estado del line item.
Creativos de line item
Parámetros opcionales
sort_by: valores posibles: id, name.
sort_order: valores posibles: asc, desc.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/line_items/$LINE_ITEM_ID/creatives?sort_by=start_date&sort_order=asc
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/999999/line_items/0000001/creatives?sort_by=start_date&sort_order=asc
Respuesta:
{
"results": [
{
"creative_id": 123456,
"name": "Name_Creative_Test",
"status": "active",
"line_item_id": 0000001,
"campaign_id": 999999
}
]
}
Campos de respuesta
creative_id: id del creativo.
name: nombre del creativo.
status: estado del creativo. Puede ser: active.
line_item_id: id del line item.
campaign_id: id de la campaña.
Errores
Error | Status | Mensaje |
---|---|---|
bad_request | 400 | The parameter {paramKey} is required. |
not_found | 404 | No campaigns found for advertiser id {advertiser_id} Campaign not found for sent campaign_id. |
not_found | 404 | No line items found for campaign_id {campaign_id} |
not_found | 404 | No creatives found for line_item_id {line_item_id} |