Display Ads

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: 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": 36,
      "site_id": "MLM"
    }
  ]
}

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.

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.
status: estado da campanha.
site_id: país.

Ver métricas da campanha

Os resultados deste endpoint serão as métricas por dia e um summary do período da campanha.

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

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

Resposta:

{
  "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.
site: país da campanha.
currency: moeda.
prints: Impressões: número de vezes que seus anúncios foram exibidos.
clicks: vezes que os usuários clicaram em seus anúncios.
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.
roas: Retorno do dinheiro obtido em investimento publicitário.
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.

Erros

Erro	Status	Mensagem
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.