Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Gerenciar sugestões de preços
As sugestões de preços no Mercado Livre são recomendações para ajudar os vendedores a definir preços competitivos. Baseadas em uma análise de preços atuais de produtos semelhantes, tanto na plataforma Mercado Livre quanto em outras, no histórico de vendas e na demanda, essas sugestões visam orientar o vendedor a estabelecer um preço atraente para os compradores. Isso aumenta as chances de venda e melhora o posicionamento nos resultados de busca.
Obter itens com sugestões de preços por vendedor
Devolve uma lista de items_id que tenham sugestões de preços para um seller_id específico.
Pré condições para obter sugestões de preços por vendedor
- Deve consultar sobre um usuário existente
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/suggestions/user/$USER_ID/items
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/suggestions/user/12345678/items
Resposta:
{
"total": 3,
"items": [
"MLM2098685855",
"MLM3092970874",
"MLM2081093293"
]
}
Campos da resposta:
A resposta de um GET ao recurso suggestions/user/$USER_ID/items fornecerá os seguintes parâmetros
- total: Quantidade total de itens com sugestões
- items: Lista de IDs de itens com sugestões.
Obter detalhe da sugestão de preços por item_id
Para consultar o preço sugerido para atribuir a um item específico, é necessário realizar um GET no recurso /suggestions/items/{itemId}/details
Pré condições para obter sugestões de preços
- Deve consultar sobre um item existente
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/suggestions/items/$ITEM_ID/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/suggestions/items/MLA12345678/details
Resposta:
{
"item_id": "MLM2077308861",
"status": "with_benchmark_highest",
"currency_id": "MXN",
"ratio": 0,
"current_price": {
"amount": 150000,
"usd_amount": 0
},
"suggested_price": {
"amount": 230,
"usd_amount": 0
},
"lowest_price": {
"amount": 230,
"usd_amount": 0
},
"costs": {
"selling_fees": 67.5,
"shipping_fees": 73
},
"applicable_suggestion": false,
"percent_difference": 100,
"metadata": {
"graph": [
{
"price": {
"amount": 50000,
"usd_amount": 0
},
"info": {
"title": "Mate De Test No Ofertar",
"sold_quantity": 0
}
}
],
"compared_values": 1
},
"promotion_detail": {
"unhealthy_reason": "no_sales",
"days_unhealthy": 30,
"campaign_start_date": "2024-06-16",
"campaign_end_date": "2024-07-20",
"promotion_id": "P-MLC13857010",
"discount_percent": 30,
"campaign_name": "UNHEALTHY_STOCK"
},
"last_updated": "01-08-2024 11:30:07"
}
Campos da resposta
A resposta de um GET para o recurso /suggestions/items/{{itemId}}/details fornecerá os seguintes parâmetros:
- item_id: Identificador do item
- status: Status da sugestão de preços em relação ao benchmark de concorrência. As possíveis sugestões de preço são:
- with_benchmark_highest: Se o preço atual do item for mais alto que o preço sugerido e o preço máximo de seus vizinhos
- with_benchmark_high : Se o preço atual do item for alto em relação ao sugerido
- no_benchmark_ok: Se o preço atual do item for igual ao sugerido
- no_benchmark_lowest: Se o preço atual do item estiver abaixo do sugerido
No caso de a sugestão vencedora ser do tipo Markdown, o preço da sugestão passa para os estados:
A maioria de nossas sugestões são baseadas em concorrência de preços. Ou seja, preço sugerido com base em concorrentes internos ou externos.
- not_optin_applied: Se a promoção não foi aplicada
- promotion_scheduled: Se a promoção foi optineada, mas ainda não chegou a data da promoção
- promotion_active: Se a promoção foi optineada e está dentro das datas em que a promoção se aplica
Nota:
Este é o único caso em que se utiliza uma estratégia de sugestão baseada em uma campanha promocional do tipo unhealthy. Seu objetivo é incentivar que o vendedor ative uma campanha naqueles itens que estão há muito tempo sem vendas. Ao criar a campanha, ela é automaticamente vinculada a uma oportunidade de ajuste de preço, o que gera uma sugestão do tipo markdown.
- currency_id: Identificador da moeda na qual os preços são expressos
- ratio: Relação entre o preço atual e o preço sugerido
- current_price: Preço atual do item.
- amount: Montante na moeda local.
- usd_amount: Montante em dólares americanos.
- suggested_price: Preço sugerido comparando com a concorrência.
- suggested_price_amount: Montante sugerido na moeda local.
- usd_amount: Montante sugerido em dólares americanos.
- lowest_price: Preço mínimo existente neste item
- amount: Preço expresso em moeda local
- usd_amount: Preço expresso em dólares
- costs: Custos relacionados à venda do item
- selling_fees: Custos pela venda do item.
- shipping_fees: Custos pelo envio do item.
- applicable_suggestion: Se a sugestão de preço é aplicável para este item ou não.
- percent_difference: Porcentagem de diferença entre o preço atual e o sugerido.
- metadata:
- graph: Lista de objetos que contêm detalhes de itens similares para comparar.
- price: Preço do item similar.
- amount: Preço na moeda local.
- usd_amount: Preço convertido para dólares americanos.
- info:
- title: Nome da publicação
- sold_quantity: Quantidade vendida do item
- compared_values: Quantidade de valores comparados.
- promotion_detail:
- unhealthy_reason:
- days_unhealthy: Quantidade de dias
- campaign_start_date: Data de início da campanha promocional.
- campaign_end_date: Data de fim da campanha promocional.
- promotion_id: Identificador único da promoção.
- discount_percent: Percentual de desconto que possui a promoção.
- promotion_name: Nome da campanha.
- unhealthy_reason:
- last_updated: Data da última sugestão de preço.
Possíveis erros ao consultar sugestões de preços de um item
Ao consultar a sugestão de preços de um item, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.
Response bad req:
{
"message": "client id not allowed",
"error": "",
"status": 400,
"cause": []
}
O item não pertence ao vendedor:
{
"message": "Caller is not the item's owner",
"error": "",
"status": 401,
"cause": []
}
Não autorizado:
{
"code": "unauthorized",
"message": "invalid access token"
}
Item consultado não possui sugestões:
{
"message": "item price suggestion not found, item id: [MLM2890672004], error: [kvs: key not found]",
"error": "",
"status": 404,
"cause": []
}
Próximo: Automatizações de preços