Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
Campanhas do vendedor
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.
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 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".
- O deal_price e o top_deal_price podem ser modificados para um desconto maior ou menor.
- Pode adicionar ou remover o desconto loyalty.
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. |