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

Brand Ads

Esta funcionalidade tem o objetivo de melhorar a capacidade dos anunciantes para compreender e otimizar o rendimento de suas campanhas publicitárias. Você pode acessar informações relevantes e atualizadas de forma automatizada, permitindo que os anunciantes integrem com eficiência os dados para análise e comparação.

Posicionamento
Para que um anúncio de Brand Ads seja exibido na posição 0 dos resultados da pesquisa, o significado das palavras-chave configuradas deve coincidir com a pesquisa realizada por um usuário. Para determinar qual anúncio será exibido, Brand Ads utiliza um sistema de pujas onde cada anunciante configura:

  • a palavra-chave que você deseja vincular ao seu anúncio
  • o costo por clique (CPC) máximo que está em disputa para pagar

O algoritmo de Brand Ads avalia os anúncios que compõem um mesmo espaço (ou seja, que compartilham palavras-chave) com base em uma série de critérios e atribui uma pontuação chamada Ad-Score, que mede a probabilidade de conversão do anúncio. Esta pontuação depois está em uma conta junto com o CPC máximo para elaborar uma classificação (Ad Rank) que estabelece o ganhador da subasta.

Flujo técnico recomendado

  1. Consultar anunciante (advertiser id)
  2. Consultar campanhas, anuncios e keywords
  3. Consulta métricas do anunciante, campanhas e keywords

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

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

Resposta:

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

Buscar campañas de un advertiser

Chamada:

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

Resposta:

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

Chamada:

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

Resposta:

{
      "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 itens de uma campanha

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/items
[
  {
    "campaign_id": 1,
    "status": "active",
    "item_id": "MLA1178375484"
  }
]

Consultar keywords da campanha

Chamada:

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

Resposta:

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

Métricas da campanha do anunciante

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

limit: por padrão 50.
offset: por padrão 0.
aggregation_type: tipo agregado de dados a serem exibidos. Valores possíveis: daily, total. Por padrão, ele retorna ambos.
fields: campos de métrica específicos a serem consultados.


Chamada:

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

Resposta:

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

prints (Impressões): número de vezes que seus anúncios foram exibidos.
clicks: número de vezes que os usuários clicaram em seus anúncios.
ctr (click-through rate): taxa de cliques obtidos sobre o total de impressões.
cvr: (taxa de conversão): taxa de conversão referente aos seus cliques.
consumed_budget (Investimento): valor efetivamente gasto para exibir seus anúncios.
cpc (custo por clique): custo médio pago por cada clique que os anúncios receberam.
acos (advertising cost of sales): valor investido em anúncios sobre o total geral gerado pelas vendas atribuídas ( investimento / ganhos )
event_time: métricas atribuídas por data da ação serão mostradas associadas à data exata em que a ação foi realizada (exemplo: vendas).
units_quantity (ventas) número de vezes que os usuários fizeram uma compra depois de visualizar ou clicar em seus anúncios.
units_amount (ingressos): valor total gerado pelas vendas atribuídas aos seus anúncios.
items_quantity: quantidade de itens vendidos por atribuições
ppv_conversions VPP (visualizações de páginas de produtos): número de visualizações de páginas de produtos após visualizar ou clicar em seus anúncios.
bookmark_conversions (bookmark) número de itens atribuíveis que foram marcados como favoritos após visualizar ou clicar em seus anúncios.
cart_conversions: (carrinho) número de itens atribuíveis que foram adicionados ao carrinho de compras após visualizar ou clicar em seus anúncios.
checkout_conversions: número de itens atribuíveis para os quais o processo de compra foi iniciado após visualizar ou clicar em seus anúncios.
leads_question_conversions: número de potenciais clientes interessados em adquirir seu produto que solicitaram em sua publicação após clicarem em seus anúncios.
leads_im_conversions: quantidade de potenciais clientes interessados em adquirir seu produto que entraram em contato pelo WhatsApp a partir de sua publicação após clicarem em seus anúncios.
eshop_conversions:quantidade de vendas atribuídas.
touch_point: métricas atribuídas por data de visualização serão exibidas associadas à data do clique ou impressão visível que as gerou.

  • units_quantity: (vendas) número de vezes que os usuários fizeram uma compra depois de visualizar ou clicar em seus anúncios.
  • units_amount: (ingressos) valor total gerado pelas vendas atribuídas aos seus anúncios.
  • items_quantity: número de itens vendidos por atribuições.
  • ppv_conversions: (visualizações de páginas de produtos) número de visualizações nas páginas dos produtos após visualizar ou clicar em seus anúncios.
  • bookmark_conversions: (bookmark) número de itens atribuíveis que foram marcados como favoritos após visualizar ou clicar em seus anúncios.
  • cart_conversions: (carrinho) número de itens atribuíveis que foram adicionados ao carrinho de compras após visualizar ou clicar em seus anúncios.
  • checkout_conversions: (checkout) número de itens atribuíveis para os quais o processo de compra foi iniciado após visualizar ou clicar em seus anúncios.
  • leads_question_conversions: número de potenciais clientes interessados em adquirir seu produto que solicitaram em sua publicação após clicarem em seus anúncios.
  • 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: quantidade de vendas atribuídas.

Métricas por campanha e dia

Parâmetros obrigatórios

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


Parâmetros opcionais

limit: por padrão 50.
offset: por padrão 0.
aggregation_type: tipo agregado de dados a serem exibidos. Valores possíveis: daily, total. Por padrão, ele retorna ambos.
fields: campos de métrica específicos a serem consultados.


Chamada:

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

Exemplo:

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

Resposta:

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

Campos de resposta

Você pode consultar as estatísticas com base no endpoint anterior. Além disso, as métricas de competitividade da campanha são:


lost_impression_share_by_budget: porcentagem de impressões perdidas por pressuposto.
lost_impression_share_by_ad_rank: porcentagem de impressões perdidas pelo Ad Rank.
impression_share: impressões ganhas por uma campanha sobre o total de impressões que a campanha era elegível para ganhar.
competitive_cpc: costo pelo click (cpc) médio da competição.


Métricas de keywords por campanha e dias

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


Parâmetros obrigatórios

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


Parâmetros opcionais

limit: por padrão 50.
offset: por padrão 0.
aggregation_type: tipo de agregado de dados a mostrar. Valores possíveis: daily, total. Por defeito retorna ambos.
keywords: palavras-chave específicas para consultar.


Chamada:

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

Resposta:

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

Seguinte: Display Ads.