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 03/05/2024

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

Posicionamiento
Para que un anuncio de Brand Ads se muestre en la posición 0 de los resultados de búsqueda, el significado de las palabras clave configuradas deben coincidir con la búsqueda que realizó un usuario. Para determinar qué anuncio se muestra, Brand Ads utiliza un sistema de pujas donde cada anunciante establece:

  • la palabra clave que quiere vincular con su anuncio
  • el CPC máximo que está dispuesto a pagar

El algoritmo de Brand Ads evalúa los anuncios que compiten por un mismo espacio (es decir, que comparten palabras clave) en base a una serie de criterios y les asigna un puntaje, llamado Ad-Score, que mide la probabilidad de convertir del anuncio. Este puntaje luego se tiene en cuenta junto con el CPC máximo para elaborar un ranking (Ad Rank) que establece el ganador de la subasta.

Flujo técnico recomendado

  1. Consulta anunciante (advertiser id)
  2. Consulta las campañas, anuncios y keywords
  3. Consulta métricas de advertiser, campañas y keywords

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: BADS (Brand Ads), DISPLAY.

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=BADS

Respuesta:

{
  "advertisers": [
    {
      "advertiser_id": 36,
      "site_id": "MLM"
    }
  ]
}

Buscar campañas de un advertiser

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns

Respuesta:

{
  "paging": {
    "total": 50,
    "offset": 0,
    "limit": 2
  },
  "campaigns": [
    {
      "campaign_id": 1,
      "name": "campaign meli 1",
      "start_date": "2024-01-01T00:06:22.000Z",
      "end_date": "2024-01-01T00:06:22.000Z",
      "advertiser_id": 1234,
      "campaign_type": "custom",
      "status": "active",
      "site_id": "MLA",
      "official_store_id": 12345,
      "destination_id": 12345,
      "headline": "esto es un headline",
      "budget": {
        "amount": 1111111.32,
        "currency": "ARS"
      },
      "cpc": 100.5,
      "items": [
        {
          "campaign_id": 1,
          "status": "active",
          "item_id": "MLA1178375484"
        }
      ],
      "keywords": [
        {
          "campaign_id": 1,
          "type": "custom",
          "term": "auto",
          "match_type": "phrase",
          "is_negative": false,
          "cpc": 50.5
        }
      ]
    }
  ]
}

Consultar campaña por advertiser

Llamada:

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

Respuesta:

{
      "campaign_id": 1,
      "name": "campaign meli 1",
      "start_date": "2024-01-01T00:06:22.000Z",
      "end_date": "2024-01-01T00:06:22.000Z",
      "advertiser_id": 1234,
      "campaign_type": "custom",
      "status": "active",
      "site_id": "MLA",
      "official_store_id": 12345,
      "destination_id": 12345,
      "headline": "esto es un headline",
      "budget": {
        "amount": 1111111.32,
        "currency": "ARS"
      },
      "cpc": 100.5,
      "items": [
        {
          "campaign_id": 1,
          "status": "active",
          "item_id": "MLA1178375484"
        }
      ],
      "keywords": [
        {
          "campaign_id": 1,
          "keyword_id": 1,
          "type": "custom",
          "term": "auto",
          "match_type": "phrase",
          "is_negative": false,
          "cpc": 50.5
        }
      ]
    }

Consultar items de una campaña

Llamada:

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

Response:

[
  {
    "campaign_id": 1,
    "status": "active",
    "item_id": "MLA1178375484"
  }
]

Consultar keywords de campaña

Llamada:

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

Respuesta:

[
  {
    "campaign_id": 1,
    "type": "custom",
    "term": "auto",
    "match_type": "phrase",
    "is_negative": false,
    "cpc": 50.5
  }
]

Métricas de campañas del advertiser

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

limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics

Respuesta:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-08",
            "site_id": "MLA",
            "currency": "ARS",
            "prints": 0,
            "clicks": 0,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 0.00,
            "cpc": 0.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ],
    "summary": {
        "site_id": "MLA",
        "currency": "ARS",
        "prints": 0,
        "clicks": 0,
        "ctr": 0.00,
        "cvr": 0.00,
        "consumed_budget": 0.00,
        "cpc": 0.00,
        "acos": 0,
        "event_time": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "touch_point": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        }
    }
}

Campos de respuesta

