Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.Documentação do
Product Ads
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.
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