Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação

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

Campanhas tradicionais

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.

Os vendedores que recebem assessoria da equipe comercial do Mercado Livre são convidados periodicamente a participar de diversas campanhas realizadas no site. Se o vendedor recebeu o convite para uma campanha específica e deseja participar, você pode fazer isso com os seguintes recursos.



Consultar detalhes de uma campanha

Para obter os detalhes de uma oferta do tipo DEAL, faça o seguinte GET:

Nota:
O formato do id desta campanha foi alterada, na versão anterior do recurso enviávamos deal_id no formato {siteId}XXX (MLA1111), na v2 (nova versão do recurso), agora enviamos promotion_id no formato P-{siteId}XXX (P-MLA123456).

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:

Estado Descrição
pending Promoção aprovada, mas que ainda não iniciou.
started Promoção ativa.
finished Promoção finalizada.


Consultar itens de uma campanha

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

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": "MLB3295112047",
          "status": "started",
          "price": 4000,
          "original_price": 5000,
          "top_deal_price": 3000
      },
      {
          "id": "MLB3293389813",
          "status": "candidate",
          "price": 0,
          "original_price": 3000.5,
          "min_discounted_price": 900.15
      },
      {
          "id": "MLB3500418540",
          "status": "candidate",
          "price": 0,
          "original_price": 2000,
          "min_discounted_price": 600
      },
      {
          "id": "MLB3500450682",
          "status": "candidate",
          "price": 0,
          "original_price": 3000,
          "min_discounted_price": 900
      },
      {
          "id": "MLB3500438432",
          "status": "candidate",
          "price": 0,
          "original_price": 3000.5,
          "min_discounted_price": 900.15
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 5
  }
}

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

Estados Descrição
candidate Item elegível para a campanha.
pending Item foi enviado para a campanha porém não iniciou.
started Item com campanha já iniciada.
finished Item eliminado da campanha

Indicar itens para uma campanha

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

Nota:
É opcional informar o preço para top_deal_price.

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
}

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


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