Campanhas tradicionais

A campanha tradicional, conhecida como DEAL, é um tipo de promoção organizada pelo Mercado Livre, na qual vendedores convidados podem oferecer seus produtos com preços promocionais.

Os vendedores são periodicamente convidados pelo Mercado Livre para participar de campanhas DEAL. Caso aceitem o convite, podem incluir produtos e definir preços promocionais dentro dos parâmetros estabelecidos pela plataforma.

Consultar detalhes de uma campanha

Para obter os detalhes de uma oferta do tipo DEAL, utilize o seguinte endpoint:

Chamada:

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

Resposta:

{
  "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": "HOTSALE"
}

Estado

Esses são os diferentes estados pelos quais uma campanha tradicional pode passar:

Consultar itens de uma campanha

Para conhecer os itens que fazem parte de uma campanha tradicional, utilize o seguinte endpoint

Exemplo:

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

Resposta:

{
  "results": [
         {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "max_discounted_price": 4800,
          "suggested_discounted_price": 4150,
          "min_discounted_price": 1600,
          "start_date": "2024-11-27T00:00:00",
          "end_date": "2024-12-05T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE"
   },
      {
          "id": "MLB3538191900",
          "status": "started",
          "price": 1000,
          "original_price": 1500,
          "max_discounted_price": 1300,
          "suggested_discounted_price": 1200,
          "min_discounted_price": 1000,
          "start_date": "2024-12-01T00:00:00",
          "end_date": "2024-12-10T00:00:00",
          "sub_type": "FIXED_AMOUNT",
          "top_deal_price": 1100,
          "discount_percentage": 33.33,
          "currency": "BRL"
      },
      {
          "id": "MLB3538191901",
          "status": "pending",
          "price": 0,
          "original_price": 2000,
          "max_discounted_price": 1800,
          "suggested_discounted_price": 1700,
          "min_discounted_price": 1500,
          "start_date": "2024-12-05T00:00:00",
          "end_date": "2024-12-15T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "currency": "BRL"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 2
  }
}

Parámetros

id: id do item.
status: estado do item na campanha.
price: preço do item na campanha.
original_price: preço do item sem desconto.
min_discounted_price: preço mínimo que o vendedor pode colocar no item na campanha. Ou seja, é o maior desconto que o item pode ter.
max_discounted_price: Preço máximo de desconto considerado crível.
suggested_discounted_price: Sugestão de preço promocional atrativo. Pode ser null caso não haja uma sugestão confiável para o item.
top_deal_price: preço do item para os melhores compradores, com nível 3 e 6 do Mercado Pontos. Este campo aparecerá apenas se o item estiver ativo na campanha e se o vendedor colocou um valor para o mesmo no momento em que adicionou o item na campanha.

Estado dos itens

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

Sugestão de Descontos para Promoções

A funcionalidade Sugestão de Descontos permite que vendedores recebam sugestões automáticas de preços promocionais, visando aumentar a competitividade de suas ofertas. Essa sugestão considera o histórico de preços e outros fatores internos para gerar um desconto adequado.

O recurso seller-promotions/promotions permite obter informações sobre os itens candidatos para uma campanha de promoção.

Tipos de campanhas suportadas

• Campanhas tradicionais
• Desconto individual
• Campanhas do vendedor

Indicar itens para uma campanha

Uma vez convidado a participar de uma campanha, você pode indicar quais produtos deseja incluir nela.

Chamada:

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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
  "deal_price": 4000,
  "top_deal_price": 3000,
  "promotion_id": "P-MLB1806019",
  "promotion_type": "DEAL"
 }' 
https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?app_version=v2

Resposta:

{
  "price": 4000,
  "top_price": 3000,
  "original_price": 5000
}

Resposta con error:

Erro 400: Ocorre quando o deal_price informado não atende aos requisitos para o 'Preço Sugerido'

{
  {
    {
      "message": "Errors: ERROR_CREDIBILITY_DISCOUNTED_PRICE - The discounted price is not credible.",
      "error": "bad_request",
      "status": 400,
      "cause": [
        {
          "error_code": "ERROR_CREDIBILITY_DISCOUNTED_PRICE",
          "error_message": "The discounted price is not credible."
     }  
  }  
}

Parâmetros

deal_price: preço do item na promoção.
top_deal_price: preço do item para os melhores compradores com nível 3 a 6 do Mercado Pontos (é opcional informar este preço)
deal_price: preço do item na promoção.
promotion_type: tipo de promoção (DEAL).

Modificar itens

Para modificar os itens que estão participando de uma promoção, faça a seguinte chamada.

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
   "deal_price":$DEAL_PRICE,
   "top_deal_price":$TOP_DEAL_PRICE,
   "promotion_id":"$PROMOTION_ID"
   "promotion_type":"DEAL"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
  "deal_price": 3900,
  "top_deal_price": 3000,
  "promotion_id": "P-MLB1806019",
  "promotion_type": "DEAL"
 }'
https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?app_version=v2

Resposta:

{
  "price": 3900,
  "top_price": 3000,
  "original_price": 5000
}

Excluir itens

Com este recurso você pode excluir itens de uma campanha tradicional.

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&app_version=v2'

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?promotion_type=DEAL&promotion_id=P-MLB1806019=&app_version=v2'

Resposta: Status 200 OK

Possíveis Mensagens de Erro

Ao interagir com a API, é importante estar ciente das mensagens de erro que podem ocorrer, especialmente em casos de requisições inválidas ou falta de acesso. Em caso de problemas, é recomendável verificar as permissões de acesso e os parâmetros de solicitação, além de manter o token de autenticação atualizado

Próxima: Campanha com co-participação