Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 23/05/2024

Display Ads

Esta funcionalidade destina-se a melhorar a capacidade dos anunciantes de compreender e otimizar o desempenho das suas campanhas publicitárias. Você pode acessar informações relevantes e atualizadas de maneira automatizada, permitindo que os anunciantes integrem dados de forma eficiente para análise e comparação. Fornecedores, agências e marcas podem:

  • Mostrar anúncios de seus produtos quando seu público potencial acessar qualquer uma das plataformas do ecossistema Mercado Livre.
  • Escolha para qual público exibir seus anúncios (segmentação).
  • Crie anúncios adaptados a múltiplos espaços publicitários de forma ágil.
  • Mostre anúncios aos usuários em momentos diferentes durante a fase de compra.
  • Estabeleça custos variáveis ​​por objetivos de campanha em vez de custos fixos por impressão.

Fluxo técnico recomendado

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

  4. 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 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,
      "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 resposta

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

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.