Campanhas do vendedor

Documentação do Mercado Livre

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

Última atualização em 03/11/2023

Campanhas do vendedor

Importante:

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 podem criar suas próprias campanhas através de sua conta do Mercado Livre e gerenciá-las pela integração. Se o vendedor criou uma campanha e quer gerenciar os itens candidatos, poderá fazer isso com os seguintes recursos.

Importante:

Agora temos novos endpoints para criar, atualizar e excluir campanhas do vendedor.

Nota:

O prazo máximo para este tipo de campanha é de 31 dias.

Para oferecer este desconto é necessário:

Ter reputação verde.
O item deve ter status igual a ativo ou pausado.
Condição igual a novo.
A exposição do item não pode ser gratuita.

Criar campanha

Para criar uma campanha do vendedor realize a seguinte chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
   "promotion_type": "SELLER_CAMPAIGN",
   "name": "test campana del seller",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 15,
   "loyalty_percentage": 30,
   "start_date": "2023-07-17T00:00:00",
   "finish_date": "2023-07-20T00:00:00"
}

Campos de chamada

promotion_type: tipo de campanha a criar, atualmente, só é permitido SELLER_CAMPAIGN.
name: nome da campanha.
sub_type: para campanha do vendedor os subtipos permitidos são FIXED_PERCENTAGE e FLEXIBLE_PERCENTAGE.
fixed_percentage: apenas para FIXED_PERCENTAGE (Obrigatório).
loyalty_percentage: apenas para FIXED_PERCENTAGE (opcional, desconto com loyalty).
start_date: data de início da campanha em formato local. O início do dia será sempre considerado como a hora de início.
finish_date: a data de fim da campanha em formato local. O fim do dia será sempre considerado como a hora de fim.

Resposta:

{
   "id": "C-MLB360923",
   "type": "SELLER_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 15,
   "loyalty_percentage": 30,
   "status": "pending",
   "start_date": "2023-07-17T00:00:00",
   "finish_date": "2023-07-20T23:59:59",
   "name": "test campana del seller"
}

Atualizar a campanha

Todos os campos podem ser alterados, mas apenas os campos que pretende alterar devem ser enviados. O único campo obrigatório é promotion_type, que deve estar sempre presente. Se pretender eliminar o desconto de loyalty, deve enviar o campo remove_loyalty como true.

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?app_version=v2
{
   "promotion_type": "SELLER_CAMPAIGN",
   "name": "new name 10",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 18,
   "loyalty_percentage": 33,
   "start_date": "2023-07-18T00:00:00",
   "finish_date": "2023-07-19T00:00:00",
   "remove_loyalty": false
}

Resposta:

{
   "id": "C-MLB360923",
   "type": "SELLER_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 18,
   "loyalty_percentage": 33,
   "status": "pending",
   "start_date": "2023-07-18T00:00:00",
   "finish_date": "2023-07-19T23:59:59",
   "name": "new name 10"
}

Excluir campanha

Para excluir uma campanha do vendedor realize esta chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=SELLER_CAMPAIGN&app_version=v2

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB360923?promotion_type=SELLER_CAMPAIGN&app_version=v2

Resposta: Status 200 OK

Consultar detalhes da campanha

Existem dois sub-tipos para campanhas do vendedor:
FIXED_PERCENTAGE - tem um porcentagem de desconto fixo.
FLEXIBLE_PERCENTAGE - não tem porcentagem fixo.

Para obter os detalhes de uma campanha do vendedor, faça a seguinte consulta:
Exemplo sub_type FIXED_PERCENTAGE:

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

Resposta:

{
  "id": "C-MLB300",
  "type": "SELLER_CAMPAIGN",
  "sub_type": "FIXED_PERCENTAGE",
  "fixed_percentage": 15,
  "loyalty_percentage": 30,
  "status": "started",
  "start_date": "2023-04-27T15:03:00Z",
  "finish_date": "2023-05-05T03:00:00Z",
  "name": "camp del seller 1"
}

Exemplo sub_type FLEXIBLE_PERCENTAGE:

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

Resposta:

{
  "id": "C-MLB302",
  "type": "SELLER_CAMPAIGN",
  "sub_type": "FLEXIBLE_PERCENTAGE",
  "status": "started",
  "start_date": "2023-04-27T15:04:00Z",
  "finish_date": "2023-05-05T03:00:00Z",
  "name": "camp del seller tahi 2"
}

Campos da resposta

id: identificador da campanha.
type: tipo de campanha (SELLER_CAMPAIGN).
sub_type: atualmente temos dois, que são FIXED_PERCENTAGE y FLEXIBLE_PERCENTAGE.
fixed_percentage porcentagem de desconto para todos os compradores.
loyalty_percentage porcentagem de desconto para os melhores compradores (níveis 3 a 6 do Mercado Pontos).
status: estado da campanha.
start_date: data em que começa a campanha.
finish_date: data em que termina a campanha.
name: nome da campanha.

Estados

Estes são os diferentes estados pelos quais uma campanha do vendedor pode passar.

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

Consultar itens em uma campanha

Para ver os itens que fazem parte de uma campanha do vendedor, faça a seguinte consulta:

Exemplo sub_type FIXED_PERCENTAGE:

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

Resposta:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "fixed_percentage": 15,
          "loyalty_percentage": 30,
          "start_date": "2023-04-27T12:03:00",
          "end_date": "2023-05-05T00:00:00",
          "sub_type": "FIXED_PERCENTAGE"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Exemplo sub_type FLEXIBLE_PERCENTAGE:

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

