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 05/12/2023

Mercado Ads

Nota:
Esta funcionalidade está disponível apenas para integradores autorizados.

Esta API permite criar campanhas publicitárias para promover anúncios (publicações com publicidade) no Mercado Livre, a fim de obter mais visitas e vendas. Através doMercado Ads conseguirá potencializar o rendimento e incrementar vendas.


Limites de orçamento

Antes de criar uma campanha, conheça os limites de orçamento. Cada usuário tem um investimento mínimo e máximo associado a publicidade. Você pode escolher livremente seu investimento diário dentro desta faixa.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/budgets/limits?campaign_type=default

Resposta:

{
       "campaign_type": "default",
       "minimum": 100,
       "maximum": 50000,
       "maximum_percentage": 30,
       "minimum_percentage": 0.5,
       "recommended_minimum": 500
   }
  • campaign_type: tipo de campanha.
  • minimum: valor mínimo de investimento publicitário.
  • maximum: valor máximo de investimento publicitário.
  • maximum_percentage: porcentagem máxima.
  • minimum_percentage: porcentagem mínima.
  • recommended_minimum: mínimo recomendado.
Nota:
- Os valores estão expressos na moeda local.
- O orçamento deverá estar dentro desta faixa.
- Os valores dos limites são orçamentos válidos.
- Os limites podem mudar ao longo do tempo.

Criar uma campanha

Todos os anúncios devem estar agrupados em uma campanha cujo orçamento será repetido entre os anúncios inseridos nela.


Parâmetros

  • Budget: (obrigatório) deve estar dentro dos limites de orçamento do seu usuário
  • Status: (opcional) tem valor active por default.
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns
{
  "budget": 20,
  "status": "active"|"paused",
}

Resposta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:31:11.897Z",
    "date_created": "2018-08-23T18:31:11.897Z"
}

Modificar uma campanha

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID
{
  "status": "active"|"paused",
  "budget":225
}

Consultar uma campanha

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID

Exemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/223493019

Resposta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:56:33.000Z",
    "date_created": "2018-08-23T04:00:00.000Z"
}

Buscar campanhas por usuário

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=$USER_ID

Exemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=123456

Resposta:

{  
   "paging":{  
      "total":1,
      "offset":0,
      "limit":10
   },
   "results":[  
      {  
         "id":223703005,
         "name":"Campanha Principal",
         "user_id":301254033,
         "type":"default",
         "status":"active",
         "budget":225.0,
         "last_updated":"2018-08-24T04:00:00.000Z",
         "date_created":"2018-08-24T04:00:00.000Z"
      }
   ]
}

Métricas de campanha

Você pode consultar métricas de uma campanha com um intervalo de datas que não supere 90 dias.


Parâmetros obrigatórios

  • date_from: com formato aaaa-mm-dd, exemplo 2018-08-01
  • date_to: com formato aaaa-mm-dd, exemplo 2018-08-10
  • campaign_id: id da campanha

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD

Resposta:

{
  "id": 289823066,
  "clicks": 4315,
  "impressions": 532218,
  "ctr": 0.81,
  "cost": 26200.179999999993,
  "cpc": 6.07,
  "sold_quantity_direct": 237,
  "sold_quantity_indirect": 84,
  "sold_quantity_total": 321,
  "amount_direct": 182859.14,
  "amount_indirect": 74808.53,
  "amount_total": 257667.67,
  "advertising_fee": 10.17,
  "share": 10.89,
  "organic_sold_items_quantity": 2424,
  "sold_items_quantity_direct": 200,
  "sold_items_quantity_indirect": 77,
  "sold_items_conversion": 277
}