prints (impresiones): es la cantidad de veces que se mostraron tus anuncios.
clicks: cantidad de veces que los usuarios hicieron clic en tus anuncios.
ctr (click-through rate): tasa de clics obtenidos sobre el total de impresiones.
cvr: (conversion rate): tasa de conversión respecto a sus clicks.
consumed_budget (inversión): cantidad de dinero efectivamente gastado para mostrar tus anuncios.
cpc (costo por clic): costo promedio que se paga por cada clic que recibieron los anuncios.
acos (advertising cost of sales): inversión ingreso/egreso, costo publicitario de ventas.
event_time: métricas atribuidas por fecha de acción, se mostrarán asociadas a la fecha exacta en que la acción fue realizada (Ej: ventas).
units_quantity (ventas): cantidad de veces que los usuarios realizaron una compra después de ver o hacer clic en tus anuncios).
units_amount (ingresos): valor total generado por las ventas atribuidas a tus anuncios.
items_quantity: cantidad de ítems vendidos por atribuciones.
ppv_conversions (vistas a páginas de producto): cantidad de vistas a las páginas de productos después de ver o hacer clic en tus anuncios.
bookmark_conversions cantidad de items atribuibles que se marcaron como favoritos después de ver o hacer clic en tus anuncios.
cart_conversions: cantidad de items atribuibles que se agregaron al carrito de compras después de ver o hacer clic en tus anuncios.
checkout_conversions: cantidad de items atribuibles para los cuales se hayan iniciado el proceso de compra después de ver o hacer clic en tus anuncios.
leads_question_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que preguntaron en tu publicación luego de hacer clic en tus anuncios.
leads_im_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que te contactaron por Whatsapp desde tu publicación luego de hacer clic en tus anuncios.
eshop_conversions: cantidad de ventas atribuidas.
touch_point: métricas atribuidas por fecha de visualización, se mostrarán asociadas a la fecha de clic o impresión visible que las generó.

  • units_quantity: (ventas) cantidad de veces que los usuarios realizaron una compra después de ver o hacer clic en los anuncios.
  • units_amount: (ingresos) valor total generado por las ventas atribuidas a tus anuncios.
  • items_quantity: cantidad de ítems vendidos por atribuciones.
  • ppv_conversions: (vistas a páginas de producto), Cantidad de vistas a las páginas de productos después de ver o hacer clic en tus anuncios.
  • bookmark_conversions: (bookmark) cantidad de items atribuibles que se marcaron como favoritos después de ver o hacer clic en tus anuncios.
  • cart_conversions: (carrito) cantidad de items atribuibles que se agregaron al carrito de compras después de ver o hacer clic en tus anuncios.
  • checkout_conversions: (checkout) cantidad de items atribuibles para los cuales se hayan iniciado el proceso de compra después de ver o hacer clic en tus anuncios.
  • leads_question_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que preguntaron en tu publicación luego de hacer clic en tus anuncios.
  • leads_im_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que te contactaron por Whatsapp desde tu publicación luego de hacer clic en tus anuncios.
  • eshop_conversions: cantidad de ventas atribuidas.

Métricas por campaña y día

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

limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.


Llamada:

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

Ejemplo:

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

Respuesta:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-02",
            "prints": 2026,
            "site_id": "MLA",
            "currency": "ARS",
            "clicks": 20,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 3000.00,
            "cpc": 150.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ],
    "summary": {
        "prints": 2026,
        "clicks": 20,
        "site_id": "MLA",
        "currency": "ARS",
        "ctr": 0.00,
        "cvr": 0.00,
        "consumed_budget": 3000.00,
        "cpc": 150.00,
        "acos": 0,
        "event_time": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "touch_point": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "competitive": {
            "lost_impression_share_by_budget": 0.7,
            "lost_impression_share_by_ad_rank": 0.04,
            "impression_share": 0.26,
            "competitive_cpc": 175.0
        }
    }
}

Métricas de keywords por campaña y días

Obtiene las métricas de keywords de cada día para una campaña específica.


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

limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords/metrics

Respuesta:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-08",
            "keywords": [
                {
                    "keyword": "cloruro magnesio",
                    "site_id": "MLA",
                     "currency": "ARS",
                    "prints": 2,
                    "clicks": 0,
                    "ctr": 0.00,
                    "cvr": 0.00,
                    "consumed_budget": 0.00,
                    "cpc": 0.00,
                    "acos": 0,
                    "event_time": {
                        "units_quantity": 0,
                        "units_amount": 0.00,
                        "items_quantity": 0,
                        "ppv_conversions": 0,
                        "bookmark_conversions": 0,
                        "cart_conversions": 0,
                        "checkout_conversions": 0,
                        "leads_question_conversions": 0,
                        "leads_im_conversions": 0,
                        "eshop_conversions": 0
                    },
                    "touch_point": {
                        "units_quantity": 0,
                        "units_amount": 0.00,
                        "items_quantity": 0,
                        "ppv_conversions": 0,
                        "bookmark_conversions": 0,
                        "cart_conversions": 0,
                        "checkout_conversions": 0,
                        "leads_question_conversions": 0,
                        "leads_im_conversions": 0,
                        "eshop_conversions": 0
                    }
                }
            ]
        }
    ],
    "summary": [
        {
            "keyword": "cloruro magnesio",
            "site_id": "MLA",
            "currency": "ARS",
            "prints": 2,
            "clicks": 0,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 0.00,
            "cpc": 0.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ]
}

Siguiente: Display Ads.