Resposta:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "start_date": "2023-04-27T12:04:00",
          "end_date": "2023-05-05T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Estado dos itens

Na seguinte tabela você irá encontrar os possíveis estados que os itens em uma campanha deste tipo podem ter:

Estado	Descrição
candidate	Item candidato para participar da promoção.
pending	Item com promoção aprovada e programada.
started	Item ativo na campanha.
finished	Item excluído da campanha.

Indicar itens para uma campanha

Após ter itens convidados a participar de uma campanha do vendedor, poderá indicar quais produtos quer incluir na campanha.

Exemplo sub_type FIXED_PERCENTAGE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"C-MLB300",
    "promotion_type":"SELLER_CAMPAIGN"

  }'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Resposta:

{
  "price": 4250,
  "original_price": 5000
}

Exemplo sub_type FLEXIBLE_PERCENTAGE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"C-MLB302",
    "promotion_type":"SELLER_CAMPAIGN",
    "deal_price": 3500,
    "top_deal_price": 3000
 
  }'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Resposta:

{
    "price": 3500,
    "original_price": 5000
 }

Parâmetros

promotion_id: identificação da promoção.
promotion_type: tipo de promoção (SELLER_CAMPAIGN).
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).

Modificar itens

Neste tipo de campanha, você só pode modificar os itens que pertencem à campanha com sub_type FLEXIBLE_PERCENTAGE.
Para modificar os itens realize a seguinte operação.
Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
"promotion_id": "C-MLB302",
"promotion_type": "SELLER_CAMPAIGN",
"deal_price": 3300,
"top_deal_price": 3000,
"remove_loyalty": true
}'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Resposta:

{
  "price": 3300,
  "original_price": 5000
}

Considerações

Se a oferta estiver ativa:

Se tiver um desconto de loyalty adicionado, já não poderá remover mais esse desconto.
Error message: "Top_deal_price can't be removed when the seller campaign has already started".
Se foi criado sem o desconto loyalty, não poderá ser adicionado mais tarde.
Error message: "Top_deal_price can't be set when the seller campaign has already started" .
Os preços só podem melhorar.
Error message: "New deal_price must be lower than current deal_price" / "New top_deal_price must be lower than current top_deal_price".

Se a oferta estiver pendente:

O deal_price e o top_deal_price podem ser modificados para um desconto maior ou menor.
Pode adicionar ou remover o desconto loyalty.

Se pretende remover o desconto de loyalty, é enviado "remove_loyalty": true. Em todos os outros casos (não pretende remover, pretende adicionar, pretende modificar ou não pretende atuar sobre esse preço), o campo é enviado como false ou não é enviado diretamente.

Apenas os campos que pretende alterar são enviados no body.

Exemplo. Modificar o top_deal_price:

{
    "top_deal_price": 1000.33,
    "promotion_id": "C-MLA123",
    "promotion_type": "SELLER_CAMPAIGN"
}

Exemplo. Modificar deal_price e eliminar o top_deal_price:

{
    "deal_price": 700,
    "promotion_id": "C-MLA123",
    "promotion_type": "SELLER_CAMPAIGN",
    "remove_loyalty": true
}

Resposta:

{
    "price": 950,
    "original_price": 1000
}

Excluir

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

Exemplo:

curl -X DELETE -H 'https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?promotion_type=SELLER_CAMPAIGN&promotion_id=C-MLB302

Resposta: Status 200 OK

Erros de validação: 400 bad request

Mensagem de erro	Descrição
The name already exists	Já existe uma campanha do vendedor com o mesmo nome.
Invalid sub_type	Quando o subtipo de um SELLER_CAMPAIGN não é FLEXIBLE_PERCENTAGE nem FIXED_PERCENTAGE.
The percentage is greater than allowed. the maximum percentage allowed is 70.000000	A percentagem máxima permitida é de 70%. Se enviar, por exemplo, fixed_percentage: 71, receberá este erro.
The percentage is less than allowed. the minimum percentage allowed is 10.000000	A percentagem é inferior à percentagem permitida.
Fixed_percentage is required	Se a promoção for do tipo FIXED_PERCENTAGE, o campo fixed_percentage é obrigatório. .
Invalid promotion type	Quando o tipo de promoção é inválido.
Start and finish dates must be in local format	Quando as datas enviadas não estão no formato local (como no exemplo) ou não são enviadas de todo.
Start_date cannot be earlier than today	Start_date não pode ser anterior a hoje.
Finish_date can not be earlier than startdate	A finish_datenão pode ser anterior à start_date.
Maximum period cannot exceed the allowed	Quando a distância entre a data de início e de fim é superior à permitida.
The percentage difference between sellerpercentage and loyaltypercentage does not meet the minimum required	A diferença entre seller_percentage e loyalty_percentage deve ser maior ou igual a 5%.
Maximum period cannot exceed the allowed	Quando se pretende atualizar uma (ou ambas) as datas e o novo período entre elas excede o permitido.
Percentages of a FLEXIBLE PERCENTAGE promotion must be updated per offer	É feita uma tentativa de modificar uma percentagem ou uma percentagem de loyalty para uma campanha do tipo flexible_percentage. As percentagens só podem ser definidas de forma generalizada em fixed_percentages. Para as promoções flexíveis, os preços das ofertas específicas devem ser editados.
The start_date field cannot be modified for the current promotion status	Não é possível alterar a data de início de uma promoção iniciada.