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 15/07/2024

Display Ads

Esta funcionalidad tiene el objetivo de mejorar la capacidad de los anunciantes para comprender y optimizar el rendimiento de sus campañas publicitarias. Puedes acceder a información relevante y actualizada de manera automatizada, permitiendo a los anunciantes integrar eficientemente los datos para análisis y comparación. Los vendedores, agencias y marcas pueden:

  • Mostrar anuncios de sus productos cuando su público potencial accede a alguna de las plataformas del ecosistema de Mercado Libre.
  • Elegir a qué público mostrar sus anuncios (segmentación).
  • Crear anuncios adaptados a múltiples espacios publicitarios de manera ágil.
  • Mostrar anuncios a los usuarios en los distintos momentos de la fase de compra.
  • Establecer costos variables por objetivos de campaña en lugar de costos fijos por impresión.

Flujo técnico recomendado

  1. Anunciantes (advertiser id) de display
  2. Campañas de anunciantes
  3. Métricas de una campaña

  4. 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": 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. 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,
      "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.0,
        "direct_item_quantity":53,
        "attribution_ppv":423,
        "attribution_add_to_cart":26,
        "attribution_bookmark":33,
        "attribution_checkout":24
      },
      "touch_point":{
        "cpa_order":1148.98,
        "cpa_ppv":125.16,
        "roas":12.36,
        "units_quantity":70,
        "direct_amount":710324.0,
        "direct_item_quantity":50,
        "attribution_ppv":459,
        "attribution_add_to_cart":26,
        "attribution_bookmark":35,
        "attribution_checkout":28
      }
    }
  ],
  "summary":{
    "site_id":"MLM",
    "currency":"MXN",
    "prints":170462,
    "clicks":2033,
    "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.0,
      "direct_item_quantity":400,
      "attribution_ppv":4708,
      "attribution_add_to_cart":263,
      "attribution_bookmark":375,
      "attribution_checkout":219
    },
    "touch_point":{
      "cpa_order":1509.74,
      "cpa_ppv":125.66,
      "roas":9.49,
      "units_quantity":586,
      "direct_amount":5746421.0,
      "direct_item_quantity":401,
      "attribution_ppv":4818,
      "attribution_add_to_cart":270,
      "attribution_bookmark":352,
      "attribution_checkout":225
    }
  }
}

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.
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: 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.