Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.Documentação do
Brand Ads
Flujo técnico recomendado
- Consultar anunciante (advertiser id)
- Consultar campanhas, anuncios e keywords
- 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.