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 13/09/2024

Product Ads

Importante:
- Product Ads está habilitado para produtos do Mercado Livre e Mercado Shops.
- Em breve, avisaremos a data de desativação da versão antiga do Product Ads. Desenvolva esta nova versão agora.

Com os seguintes endpoints de Product Ads, você pode monitorar campanhas, anúncios e métricas. Existem dois tipos de gerenciamento de anúncios em Product Ads.

  • Automático: Product Ads escolhe publicações com bom nível de vendas no Mercado Livre e as exibe nos primeiros locais dos resultados da pesquisa. Você pode adicionar ou remover anúncios da sua campanha manualmente. Ao começar a usar Product Ads, você usará o modo automático por padrão.
  • Personalizado: você pode criar múltiplas campanhas para agrupar seus anúncios, atribuir e configurar o orçamento e objetivo de cada uma. Esta é a forma ideal de gerenciar seus anúncios, pois permite que você tenha mais controle sobre suas campanhas e faça ajustes de acordo com seu desempenho.

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_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=PADS

Resposta:

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

Nota:
Se você receber o erro 404 - No permissions found for user_id, significa que o usuário não tem o Produto habilitado. O usuário deve acessar Mercado Livre > Meu perfil > Publicidade.

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_ID

Resposta:

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

Nota:
- Para todos os endpoints de métricas, você pode aplicar o intervalo de datas de 90 dias para trás.
- As informações para validar as métricas são atualizadas às 10:00 hrs GMT-3.
- Só é possível solicitar um aggregation_type por vez.

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_amount

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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

Resposta:

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