Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Gerenciar promoções
Com o recurso /seller-promotions você pode centralizar todos os tipos de promoções disponíveis como Campanhas tradicionais (DEAL), Campanhas com participação do Mercado Livre (MARKETPLACE_CAMPAIGN), Descontos individuais (PRICE_DISCOUNT), Ofertas relâmpago (LIGHTNING), Ofertas do dia (DOD), Desconto por volume (VOLUME), desconto pré-acordado por item (PRE NEGOTIATED), campanha do vendedor (SELLER_CAMPAIGN), campanhas com co-participação automatizada (SMART), campanha de preços competitivos (PRICE_MATCHING), campanha de liquidação de estoque Full (UNHEALTHY_STOCK) e campanhas de cupons do vendedor (SELLER_COUPON_CAMPAIGN). Além dos novos tipos de ofertas que disponibilizamos.
Características das promoções
| Nome da campanha | Tipo da campanha | Definição de preço | Sugestão de preço | Bonificação MELI | Stock para participar | Deadline | Aprovação |
|---|---|---|---|---|---|---|---|
| Tradicional | DEAL | Usuário define | Não | Não | Não | Sim | Sim |
| Campanhas com co-participação | MARKETPLACE CAMPAIGN | Usuário aceita | Não | Sim | Não | Sim | Não |
| Desconto por volume | VOLUME | Usuário aceita | Não | Sim | Não | Sim | Não |
| Oferta do dia | DOD | Usuário define | Sim | Não | Sim, informativo | Não | Não |
| Oferta relâmpago | LIGHTNING | Usuário define | Sim | Não | Sim, obrigatório | Não | Não |
| Desconto pré-acordado por item | PRE_NEGOTIATED | Usuário concordar e aceita | Não | Sim | Sim | Sim | Não |
| Campanha do vendedor | SELLER CAMPAIGN | Usuário define e aceita | Não | Não | Não | Sim | Não |
| Campanhas com co-participação automatizada | SMART | Usuário aceita | Não | Sim | Não | Sim | Não |
| Campanha de preços competitivos | PRICE_MATCHING | Usuário aceita | Não | Sim | Não | Sim | Não |
| Campanha de liquidação de estoque Full | UNHEALTHY_STOCK | Usuário concordar e aceita | Não | Sim | Sim | Sim | Não |
Disponibilidade por país
| Site | Campanha
tradicional (DEAL) |
Campanha com co-participação
(MARKETPLACE CAMPAIGN) |
Desconto individual
(PRICE DISCOUNT) |
Desconto por volume
(VOLUME) |
Desconto pré-acordado por item
(PRE_NEGOTIATED) |
Oferta do dia
(DOD) |
Oferta relâmpago
(LIGHTNING) |
Campanhas com co-participação automatizada
(SMART) |
Campanha de preços competitivos
(PRICE_MATCHING) |
Campanha de liquidação de estoque Full
(UNHEALTHY_STOCK) |
Campanha do vendedor
(SELLER_CAMPAIGN) |
|---|---|---|---|---|---|---|---|---|---|---|---|
| MLA, MLB, MLM, MCO, MLC, MLU, MPE. | |||||||||||
| MLV e MEC |
Promoções do vendedor
Lembre-se de que um usuário pode ter mais de um convite e de diferentes tipos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/$USER_ID?app_version=v2'Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/1356551933?app_version=v2'Resposta:
{
"results": [
{
"id": "P-MLB1806015",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2023-04-20T02:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Campanha de teste v2",
"benefits": {
"type": "REBATE",
"meli_percent": 5,
"seller_percent": 25
}
},
{
"id": "P-MLB1806017",
"type": "VOLUME",
"status": "started",
"start_date": "2023-04-20T03:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Leva 3 paga 2",
"benefits": {
"type": "VOLUME",
"meli_percent": 9.9999,
"seller_percent": 23.3331,
"name": "3x2",
"buy_quantity": 3,
"pay_quantity": 2,
"item_discount_percent": 33.333
}
},
{
"id": "P-MLB1806019",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-20T03:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "deals de teste v2"
},
{
"id": "P-MLB1809008",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-21T21:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Deals de test v2"
},
{
"id": "P-MLB1809009",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-21T23:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "campanha de teste tahi"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 5
}
}Campos de resposta
id: código de identificação da promoção.
type: tipo de oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
status: estados.
start_date: data de início da promoção.
finish_date: data de fim da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da oferta.
name: nome da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da promoção.
benefits: configurações de benefícios de promoção.
Itens candidatos
O recurso /seller-promotions/candidates permite identificar os itens convidados a fazer parte de uma promoção. Sempre que um item passa a ter o status candidate em uma promoção é enviada uma notificação com o candidate_id>, com esse recurso é possível identificar o item, a promoção e o status.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2Resposta:
{
"id": "CANDIDATE-MLB1254949426-803130663",
"item_id": "MLB1254949426",
"promotion_id": "P-MLB4629001",
"type": "MARKETPLACE_CAMPAIGN",
"status": {
"id": "candidate"
}
}Campos da resposta
id: código de identificação do candidato.
item_id: item associado ao candidato.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
status: status do candidato.
Consultar Ofertas
O recurso /seller-promotions/offers> permite identificar as alterações que ocorreram na oferta de um item. Todas as alterações são enviadas por meio de notificações com o offer_id, com esse recurso é possível identificar o item, a promoção e o estado.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2Resposta:
{
"id": "OFFER-MLB1970246686-42701792",
"item_id": "MLB1970246686",
"promotion_id": "P-MLB3329001",
"type": "DEAL",
"status": {
"id": "ACTIVE"
}
}Campos da resposta
id: código de identificação da oferta.
item_id: item associado a oferta.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
status: status da oferta (programmed, active, e inactive).
Consultar os detalhes da promoção
Realize a seguinte consulta para acessar os detalhes específicos de uma campanha tradicional, uma campanha com participação Mercado Livre e para os descontos por volume.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$PROMOTION_TYPE&app_version=v2'Para obter mais informação, acesse as documentações por campanha.
Estados
Abaixo você encontra os possíveis estados para diferentes tipos de promoções:
- Estado de uma campanha tradicional
- Estado de uma campanha com participação do Mercado Livre
- Estado de campanha desconto por volume
- Estado da campanha com desconto pré-acordado por item
Consultar itens da promoção
Para conhecer os itens que fazem parte de uma determinada promoção pode-se fazer a seguinte consulta:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTION_TYPE&app_version=v2'
Além disso, você pode consultar os itens de uma campanha.
Filtros
Você pode aplicar filtros por item ou status.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2
Exemplo de filtro por item:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000&app_version=v2
Resposta:
{
"results": [
{
"id": "MLA604400000",
"status": "started",
"price": 23968,
"original_price": 28549
}
],
"paging": {...}
}Exemplo de filtro por status started:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2
Resposta:
{
"results": [
{
"id": "MLA639970000",
"status": "started",
"price": 4037,
"original_price": 4427
},
{
"id": "MLA639973333",
"status": "started",
"price": 6007,
"original_price": 6587
},
],
"paging": [...]
}Paginação
Para realizar a paginação você deve usar o parâmetro de search_after.
Na resposta GET, devolvemos o parâmetro searchAfter, que será utilizado para recorrer aos resultados. É necessário recuperar este ID e efetuar o seguinte request com o query param search_after={search_after}. Este ID é um string, por isso devem aceitar string e utilizá-lo mais tarde nas suas chamadas.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'Exemplo de paginação:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB13451002MLB9377/items?promotion_type=DEAL&app_version=v2&limit=50&search_after=d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca1b1a42'Resposta:
"results": [
{
"id": "MLB2674512266",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506199",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506138",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505931",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505924",
"status": "candidate",
"price": 0,
"original_price": 0
[…]
"paging": {
"searchAfter":
"d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55",
"limit": 50,
"total": 14424
}
}Considerações
- Será retornado earch_after em todas as páginas, exceto na última página.
- A única forma de avançar na resposta (paginar) é através da utilização deste parâmetro.
- Ao iterar os resultados, cada chamada devolverá o search_after que deve ser utilizado na chamada seguinte.
- Utilize sempre o search_after que foi oferecido pela resposta ao request, que pode mudar e expirar (têm um TTL de 5 minutos).
- Não é possível efetuar a paginação para trás.
Como participar
Você pode participar de diversos tipos de promoções e até oferecer um desconto individual para itens:
- Indicando itens para uma campanha tradicional.
- Indicando itens para uma campanha com participação do Mercado Livre.
- Indicando items para desconto por volume.
- Aceitando desconto pré-acordado por item.
- Indicando itens para una oferta del dia.
- Indicando itens para uma oferta relâmpago.
- Oferecendo um desconto individual para uma publicação.
- Indicando itens para una campanha do vendedor.
- Indicando itens para uma campanha Smart.
Consultar as promoções de itens
Aqui você pode obter todas as promoções que o item possuí e os estados das promoções no momento da consulta.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2Resposta:
[
{
"type": "PRICE_DISCOUNT",
"status": "candidate",
"price": 4000,
"start_date": "2023-04-26T00:00:00",
"finish_date": "2023-05-10T00:00:00"
},
{
"type": "DOD",
"status": "candidate",
"price": 4000,
"start_date": "2023-04-28T00:00:00",
"finish_date": "2023-04-28T23:59:59"
},
{
"id": "P-MLB1817004",
"type": "MARKETPLACE_CAMPAIGN",
"status": "pending",
"start_date": "2023-04-27T23:00:00Z",
"finish_date": "2023-06-01T02:00:00Z",
"deadline_date": "2023-06-01T01:00:00Z",
"name": "Campanha teste 10",
"benefits": {
"type": "REBATE",
"meli_percent": 3,
"seller_percent": 27
}
},
{
"id": "MLB1345",
"type": "DEAL",
"status": "pending",
"start_date": "2023-04-27T23:00:00-03:00",
"finish_date": "2023-05-31T23:00:00-03:00",
"name": "teste 20"
},
{
"id": "C-MLB300",
"type": "SELLER_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"status": "started",
"price": 4250,
"top_price": 3500,
"start_date": "2023-04-27T00:00:00",
"finish_date": "2023-05-05T23:59:59",
"name": "camp del seller 1"
},
{
"id": "P-MLB1812010",
"type": "SMART",
"status": "started",
"name": "test-smart-2",
"offers": [
{
"id": "OFFER-MLB3538191898-177685",
"original_price": 5000,
"new_price": 3000,
"prime_price": null,
"status": "active",
"start_date": "2023-04-26T11:40:00Z",
"end_date": "2023-05-30T15:47:00Z",
"benefits": {
"type": "REBATE",
"meli_percent": 20,
"seller_percent": 20
}
}
]
},
{
"id": "C-MLB302",
"type": "SELLER_CAMPAIGN",
"sub_type": "FLEXIBLE_PERCENTAGE",
"status": "candidate",
"start_date": "2023-04-27T12:04:00",
"finish_date": "2023-05-05T00:00:00",
"name": "camp del seller 2"
}
]Modificar itens
Para modificar os itens que estão participando de uma oferta, pode fazer isso da seguinte maneira:
- Modificar itens de uma campanha tradicional.
- Modificar itens de uma campanha com participação do Mercado Livre.
- Modificar itens de uma campanha com desconto por volume.
Delete massivo de ofertas
É possível eliminar em massa todas as ofertas que estão no item.
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2Exemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA1399846831?app_version=v2Resposta:
{
"successful_ids": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": null
},
{
"offer_id": "OFFER-MLA1399846831-10000081567",
"error": null
}
],
"errors": []
}Em casos que o item tenha campanhas que não podem ser deletadas de forma massiva, a chamada terá uma resposta http 200, porém o response irá conter as mensagens de erros.
Exemplo onde nenhuma oferta pode ser eliminada:
{
"successful_ids": [],
"errors": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": "The offer of type DOD not allowed for delete."
},
{
"offer_id": "OFFER-MLA1399846831-10000081828",
"error": "The offer could not be deleted. Try again."
}
]
}Exemplo onde as ofertas foram eliminadas corretamente e também ocorreram erros:
{
"successful_ids": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": null
},
{
"offer_id": "OFFER-MLA1399846831-10000081417",
"error": null
}
],
"errors": [
{
"offer_id": "OFFER-MLA1399846831-10000081418",
"error": "The offer of type DOD not allowed for delete."
},
{
"offer_id": "OFFER-MLA1399846831-10000081419",
"error": "The offer could not be deleted. Try again."
}
]
}Possíveis erros
423_ENTITY_LOCKED: A solicitação não pôde ser processada porque o item está temporariamente bloqueado para realizar solicitações. A solicitação pode ser tentada novamente após alguns segundos.
400_BAD_REQUEST: Quando o formato do item é inválido.
Eliminar itens
Com este recurso é possível eliminar uma oferta do item antes que o prazo acabe:
- Eliminando itens de uma campanha tradicional.
- Eliminando itens de uma campanha com participação do Mercado Livre.
- Eliminando itens em uma campanha de desconto por volume.
- Eliminando desconto pré-acordado por item.
- Eliminando itens em uma oferta do dia.
- Eliminando itens em uma oferta relâmpago.
- Eliminando desconto individual para um item.
Campanha de teste
Para fazer testes com campanhas teste, envie os dados de seu usuário e/ou itens no seguinte suporte.
Lembre-se de que os usuários quanto itens devem ser testes.
Próxima: Campanhas tradicionais