Campos de resposta

  • id id da campanha.
  • clicks quantidade de cliques que a campanha recebeu.
  • impressions quantidade de impressões no site que a campanha recebeu.
  • ctr: click through rate, expresso em porcentagem, a divisão entre cliques e impressões.
  • cost: é o custo total de cliques do período, em moeda loca.
  • cpc: é o custo médio de cada clique em moeda local.
  • sold_quantity_direct: quantidade de ventas diretas.
  • sold_quantity_indirect: quantidade de vendas assistidas.
  • sold_quantity_total: quantidade de vendas total.
  • amount_direct: soma do valor das vendas diretas obtidas através do Product Ads, em moeda loca. Ter uma venda direta signica que o usuário clicou no product ads e comprou este produto.
  • amount_indirect: soma do valor das vendas assistidas obtidas através da campanha, em moeda local. Uma venda assistida significa que um usuário clicou no Product Ads e comprou outro dos seus produtos.
  • amount_total: soma do valor das vendas obtidas através do Product Ads em moeda local.
  • advertising_fee: expresso em porcentagem, a divisão entre investimento em publicidade sobre os acessos obtidos, cost / amount_total. Um valor menor implica em um rendimento melhor.
    • share: porcentagem de vendas por publicidade sobre vendas totais.
  • organic_sold_items_quantity quantidade de vendas sem publicidade.
  • sold_items_quantity_direct quantidade de vendas diretas por publicidade.
  • sold_items_quantity_indirect quantidade de vendas indiretas por publicidade.
  • sold_items_conversion quantidade de vendas por publicidade.

Métricas de anúncios

Você pode consultar em uma mesma chamada, implementando multiget até 50 Product Ads. Também deve enviar um intervalo de datas que não supere 90 dias.


Parâmetros

  • date_from: campo obrigatório, com formato aaaa-mm-dd, exemplo 2018-08-01.
  • date_to: campo obrigatório, com formato aaaa-mm-dd, exemplo 2018-08-10.
  • campaign_id: campo obrigatório, id da campanha.
  • ids: campo obrigatório, lista de até 50 itens ids separados por vírgula, exemplo MLA1234, MLA4321.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD&ids=$ITEM_ID_1,$ITEM_ID_2

Resposta:

[{
	"id": "MLA1275028260",
	"clicks": 0,
	"impressions": 0,
	"cost": 0.0,
	"cost_usd": 0.0,
	"cpc": 0.0,
	"cpc_usd": 0.0,
	"ctr": 0.0,
	"sold_quantity_direct": 0,
	"sold_quantity_indirect": 0,
	"sold_quantity_total": 0,
	"amount_direct": 0.0,
	"amount_indirect": 0.0,
	"amount_total": 0.0,
	"amount_direct_usd": 0.0,
	"amount_indirect_usd": 0.0,
	"amount_total_usd": 0.0,
	"advertising_fee": 0.0,
	"organic_orders_quantity": 0,
	"share": 0.0,
	"organic_sold_items_quantity": 0,
	"sold_items_quantity_direct": 0,
	"sold_items_quantity_indirect": 0,
	"sold_items_conversion": 0
}]

Campos da resposta

  • id id do anúncio.
  • impressions: quantidade de impressões no site que teve o Product Ads.
  • clicks: quantidade de clique que o Product Ads recebeu.
  • ctr: click through rate, expresso em porcentagem, a divisão entre cliques e impressões.
  • cost: é o custo total de cliques do período, em moeda local.
  • cpc: é o custo médio de cada clique, em moeda local.
  • sold_quantity_direct: quantidade de vendas diretas com Product Ads.
  • sold_quantity_indirect: quantidade de vendas assistidas com Product Ad.
  • sold_quantity_total: quantidade de vendas total com Product Ads.
  • amount_direct: soma do valor das vendas diretas obtidas do Product Ads, em moeda local.
  • amount_indirect: soma do valor das vendas assistidas obtidas do Product Ads, em moeda local.
  • amount_total: soma do valor das vendas obtidas através dos seus Product Ads, em moeda local.
  • advertising_fee: expresso em porcentagem, a divisão entre investimento em publicidade sob os acessos obtidos.
  • organic_orders_quantity: quantidade de unidades vendidas sem publicidade.
  • share: porcentagem de vendas por publicidade sobre vendas totais.
  • organic_sold_items_quantity: quantidade de vendas sem publicidade.
  • sold_items_quantity_direct: quantidade de vendas diretas por publicidade.
  • sold_items_quantity_indirect: quantidade de vendas indiretas por publicidade.
  • sold_items_conversion: quantidade de vendas por publicidade.

