Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.Documentação do
Display Ads
Fluxo técnico recomendado
- Anunciantes (advertiser id) de display
- Campanhas de anunciantes
- 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. |