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 10/07/2024

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

Importante:
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.


    Aceitar desconto


    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