Consultar anúncio asosciado a um item

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

Resposta:

{
    "id": "MLA657316800",
    "campaign_id": 141072850,
    "user_id": 246460082,
    "site_id": "MLA",
    "status": "active",
    "title": "Item de Teste",
    "price": 200,
    "currency_id": "ARS",
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-657316800-item-de-testeo_JM"
    "thumbnail": "http://mla-s2-p.mlstatic.com/471325-MLA25424154856_032017-I.jpg",
    "picture_id": "471325-MLA25424154856_032017",
    "date_created": "2017-03-10T02:27:32.325+0000",
    "last_updated": "2017-03-10T02:27:32.325+0000"
}

Editar estado do anúncio

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
  "status": "paused" | "active"
}

Buscar anúncios por usuários

Parâmetros

  • user_id: obrigatório.
  • status: opcional, é o status dos Product Ads.
  • title: opcional, são palavras incluídas no título do Product Ads.
  • campaigns: opcional, recebe um campaign id.
  • offset y limit: opcionais. O limit não poderá ser maior que 100.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

Buscar +10.000 anúncios por usuário

Para aqueles usuários com busca de mais 10.000 anúncios, você terá uma nova forma de consultar.


1. Realizar a priimeira busca normalmente:


Parâmetros obrigatórios

  • user_id: id do usuário, tipo long.
  • site_id: site do país do usuário, tipo string.
  • limit: limite de resultados por busca, tipo integer.

Parâmetro opcional

channel: canal do item (marketplace/mshops) – Por default é marketplace, tipo string.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

Resposta:

{
   "results": [
       {
           "id": "MLA000000000",
           "campaign_id": 10000000,
           "user_id": 10000000,
           "site_id": "MLA",
           "cpc": 0.01,
           "status": "active",
           "title": "Description",
           "price": 100.45,
           "currency_id": "USD",
           "permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
           "thumbnail": "http://mla-s2-p.mlstatic.com/test.jpg",
           "picture_id": "ABCD_12345_ZYX",
           "channel": "marketplace",
           "date_created": "2022-05-07T21:11:05.000-04:00",
           "last_updated": "2022-11-22T11:22:20.000-04:00"
       }
   ],
   "paging": {
           "offset": 0,
           "last_item_id": "MLA000000001",
           "total": 12,
           "limit": 1
   }
}

Campos da resposta

Contém a quantidade de itens definida por limit.

  • total: total de elementos que o usuário possuí.
  • limit: quantidade de elementos por página de busca.
  • last_item_id: último item_id da lista que servirá para a próxima petição e começa a mostrar os seguintes elementos dependendo do limite especificado.

2. Identificar o last_item_id (último item_id da lista) que servirá para a próxima petição.


3. Fazer a segunda busca com o último item da lista como elemento pivote para a seguinte página de resultados. Para esta busca não deve enviar o parámetro offset, dado que se o enviar junto ao last_item_id, produzirá um erro.


Parámetros obligatorios

  • user_id: id do usuário, tipo long.
  • site_id: site do país do usuário, tipo string.
  • limit: limite de resultados por busca, tipo integer.
  • last_item_id: último item lista que servirá como elemento pivote para a seguinte página de resultados. Se não o colocar, voltará ao começo da lista. Tipo string.

Parâmetro opcional

channel: canal do item (marketplace/mshops) – Por default é marketplace, tipo string.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE&last_item_id=$LAST_ITEM_ID