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_IDExemplo:
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=BADSResposta:
{
"advertisers": [
{
"advertiser_id": 000,
"site_id": "MLB",
"advertiser_name": "Advertiser AAA",
"account_name": "MLB - XZY"
},
{
"advertiser_id": 111,
"site_id": "MLM",
"advertiser_name": "Advertiser BBB",
"account_name": "MLM - XYZ"
},
{
"advertiser_id": 222,
"site_id": "MLA",
"advertiser_name": "Advertiser CCC",
"account_name": "MLA - XYZ"
},
{
"advertiser_id": 333,
"site_id": "MLC",
"advertiser_name": "Advertiser DDD",
"account_name": "MLC - XYZ"
}
]
}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.
advertiser_name: nome do anunciante.
account_name: nome da conta.
Tipos de campanhas
Antes de consultar campanhas, recomendamos conhecer os tipos de campanhas. Além disso, você pode acessar métricas de campanhas a partir de 2023-02-09.
- Automatic: as campanhas automáticas são administradas pelo Mercado Ads. A campanha será executada automaticamente para todos os itens associados ao official_store_id do destination_id enviado e criará palavras-chave, que não poderão ser editadas nem eliminadas, ou seja, o Mercado Ads administrará o inventário do anunciante e atribuirá as melhores palavras-chave para seus anúncios.
- Custom: as campanhas personalizadas são criadas e administradas pelo usuário, onde o anunciante deve fornecer uma lista de itens (mínimo 3, máximo 10) com os quais configurar seu anúncio e as palavras-chave (mínimo 1, máximo 200) que são palavras-chave para buscas em que deseja ser exibido. Depois, poderá editar e excluir essas palavras-chave.
Search campanhas de anunciante
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaignsResposta:
{
"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
}
]
}
]
}Detalhe de campanha
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_IDResposta:
{
"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 anúncios de uma campanha custom
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 custom
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywordsResposta:
[
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]Métricas da campanha
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.
Filtros disponíveis
status: estado da campanha. Valores possíveis: active, paused.
destination_id: id de destination da campanha.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&aggregation_type=dailyExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/metrics?date_from=2024-07-01&date_to=2024-07-10&aggregation_type=dailyResposta:
{
"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
}
}
}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?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/123456/metrics?date_from=2024-07-01&date_to=2024-07-10Resposta:
{
"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
}
}
}Métricas de keywords por campanha e dias
Obtém as métricas de palavras-chave de cada dia para uma campanha 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?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/keywords/metrics?date_from=2024-07-01&date_to=2024-07-10Resposta:
{
"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
}
}
]
}Glossário
prints (impressões): é a quantidade de vezes que os seus anúncios foram exibidos.
clicks: quantidade de vezes que os usuários clicaram nos seus anúncios.
ctr (click-through rate): taxa de cliques obtidos sobre o total de impressões.
cvr (conversion rate): taxa de conversão em relação aos cliques.
consumed_budget (investimento): quantidade de dinheiro 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): investimento/receita, custo publicitário das vendas.
Métricas podem ser atribuídas:
event_time: métricas atribuídas por data de ação, serão mostradas associadas à data exata em que a ação foi realizada (Ex: vendas).
touch_point: métricas atribuídas por data de visualização, serão mostradas associadas à data do clique ou impressão visível que as gerou.
- units_quantity (vendas): quantidade de vezes que os usuários realizaram uma compra após ver ou clicar nos anúncios.
- units_amount (receita): valor total gerado pelas vendas atribuídas aos seus anúncios.
- items_quantity: quantidade de itens vendidos por atribuições.
- ppv_conversions (visualizações de páginas de produto): quantidade de visualizações nas páginas de produtos após ver ou clicar nos seus anúncios.
- bookmark_conversions (bookmark): quantidade de itens atribuíveis que foram marcados como favoritos após ver ou clicar nos seus anúncios.
- cart_conversions (carrinho): quantidade de itens atribuíveis que foram adicionados ao carrinho de compras após ver ou clicar nos seus anúncios.
- checkout_conversions (checkout): quantidade de itens atribuíveis para os quais o processo de compra foi iniciado após ver ou clicar nos seus anúncios.
- leads_question_conversions: quantidade de potenciais clientes interessados em adquirir o seu produto que perguntaram na sua publicação após clicar nos seus anúncios.
- leads_im_conversions: quantidade de potenciais clientes interessados em adquirir o seu produto que entraram em contato pelo WhatsApp a partir da sua publicação após clicar nos seus anúncios.
- eshop_conversions: quantidade de vendas atribuídas.
competitive: array com métricas de competitividade. São mostradas apenas no nível de campanha e refletem sua distribuição de impressões, ou seja, são porcentagens relacionadas ao número de vezes que seus anúncios patrocinados foram mostrados ou não em relação a 100% das vezes em que poderiam ter sido mostrados. São calculadas com os dados dos últimos 7 dias. Em breve, será possível selecionar o período. As métricas podem ser:
- lost_impression_share_by_budget (Perdidas por orçamento): percentual de perda, entendendo como tal as impressões potenciais que não puderam ser capitalizadas por orçamento baixo. Por exemplo: se for 10, significa que a campanha perdeu impressões em 10% das vezes em que poderia tê-las, por não ter orçamento suficiente. Nestes casos, recomendamos aumentar o orçamento.
- lost_impression_share_by_ad_rank (Perdidas por ranking): percentual de perda, entendendo como tal as impressões potenciais que não puderam ser capitalizadas por ranking baixo. Por exemplo, se o resultado for 30, a campanha perdeu impressões em 30% das vezes em que poderia tê-las, por não ter ad-rank suficiente.
O adrank é composto pelo Acos Target e pelo Quality Score (métrica interna, não é gerenciável diretamente). Para melhorar as impressões ganhas por ranking, sugerimos focar nas seguintes ações:
Revisar o CPC máximo: o recomendável é que você esteja dentro da média de sua concorrência para melhores resultados.
Verificar se a campanha está segmentada nas palavras-chave corretas: recomendamos ter diferentes campanhas para focar em palavras-chave específicas em cada uma.
Melhorar a qualidade da publicação: a qualidade das fotos, a descrição do seu produto e até as condições de envio podem influenciar seu ranking.
Cuidar da reputação: o serviço pós-venda e a avaliação do produto podem fazer a diferença na concorrência. Saiba mais sobre a API de Qualidade de Publicações.
- impression_share (Impressões ganhas): percentual de sucesso, entendendo como tal as impressões efetivas, ou seja, o percentual de vezes que a campanha ganhou os leilões em que participou com aquela palavra-chave. É a quantidade de impressões obtidas dividida pela quantidade de impressões estimadas/potenciais que poderia ter tido. Por exemplo: se for 60%, significa que a campanha ganhou e foi exibida em 60% das vezes em que poderia ter sido.
- competitive_cpc: é o CPC da concorrência.
Seguinte: Display Ads.