Display Ads

Flujo técnico recomendado

1. Anunciantes (advertiser id) de display
2. Campañas de anunciantes
3. 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: 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": 36,
      "site_id": "MLM"
    }
  ]
}

Campos de respuesta

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.

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.
status: estado de la campaña.
site_id: país.

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.

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.
fields: daily, summary. Por default es summary.

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

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

Respuesta:

{
  "metrics":[
    {
      "date":"2024-02-01",
      "prints":17961,
      "clicks":186,
      "reach":10079,
      "ctr":0.01,
      "consumed_budget":57449.13,
      "cpm":3198.55,
      "cpc":308.87,
      "cpa":1148.98,
      "roas":12.36,
      "average_frequency":1.78,
      "event_time":{
        "cpa_order":1083.95,
        "cpa_ppv":135.81,
        "roas":10.03,
        "units_quantity":53.0,
        "direct_amount":576150.0,
        "direct_item_quantity":75.0,
        "attribution_ppv":423.0,
        "attribution_add_to_cart":26.0,
        "attribution_bookmark":33.0,
        "attribution_checkout":24.0
      },
      "touch_point":{
        "cpa_order":1148.98,
        "cpa_ppv":125.16,
        "roas":12.36,
        "units_quantity":50.0,
        "direct_amount":710324.0,
        "direct_item_quantity":70.0,
        "attribution_ppv":459.0,
        "attribution_add_to_cart":26.0,
        "attribution_bookmark":35.0,
        "attribution_checkout":28.0
      }
    }
  ],
  "summary":{
    "prints":170462,
    "clicks":2033,
    "reach":48957,
    "ctr":0.01,
    "cpm":3551.57,
    "cpc":297.79,
    "cpa":1509.74,
    "roas":9.49,
    "average_frequency":3.48,
    "event_time":{
      "cpa_order":1513.52,
      "cpa_ppv":128.59,
      "roas":9.48,
      "attribution_order":400.0,
      "direct_amount":5741691.0,
      "direct_item_quantity":586.0,
      "attribution_ppv":4708.0,
      "attribution_add_to_cart":263.0,
      "attribution_bookmark":375.0,
      "attribution_checkout":219.0
    },
    "touch_point":{
      "cpa_order":1509.74,
      "cpa_ppv":125.66,
      "roas":9.49,
      "attribution_order":401.0,
      "direct_amount":5746421.0,
      "direct_item_quantity":586.0,
      "attribution_ppv":4818.0,
      "attribution_add_to_cart":270.0,
      "attribution_bookmark":352.0,
      "attribution_checkout":225.0
    }
  }
}

Campos de respuesta

date: fecha de la campaña.
site: país de la campaña. Conoce los países y monedas de Mercado Libre.
currency: moneda local.
prints: impresiones. Es la cantidad de veces que se mostraron tus anuncios.
clicks: cantidad de veces que los usuarios hicieron clic en tus anuncios.
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.
roas: Retorno de dinero que se obtiene sobre la inversión publicitaria.
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: costo promedio de cada venta en función de la inversión.
• cpa_ppv: costo promedio de cada vista a 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 visitaron 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: cantidad de veces que los usuarios agregaron a favoritos tus productos promocionados después de ver o hacer 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.

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.