Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Product Ads
Consultar anunciante
Anunciantes (advertiser_id) são aqueles que investem um orçamento para a criação e distribuição de anúncios publicitários, com o objetivo de promover os seus produtos ou serviços. Consulte a lista de anunciantes que têm acesso a um usuário, dependendo do tipo de produto requerido.
Parâmetros obrigatórios
product_id: tipo de produto. Valores disponíveis: PADS (Product Ads), 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=PADSResposta:
{
"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.
Detalhe de um anúncio
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_IDResposta:
{
"item_id": "MLM12345678",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "X",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "223",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-1111.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM111111-2222-3333-4kuhd-_JM",
"recommended": false,
"metrics_summary": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}Métricas de campanhas
Parâmetros opcionais
limit: limite de elementos a serem mostrados.
offset: atributo de paginação dos resultados, permite percorrer as páginas da lista a partir do 0 até o múltiplo do total de elementos com o limite por página.
date_from: data desde (YYYY-MM-DD). É validado se estiver presente ao solicitar metrics.
date_to: data até (YYYY-MM-DD). É validado se estiver presente ao solicitar metrics.
metrics: lista separada por vírgula (Por exemplo, clicks, prints). Indica os campos que serão retornados na resposta. Valores possíveis:
- clicks, prints, ctr, cost, cost_usd, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount
aggregation: agregação pela qual os resultados serão apresentados. Padrão: sum.
aggregation_type: Tipo de agregação em que os resultados serão apresentados. Padrão: campaign.
metrics_summary: solicita a sumarização das métricas. Deve ser usado em conjunto com metrics. Por padrão, false.
Filtros disponíveis
Para utilizar os filtros, você deve seguir a estrutura ?filters[nome do filtro]= valor.
campaign_ids: filtro por ids de campanhas separados por vírgula.
campaign_id: filtro por id de uma campanha, obtêm-se todos os itens que estiveram na campanha para o intervalo de datas.
status: estado das campanhas, separado por vírgula. Valores disponíveis: active, paused, deleted.
channel: canal das campanhas. Pode ser marketplace ou mshops.
Pesquisa e métricas de todas as campanhas
Obtenha todas as campanhas de um anunciante e também suas métricas correspondentes.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amountResposta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 1
},
"results": [
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}
]
}Métricas diárias de campanhas
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=2&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILYResposta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 2
},
"results": [
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
},
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
]
}Métricas sumarizadas de campanhas
Utilize o mesmo endpoint para consultar métricas de campanhas adicionando o parâmetro metrics_summary=true.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&metrics_summary=trueResposta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 1
},
"results": [
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}
],
"metrics_summary":
{
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}Detalhes e métricas de uma campanha
Parâmetros opcionais
date_from: data desde (YYYY-MM-DD). É validado se estiver presente ao solicitar metrics.
date_to: data até (YYYY-MM-DD). É validado se estiver presente ao solicitar metrics.
metrics: lista separada por vírgula (Por exemplo, clicks, prints), indica os campos que serão retornados na resposta. Valores disponíveis:
- clicks, prints, ctr, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount, impression_share, top_impression_share, lost_impression_share_by_budget, lost_impression_share_by_ad_rank, acos_benchmark.
aggregation: agregação pela qual os resultados serão apresentados. Padrão: sum.
aggregation_type: tipo de agregação em que os resultados serão apresentados. Padrão: campaign.
Filtros disponíveis
channel: canal das campanhas. Pode ser marketplace ou mshops.
Exemplo:
curl GET -H 'api-version: 2' -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/campaigns/$CAMPAIGN_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount,impression_share,top_impression_share,lost_impression_share_by_budget,lost_impression_share_by_ad_rank,acos_benchmarkResposta:
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
"impression_share": 0,
"top_impression_share": 0,
"lost_impression_share_by_budget": 0.01,
"lost_impression_share_by_ad_rank": 0.01,
"acos_benchmark": 123
}
}Métricas diarias de una campaña
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/campaigns/$CAMPAIGN_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount,impression_share,top_impression_share,lost_impression_share_by_budget,lost_impression_share_by_ad_rank,acos_benchmark&aggregation_type=DAILYResposta:
{
[
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
"impression_share": 0,
"top_impression_share": 0,
"lost_impression_share_by_budget": 0.01,
"lost_impression_share_by_ad_rank": 0.01,
"acos_benchmark": 123
}
]
}Métricas de anúncios
Parâmetros opcionais
limit: limite de elementos a serem mostrados.
offset: atributo de paginação dos resultados, permite percorrer as páginas da lista a partir do 0 até o múltiplo do total de elementos com o limite por página.
date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos.
date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos.
metrics: lista separada por vírgula (Por exemplo, clicks, prints), indica os campos que serão retornados na resposta. Valores possíveis:
- clicks, prints, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount.
sort: ordenamento da consulta, asc e desc.
sort_by: nome do atributo pelo qual será feita a ordenação.
aggregation: agregação pela qual os resultados serão apresentados. Padrão: sum.
aggregation_type: tipo de agregação em que os resultados serão apresentados: diário, item. Padrão: item.
metrics_summary: sumariza as métricas e deve ser usado em combinação com metrics. Padrão: false.
Filtros disponíveis
Para utilizar os filtros, você deve seguir a estrutura ?filters[nome do filtro]= valor.
item_id: Id do anúncio. Um ou mais, separados por vírgula.
statuses: status dos anúncios. Valores disponíveis: active, paused, hold, idle, delegated, revoked geralmente filtrado por active, paused e idle.
- hold: o item está desabilitado na publicidade, isso resulta em o item no nível do marketplace estar pausado ou sem estoque.
- idle: o item está disponível para publicidade, mas não está em nenhuma campanha de publicidade.
- delegated: significa que, para o proprietário que consulta o item, ele está delegado a outro anunciante. Ou seja, embora o proprietário (vendedor) possa ser o dono do item, ele não tem mais autoridade para operar sobre ele porque eles estão "emprestados" a outro anunciante.
- revocado: significa que, para o anunciante a quem os itens foram emprestados, este anunciante os devolveu ao proprietário, então ele não tem mais autoridade para operar sobre esses itens.
channel: canal de venda 'marketplace' (Mercado Livre) ou 'mshops' (Mercado Shops).
price: preço.
buy_box_winner: o item associado é o vencedor do Catálogo. Valores disponíveis: true ou false. Saiba mais sobre Competição no Catálogo.
condition: condição do item associado.
current_level: reputação do item associado.
deferred_stock: estoque do item associado.
domains: domínio do item associado.
logistic_types: tipo de logística do item associado.
listing_types: tipo de listagem do item associado.
official_stores: loja oficial do item associado.
recommended: o anúncio é recomendado pelos Product Ads. De acordo com nossos modelos, ele tem bom desempenho e, se a publicidade for ativada, as vendas serão potencializadas.
campaign_id: obtenha todos os anúncios que tiveram uma campanha em um período de tempo.
campaigns: listagem de campanhas separadas por vírgula.
brand_value_id: identificador de marca.
brand_value_name: nome da marca.
Pesquisa e métricas de todos os anúncios
Obtenha todos os anúncios e as métricas correspondentes a eles.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amountResposta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"item_id": "MLM12345678",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "active",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA111111_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-12345678-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
]
}Métricas diárias de anúncios
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILYResposta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"date": "2023-01-01",
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
]
}Métricas sumarizadas de anúncios
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&metrics_summary=trueResposta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"item_id": "MLM2945612374",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "delegated",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA74798069591_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-2945696974-pantalla-samsung-led-smart-tv-de-65-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
],
"metrics_summary": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}Métricas de um anúncio
Parâmetros opcionais
date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos.
date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos.
metrics: lista separada por vírgula (Por exemplo, clicks, prints). Indica os campos que serão retornados na resposta. Valores possíveis:
- clicks, prints, ctr, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount.
aggregation: agregação pela qual os resultados serão apresentados. Padrão: sum.
aggregation_type: tipo de agregação em que os resultados serão apresentados: diário, item. Padrão: item.
channel: canal do item, mshops ou marketplace. Valor padrão: marketplace.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amountResposta:
{
"item_id": "MLM2945612374",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "X",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA74798069591_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-2945696974-pantalla-samsung-led-smart-tv-de-65-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics_summary": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}Métricas diarias de un anuncio
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILYResposta:
{
"results": [
{
"date": "2023-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
]
}Glossário
total: total de registros obtidos.
offset: valor padrão: 0.
limit: limites de elementos na lista de campanhas. Padrão: 50.
results: resultados obtidos.
id: identificador do anúncio ou campanha.
budget: média diária do orçamento (mensal) da campanha, ou seja, caso o orçamento não seja consumido durante o dia, o orçamento restante será utilizado nos dias seguintes até o final do mês.
last_updated: data da última modificação da campanha.
date_created: data de criação da campanha.
price: preço do artigo associado.
title: nome da publicação.
has_discount: se tem desconto. Este valor é identificado com base na diferença entre os campos "regular amount" e "amount" fornecidos pela API de Preços.
catalog_listing: é uma publicação de catálogo.
logistic_type: tipo de logística para o envio do anúncio.
listing_type_id: identificador do tipo de publicação.
domain_id: domínio.
date_created: data de criação do anúncio.
official_store_id: identificador da loja oficial.
buy_box_winner: é vencedor de Catálogo.
channel: canal da campanha (pode ser marketplace ou mshops).
campaign_id: identificador da campanha.
condition: condição da publicação.
current_level: reputação.
deferred_stock: estoque de produto disponível. Um item com manufacturing_time (tempo de disponibilidade) faz com que o anúncio não seja exibido, priorizando-se então os anúncios que tenham estoque imediato.
thumbnail: link para a imagem em miniatura.
permalink: link para a publicação.
brand_value_id: identificador da marca associada ao item.
brand_value_name: nome da marca associada ao item.
status: estado do anúncio ou campanha.
recommended: o anúncio é recomendado.
metrics: métricas do artigo ou campanha.
clicks: cliques da campanha.
prints: quantidade de impressões (vezes em que o anúncio é exibido).
sov: percentual de vendas por publicidade sobre vendas totais.
clicks: cliques da campanha.
ctr: taxa de cliques.
cost: investimento da campanha.
cpc: custo por clique.
acos: percentual de investimento em publicidade sobre as receitas obtidas.
Vendas sem publicidade
- organic_units_quantity: quantidade de unidades vendidas sem publicidade
- organic_units_amount: valor de vendas de pedidos orgânicos.
- organic_items_quantity: quantidade de vendas sem publicidade.
Vendas com publicidade
- Vendas diretas
- direct_items_quantity: quantidade de vendas diretas por publicidade.
- direct_units_quantity: quantidade de unidades vendidas em vendas diretas.
- direct_amount: valor total das vendas diretas obtidas do seu Product Ad, em moeda local.
- Vendas indiretas
- indirect_items_quantity: quantidade de vendas indiretas por publicidade.
- indirect_units_quantity: quantidade de unidades vendidas em vendas assistidas.
- indirect_amount: valor total das vendas assistidas obtidas do seu Product Ad, em moeda local.
advertising_items_quantity: quantidade de vendas por publicidade.
cvr: taxa de conversão.
roas: retorno sobre o gasto publicitário.
units_quantity: quantidade de vendas totais.
total_amount: valor total das vendas obtidas do seu Product Ad, em moeda local.
impression_share: percentual de vezes que os anúncios são exibidos considerando todas as vezes que podem ser exibidos.
top_impression_share: quantidade de leilões ganhos nas primeiras posições da pesquisa em relação à quantidade de leilões em que pôde participar.
lost_impression_share_by_budget: percentual de vezes que os anúncios não são exibidos, considerando todas as vezes que poderiam ser exibidos e que não ocorreu porque o orçamento é muito baixo.
lost_impression_share_by_ad_rank: percentual de vezes que os anúncios não são exibidos, considerando todas as vezes que podem ser exibidos e que não ocorreu porque sua classificação é mais baixa do que outros vendedores.
acos_benchmark: o ACOS alvo usado por anúncios com bons resultados em impressões e vendas.
picture_id: id da imagem do artigo no nível Mercado Livre.
acos_target: custo publicitário de vendas (ACOS) target utilizado por anúncios com bons resultados em impressões e vendas.
strategy: tipo de estratégia de campanha. Pode ser PROFITABILITY, INCREASE e VISIBILITY.
acos_top_search_target: objetivo ACOS (custo publicitário de vendas) definido para uma campanha com o objetivo de ofertar especificamente para os primeiros resultados de pesquisa. Para outros leilões, será considerada a oferta do ACOS alvo. Deve ser superior ao ACOS alvo da campanha e inferior a 500.