Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 05/12/2023

Desconto pré-acordado por item e campanha de liquidação de estoque Full

Importante:

- A partir de 10 de janeiro de 2024 eliminaremos a versão anterior do recurso /seller-promotions.
- Para obter a resposta com a nova versão envie a query param app_version=v2. Consulte a documentação de cada campanha para conhecer as mudanças.
- Estas campanhas estão na mesma documentação porque trabalham com a mesma l'gica e os mesmos parametros.

Os vendedores são convidados periodicamente a participar nas diversas campanhas que são realizadas no site.
Desconto pré-acordado por item: neste tipo de campanha, o vendedor faz um pré-acordo de desconto para determinados itens com um agente comercial do Mercado Livre, onde são estabelecidos o preço, o desconto oferecido e o benefício concedido.
Campanha de liquidação de estoque Full este tipo de campanha é muito similar a campanha de desconto pré-acordado por item, mas com a diferença que é somente para itens de Full.
Se o vendedor recebeu um convite e deseja participar, você pode fazê-lo com os seguintes recursos.

Visão do vendedor

Consultar detalhes de uma campanha

Exemplo de desconto pré-acordado:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/P-MLM394001?promotion_type=PRE_NEGOTIATED&app_version=v2

Resposta de desconto pré-acordado:

{
   "id": "P-MLM394001",
   "type": "PRE_NEGOTIATED",
   "status": "started",
   "start_date": "2021-03-30T18:30:15.525Z",
   "finish_date": "2021-12-27T17:59:59.525Z",
   "deadline_date": "2021-05-27T17:59:59.525Z",
   "name": "Prueba descuento x item sin benefit",
   "offers": [
       {
           "id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
           "original_price": 101,
           "new_price": 21,
           "status": "active",
           "start_date": "2021-05-10T16:00:00Z",
           "end_date": "2021-05-11T15:00:00Z",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 9.9,
               "seller_percent": 69.3
           }
       }
   ]
}

Exemplo de liquidação de estoque Full:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB12345?promotion_type=PRE_NEGOTIATED&app_version=v2'

Resposta de liquidação de estoque Full:

{
   "id": "P-MLB12345",
   "type": "UNHEALTHY_STOCK",
   "status": "started",
   "start_date": "2023-08-30T18:30:15.525Z",
   "finish_date": "2023-12-27T17:59:59.525Z",
   "deadline_date": "2023-09-27T17:59:59.525Z",
   "name": "Prueba liquidación stock Full",
   "offers": [
       {
           "id": "MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
           "original_price": 101,
           "new_price": 21,
           "status": "active",
           "start_date": "2023-09-10T16:00:00Z",
           "end_date": "2021-09-11T15:00:00Z",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 9.9,
               "seller_percent": 69.3
           }
       }
   ]
}

Campos específicos destas campanhas

Offers: detalhe do desconto pré-acordado

id: id da oferta.

original_price: preço original do item.

new_price: preço final do item.

status: status do item na promoção.

start_date: data de início da oferta na promoção.

end_date: data de término da oferta na promoção.

Benefits: detalhe dos benefícios da promoção.

type: tipo de benefício.
meli_percent: porcentagem de contribuição do Mercado Livre.
seller_percent: porcentagem de contribuição do vendedor.

Estados de campanha

Esses são os diferentes status pelos quais estas campanhas podem passa:

Estados	Descrição
pending	Aprovada que ainda não começou.
started	Ativa
finished	Finalizada

Consultar itens de uma campanha

Para conhecer os itens que fazem parte de uma campanha faça a seguinte consulta:

Exemplo de desconto pré-acordado:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/P-MLM394001/items?promotion_type=PRE_NEGOTIATED&app_version=v2

Resposta de desconto pré-acordado:

{
   "results": [
       {
           "id": "MLM848619385",
           "status": "candidate",
           "price": 21,
           "original_price": 101,
           "offer_id": "MLM848619385-0e2f3064-0e13-425d-b4a7-0dee85414835",
           "meli_percentage": 24.8,
           "seller_percentage": 54.5,
           "start_date": "2021-05-11T22:00:00Z",
           "end_date": "2021-05-13T01:00:00Z"
       }
   ],
   "paging": {
       "total": 1
   }
}

Exemplo de liquidação de estoque Full:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB12345/items?promotion_type=UNHEALTHY_STOCK&app_version=v2'

Respuesta de liquidação de estoque Full:

{
   "results": [
       {
           "id": "MLB10203040",
           "status": "candidate",
           "price": 21,
           "original_price": 101,
           "offer_id": "MLB10203040-0e2f3064-0e13-425d-b4a7-0dee85414835",
           "meli_percentage": 24.8,
           "seller_percentage": 54.5,
           "start_date": "2023-09-11T22:00:00Z",
           "end_date": "2023-09-13T01:00:00Z"
       }
   ],
   "paging": {
       "total": 1
   }
}

Ao criar uma campanha, todos os itens aplicáveis a ela são selecionados. O status inicial (status) dos itens é candidate e têm um offer_id único. Assim que o vendedor incorpora um item à campanha, seu status muda e passa a ser programmed ou active.

Estado dos itens

Na tabela a seguir você encontra os possíveis status que os itens podem assumir neste tipo de campanha:

Estados	Descrição
candidate	Candidato a participar da promoção.
pending	Promoção aprovada e programada.
active	Ativo na campanha.
finished	Eliminado da campanha.

Aceita desconto

Nota:

Para indicar y eliminar esta campaña de un ítem, cambiamos el wording de "deal_id" a "promotion_id".

Uma vez acordado um desconto para um item, o vendedor pode confirmar o pré-acordo com o seguinte recurso:

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"$PROMOTION_ID",
   "offer_id":"$OFFER_ID",
   "promotion_type":"$PROMOTION_TYPE"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID

Exemplo de desconto pré-acordado:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"P-MLM394001",
   "offer_id":"MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
   "promotion_type":"PRE_NEGOTIATED"
}'
https://api.mercadolibre.com/seller-promotions/items/MLM848619385

Resposta de desconto pré-acordado:



{
   "offer_id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
   "price": 21,
   "original_price": 101
}

Exemplo de liquidação de estoque Full:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"P-MLB12345",
    "offer_id":"MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
   "promotion_type":"UNHEALTHY_STOCK"
}'
https://api.mercadolibre.com/seller-promotions/items/MLB10203040

Resposta de liquidação de estoque Full:

{
   "offer_id": "MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
   "price": 21,
   "original_price": 101
}

Parâmetros

promotion_id: identificação da promoção.
offer_id: identificação da oferta acordada.
promotion_type: tipo de promoção PRE_NEGOTIATED ou UNHEALTHY_STOCK.

Eliminar desconto

Com este recurso você pode eliminar a oferta do item.

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID

Exemplo de desconto pré-acordado:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB1834747833?promotion_type=PRE_NEGOTIATED&promotion_id=P-MLM394001&offer_id=MLM1834747833-9eafadd4-16d2-49ae-b272-9a7a34585cb8

Exemplo de liquidação de estoque Full:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB10203040?promotion_type=UNHEALTHY_STOCK&promotion_id=P-MLB12345&offer_id=MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5'

Resposta: Status 200 OK

Nota:

Lembre-se que, se excluir um desconto pré-acordado ou de liquidação de estoque, o item não será mais um candidato.

Próxima: Desconto individual