Display Ads

Tipos e objetivos de campanha

Fluxo técnico recomendado

1. Anunciantes (advertiser id) de display
2. Campanhas de anunciantes
3. Métricas de uma campanha



Painel de campanha en Mercado Ads

Consultar anunciante

Os anunciantes (advertiser_id) são aqueles que têm um pressuposto para a criação e distribuição de anúncios publicitários, com o objetivo de promover seus produtos ou serviços. Consulte a listagem de anunciantes que têm acesso a um usuário, dependendo do tipo de produto que você deseja (Brand Ads ou Display).

Parâmetros obrigatórios

product_id: tipo de produto. Valores disponíveis: PADS (Product Ads), DISPLAY, BADS (Brand Ads).

Parâmetros opcionais

sort_by: classifica por atributo (advertiser_id, site_id). Por padrão é advertiser_id.
sort_order: ordem (asc, desc). Por padrão é desc.

Chamada:

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

Exemplo:

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

Resposta:

{
    "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"
        }
    ]
}

Campos de resposta

advertiser_id: identificador do anunciante. Você o usará para o restante das solicitações.
site_id: identificador do país. Consulte a nomenclatura dos sites do Mercado Livre e suas respectivas moedas.
advertiser_name: nome do anunciante.
account_name: nome da conta.

Consultar as campanhas de um anunciante

Parâmetros opcionais

sort_by: classifica por atributo (id, name, start_date, end_date). O padrão é id.
sort_order: pedido (asc, desc). O padrão é desc.

Chamada:

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

Exemplo:

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

Resposta:

{
 "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 da resposta

id: id da campanha. Use o id para consultar as métricas da campanha.
name: nome da campanha.
start_date: data de início da campanha.
end_date: data de término da campanha.
advertiser_id: id do anunciante.
type: tipo da campanha: Programmatic ou Guaranteed.
status: estado da campanha.
site_id: país.
strategy: objetivo da campanha. Em breve.
:

Ver métricas da campanha

Os resultados deste endpoint serão as métricas por dia e um resumo do período da campanha. Você pode consultar até 90 dias atrás, considerando 1º de setembro de 2022 como data inicial.

Parâmetros obrigatórios

date_from: data desde a consulta no formato YYYY-MM-DD.
date_to: data até consulta no formato YYYY-MM-DD.

Parâmetros opcionais

sort_by: classifica por atributo (id, name, start_date, end_date). O padrão é id.
sort_order: pedido (asc, desc). O padrão é desc.

Chamada:

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

Exemplo:

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

Resposta:

{
  "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
    }
  }
}

Glossário

date: fecha.
site_id: identificador do país. Consulte a nomenclatura dos sites do Mercado Livre e suas respectivas moedas.
currency: identificador de moedas.
prints: Impressões: número de vezes que seus anúncios foram exibidos.
clicks: vezes que os usuários clicaram em seus anúncios.
active_views (vistas activas): quantidade de vezes que os usuários viram os primeiros 6 segundos do seu anúncio de Social e Vídeo.
completed_views (vistas completas): quantidade de vezes que os usuários viram seu anúncio completo de Social e Vídeo.
reach: Escopo: número de usuários únicos para os quais seus anúncios foram exibidos.
ctr: Click-Through Rate: taxa de cliques obtidos sobre o total de impressões.
consumed_budget: Investimento: valor efetivamente gasto para exibir seus anúncios.
cpm: custo médio pago por mil impressões de anúncios.
cpc: Custo por clique. É o custo médio pago por cada clique que os anúncios receberam.
average_frequency: Frequência média. Número médio de vezes que seus anúncios foram exibidos ao mesmo usuário.

As métricas de atribuição têm duas formas de serem apresentadas:

Métricas atribuídas por data de ação (event_time): as métricas serão mostradas associadas à data exata em que a ação foi realizada (Ex: Vendas).
Métricas atribuídas por data de visualização (touchpoint): as métricas serão exibidas associadas à data do clique ou impressão visível a que foram atribuídas.

• cpa_order: (vendas): custo médio de investimento para cada venda obtida.
• cpa_ppv: custo médio de investimento para cada visualização de página de produto obtida.
• roas: retorno do dinheiro obtido no investimento.
• units_quantity: unidades de seus produtos que foram vendidas entre todas as compras atribuídas aos seus anúncios.
• direct_amount (lucros): valor total das vendas atribuídas aos seus anúncios.
• direct_item_quantity: vezes que os usuários fizeram uma compra depois de visualizar ou clicar em seus anúncios.
• attribution_ppv (visualizações da página do produto): vezes que as pessoas visitaram a página do seu produto depois de visualizar ou clicar em seus anúncios.
• attribution_add_to_cart: vezes que os usuários adicionaram seus produtos promovidos ao carrinho de compras depois de visualizar ou clicar em seus anúncios.
• attribution_bookmark: vezes que os usuários adicionaram seus produtos promovidos aos favoritos depois de visualizar ou clicar em seus anúncios.
• attribution_checkout: vezes que os usuários iniciaram um processo de compra de seus produtos promovidos após visualizar ou clicar em seus anúncios.
• attribution_leads: contatos gerados por clientes em potencial depois que eles visualizaram ou clicaram em seus anúncios.
• cpl: custo médio de cada lead com base no investimento.
Note:
Existem 2 maneiras de um vendedor obter contatos:
- Publicações de Veículos, Imóveis ou Serviços (VIS): ao deixar uma dúvida, ligação ou WhatsApp, o lead chega até o vendedor. Saiba mais sobre nossas Veículos, Imóveis and Serviços APIs.
- 2. Formulários: preenchendo o formulário de contato que chega ao CRM do cliente. Por exemplo: o form.

Line items de campanha

O line item define os parâmetros de compra do anúncio patrocinado: o perfil do usuário que você quer alcançar, a localização geográfica, o dispositivo por onde a pessoa navega, entre outros. Cada line item está associado a uma única campanha e consome o orçamento dela.

Parâmetros opcionais

sort_by: valores possíveis: id, name, start_date, end_date.
sort_order: valores possíveis: asc, desc.

Chamada:

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

Exemplo:

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

Resposta:

{
 "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 resposta

line_item_id: id de line item.
name: nome de line item.
start_date: data de início de line item.
end_date: data final de line item.
type: tipo de line item. Eles variam de acordo com o criativo atribuído.

• Display: banner nativo com imagem e texto. Apto para distintos espaços de publicidade do Mercado Livre e Mercado Pago.
• Social: video en formato vertical con banner inferior. Disponible para los espacios de Clips de Mercado Libre.
• Video: vídeo no formato horizontal. Disponível para plataformas de streaming integradas ao Mercado Ads.

status: estado de line item.

Creativos de line item

Parâmetros opcionais

sort_by: valores posibles: id, name.
sort_order: valores posibles: asc, desc.

Chamada:

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

Exemplo:

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

Resposta:

{
    "results": [
        {
            "creative_id": 123456,
            "name": "Name_Creative_Test",
            "status": "active",
            "line_item_id": 0000001,
            "campaign_id": 999999
        }
    ]
}

Campos de resposta

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 da campanha.

Erros