Gerenciar promoções
Características das promoções
Tipo de campanha | Nome | Definição de preço | Sugestão de preço | Bonificação MELI | Stock para participar | Deadline | Aprovação |
---|---|---|---|---|---|---|---|
Tradicional | DEAL | Usuário define | Não | Não | Não | Sim | Sim |
Campanhas com participação | MARKETPLACE CAMPAIGN | Usuário aceita | Não | Sim | Não | Sim | Não |
Oferta do dia | DOD | Usuário define | Sim | Não | Sim, informativo | Não | Não |
Oferta relâmpago | LIGHTNING | Usuário define | Sim | Não | Sim, obrigatório | Não | Não |
Desconto por volume | VOLUME | Usuário aceita | Não | Sim | Não | Sim | Não |
Desconto pré-acordado por item | PRE_NEGOTIATED | Usuário concordar e aceita | Não | Sim | Sim | Sim | Não |
Disponibilidade de promoção por país
Site | Campanha
tradicional (DEAL) |
Campanha com participação
(MARKETPLACE CAMPAIGN) |
Desconto individual
(PRICE DISCOUNT) |
Desconto por volume
(VOLUME) |
Desconto pré-acordado por item
(PRE_NEGOTIATED) |
Oferta do dia
(DOD) |
Oferta relâmpago
(LIGHTNING) |
---|---|---|---|---|---|---|---|
MLA | |||||||
MLB | |||||||
MLM | |||||||
MCO | |||||||
MLC | |||||||
MLU | |||||||
MPE | |||||||
MLV |
Consultar as promoções disponíveis para o vendedor
Lembre-se de que um usuário pode ter mais de um convite e de diferentes tipos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/$USER_ID'
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/631366846'
Resposta:
{
"results": [{
"id": "MLB686",
"type": "DEAL",
"status": "started",
"start_date": "2020-02-04T17:50:00Z",
"finish_date": "2022-10-31T17:20:00Z",
"deadline_date": "2020-01-30T02:00:00Z",
"name": "HOTSALE"
},
{
"id": "DOD-MLB1000",
"type": "DOD",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z"
},
{
"id": "LGH-MLB1000",
"type": "LIGHTNING",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z"
},
{
"id": "P-MLB379009",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T16:40:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "4x3",
"buy_quantity": 4,
"pay_quantity": 3,
"item_discount_percent": 25
}
},
{
"id": "P-MLB380001",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T19:00:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB BNSP",
"benefits": {
"type": "VOLUME",
"meli_percent": 10,
"seller_percent": 30,
"name": "buy 4 save 40%",
"buy_quantity": 4,
"item_discount_percent": 40
}
},
{
"id": "P-MLB380002",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T19:30:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB SPONTH",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "save 50% on 2nd",
"buy_quantity": 2,
"item_discount_percent": 25
}
},
{
"id": "P-MLB382001",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2021-03-25T22:36:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test cofondeada",
"benefits": {
"type": "REBATE",
"meli_percent": 2,
"seller_percent": 8
}
},
{
"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"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 7
}
}
Campos de resposta
id: código de identificação da promoção.
type: tipo de oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, PRE NEGOTIATED).
status: Status.
start_date: data de início da promoção.
finish_date: data de fim da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da oferta.
name: nome da promoção.
deadline_date: prazo máximo para aceitar o convite para participar da promoção.
benefits: configurações de benefícios de promoção.
Consultar itens candidatos
O recurso /seller-promotions/candidates permite identificar os itens convidados a fazer parte de uma promoção. Sempre que um item passa a ter o status "candidate" em uma promoção é enviada uma notificação com o candidate_id, com esse recurso é possível identificar o item, a promoção e o status.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663
Resposta:
{
"id": "CANDIDATE-MLB1254949426-803130663",
"item_id": "MLB1254949426",
"promotion_id": "P-MLB4629001",
"type": "MARKETPLACE_CAMPAIGN",
"status": {
"id": "candidate"
}
}
Campos da resposta
id: código de identificação do candidato.
item_id: item associado ao candidato.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED).
status: status do candidato.
Consultar Ofertas
O recurso /seller-promotions/offers permite identificar as alterações que ocorreram na oferta de um item. Todas as alterações são enviadas por meio de notificações com o offer_id, com esse recurso é possível identificar o item, a promoção e o status.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792
Resposta:
{
"id": "OFFER-MLB1970246686-42701792",
"item_id": "MLB1970246686",
"promotion_id": "P-MLB3329001",
"type": "DEAL",
"status": {
"id": "ACTIVE"
}
}
Campos da resposta
id: código de identificação da oferta.
item_id: item associado a oferta.
promotion_id: id da promoção.
type: tipo de promoção (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED).
status: status da oferta (programmed, active, e inactive).
Consultar os detalhes da promoção
Realize a seguinte consulta para acessar os detalhes específicos de uma campanha tradicional, uma campanha com participação Mercado Livre e para os descontos por volume.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$PROMOTION_TYPE'
Saiba mais sobre campanha tradicional, campanha com participação do Mercado Livre, desconto por volume e desconto pré-acordado por item. .
Status
Abaixo você encontra os possíveis status que os diferentes tipos de promoções:
- Status de uma campanha tradicional
- Status de uma campanha com participação do Mercado Livre
- Status de campanha desconto por volume
- Status da campanha com desconto pré-acordado por item
Consultar itens da promoção
Para conhecer os itens que fazem parte de uma determinada promoção pode-se fazer a seguinte consulta:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTION_TYPE'
Além disso, poderá consultar itens de uma campanha tradicional, itens em uma campanha com participação do Mercado Livre e os itens que podem acessar descontos por volume.
Aqui você pode verificar os itens de uma oferta do dia, de uma oferta relâmpago e o status da campanha com um desconto pré-acordado por item.
Filtros
Você pode aplicar filtros por item ou status.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=DEAL&status=$STATUS&item_id=$ITEM_ID
Exemplo de filtro por item:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000
Resposta:
{
"results": [
{
"id": "MLA604400000",
"status": "rejected",
"price": 23968,
"original_price": 28549
}
],
"paging": {...}
}
Exemplo de filtro por status started:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=approved
Resposta:
{
"results": [
{
"id": "MLA639970000",
"status": "started",
"price": 4037,
"original_price": 4427
},
{
"id": "MLA639973333",
"status": "started",
"price": 6007,
"original_price": 6587
},
],
"paging": [...]
}
Paginação
Para realizar a paginação você deve usar o parametro de searchAfter. O valor enviado nesse parâmetro é sempre o ultimo id do item retornado na chamada anterior.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&searchAfter=$ITEM_ID'
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLB9377/items?promotion_type=DEAL&searchAfter=MLB2674512267'
Resposta:
"results": [
{
"id": "MLB2674512266",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506199",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506138",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505931",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505924",
"status": "candidate",
"price": 0,
"original_price": 0
[…]
"paging": {
"searchAfter": "MLB2674512267",
"limit": 50,
"total": 14424
}
}
Participar de uma promoção
Você pode participar de diversos tipos de promoções e até oferecer um desconto individual para itens:
- Indicando itens para uma campanha tradicional.
- Indicando itens para uma campanha com participação do Mercado Livre.
- Indicando items para desconto por volume.
- Aceitando desconto pré-acordado por item.
- Indicando itens para una oferta del dia.
- Indicando itens para uma oferta relâmpago.
- Oferecendo um desconto individual para uma publicação.
Consultar as promoções de itens
Para ofertas DEALS, retornaremos apenas itens com status aprovado (status = aprovado).
Não aprovaremos as campanhas em teste e elas permanecerão com o status pending_approval, ou seja, você não verá o preço na promoção.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946
Resposta:
[
{
"id": "2864-MLB876768946",
"type": "PRICE_DISCOUNT",
"status": "started",
"price": 700,
"top_price": 650,
"start_date": "2020-09-09T00:00:00",
"finish_date": "2020-09-15T00:00:00"
},
{
"id": "MLB686",
"type": "DEAL",
"status": "started",
"price": 680,
"start_date": "2021-03-04T17:50:00Z",
"finish_date": "2021-10-31T17:20:00Z",
"deadline_date": "2021-03-03T02:00:00Z",
"name": "HOT SALE"
},
{
"id": "P-MLB119001",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2021-04-15T18:37:40.881Z",
"finish_date": "2021-04-30T18:37:40.881Z",
"name": "10% en herramientas",
"benefits": {
"type": "REBATE",
"meli_percent": 2,
"seller_percent": 8
}
},
{
"id": "1504782-MLA874447795",
"type": "DOD",
"status": "started",
"price": 789,
"start_date": "2021-04-19T00:00:00",
"finish_date": "2021-04-19T23:59:59.999999999"
},
{
"id": "1499515-MLA915978647",
"type": "LIGHTNING",
"status": "started",
"price": 745,
"start_date": "2021-04-19T06:00:00",
"finish_date": "2021-04-19T12:00:00",
"remaining_stock": 3
},
{
"id": "P-MLB379009",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T16:40:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "4x3",
"buy_quantity": 4,
"pay_quantity": 3,
"item_discount_percent": 25
}
},
{
"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
}
}
]
}
]
Modificar itens
Para modificar os itens que estão participando de uma oferta, pode fazer isso da seguinte maneira:
- Modificar itens de uma campanha tradicional.
- Modificar itens de uma campanha com participação do Mercado Livre.
- Modificar itens de uma campanha com desconto por volume.
Eliminar itens
Com este recurso é possível eliminar uma oferta do item antes que o prazo acabe:
- Eliminando itens de uma campanha tradicional.
- Eliminando itens de uma campanha com participação do Mercado Livre.
- Eliminando itens em uma campanha de desconto por volume.
- Eliminando desconto pré-acordado por item.
- Eliminando itens em uma oferta do dia.
- Eliminando itens em uma oferta relâmpago.
- Eliminando desconto individual para um item.
Atribuir campanha para teste
Para fazer testes com campanhas teste, envie os dados de seu usuário e/ou itens no seguinte formulário.
Lembre-se de que os usuários quanto itens devem ser testes.
Próxima: Campanhas tradicionais
