Gerenciar promoções Mercado Shops


Conteúdos


Consultar promoções

→Promoções no Mercado Shops
    ↳Glossário de campos e parâmetros
    →Consultar promoções


Gerenciar publicações com promoções

→Consultar promoções de uma publicação
→Consultar publicações por promoção
→Adicionar publicações a uma promoção
→Excluir uma publicação de uma promoção


Gerenciar promoções por loja

→Consultar promoções por loja
→Criar promoção por loja
→Modificar promoções por loja
→Excluir promoções por loja



Promoções no Mercado Shops

Com o recurso /seller-promotions você pode centralizar todos os tipos de promoções disponíveis no canal de Mercado Shops, como boleto (BOLETO), cupom (COUPON), descontos individuais (INDIVIDUAL), descontos tradicionais (TRADITIONAL e MASSIVE).
Além disso, no Mercado Shops você só precisa ter sua loja criada e ter itens para começar a usar a central de promoções do canal.


Glossário de campos e parâmetros

Campos Descrição do campo Valores possíveis para o campo e sua descrição
name Nome da promoção. String
code Código de desconto. String
description Breve descrição da campanha de desconto. String
discount_type Tipo de desconto. Os valores são “percent”: porcentagem e “fixed”: valor fixo.Para as massivas poderá contar com o valor “by_item”.
value Valor de desconto aplicado. Double
start_date Data de início da promoção. Valor do tipo string, p,e: "2021-11-01T00:00:00.000+0000".
end_date Data fin da promoção (deve ser uma data maior que start_date). Valor do tipo string, p,e: "2021-12-01T00:00:00.000+0000".
min_payment_amount Valor mínimo de pagamento para aplicar o desconto. Double
campaign_item_type Este campo aplica para as campanhas tradicionais. Os valores são “massive” ou “traditional”.
one_coupon_per_user Identifica se a campanha do tipo cupom permite o uso do cupom mais de uma vez. Booleano
status Status da promoção. Os valores são “active”: activo e “inactive”: inativo.
id Id da promoção. String
item_id Id da publicação. Poderá visualizá-la nas promoções individuais.
type Tipo de campanha que o usuário deseja criar. Os valores são “boleto”, “coupom”, “traditional”, “individual”.
target Cobertura do produto, permite identificar se a campanha se aplica a todos os produtos, produtos selecionados ou se aplica a uma lista de produtos. Os valores são “ALL_PRODUCTS”,” SELECTED_PRODUCTS”,”LISTED_PRODUCTS”.
shop_id Identificador da loja/user. Integer
value_discount É o valor do desconto para o item (esse campo aplica apenas para a criação de campanhas massivas). Double
discount_type É o tipo de desconto que se aplica ao item (esse campo aplica apenas para a criação de campanhas massivas). Os valores possíveis são “fixed_price” e “percent”.

Consultar promoções

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$TIPODEPROMOTION&channel=$CHANNEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156?promotion_type=BOLETO&channel=mshops

Resposta de oferta tradicional:

'{
    "id": "TR-496907760-202112031641564156",
    "name": "Traditional Modificada 3",
    "status": "ACTIVE",
    "type": "TRADITIONAL",
    "start_date": "2120-03-14T00:00:00.000+00:00",
    "end_date": "2120-02-13T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "PERCENT",
    "value": 10,
    "shop_id": 496907780,
    "campaign_item_type": "traditional"
}'

Resposta de cupom:

{
   "id": "10097749",
   "name": "Cupon OPEN PLATFORM",
   "status": "ACTIVE",
   "type": "coupon",
   "start_date": "2022-10-30T00:00:00.000+00:00",
   "end_date": "2022-10-31T00:00:00.000+00:00",
   "target": "ALL_PRODUCTS",
   "discount_type": "percent",
   "value": 10,
   "shop_id": 654461415,
   "description": "Esta es la descripción del cupon",
   "code": "TESTCODE",
   "use_limit": 1
}

Resposta de tradicional massiva:

{
   "id": "TRM-654461415-202202011726162616",
   "name": "Traditional Kike masiva prueba 3",
   "status": "ACTIVE",
   "type": "traditional",
   "start_date": "2120-03-14T00:00:00.000+00:00",
   "end_date": "2120-02-13T00:00:00.000+00:00",
   "target": "LISTED_PRODUCTS",
   "discount_type": "by_item",
   "shop_id": 654461415,
   "campaign_item_type": "massive"
}

Resposta por campanha não encontrada:

'{
    "message": "GET to /shops/635345120/discounts/00006720 returned 404 and {\"status_code\":404,\"code\":\"discount_not_found_exception\",\"message\":\"discount with campaign id 00006720 not found for shop 635345120\",\"stacktrace\":null,\"request_id\":\"2edcb000-aacf-41d4-834e-916e1bd922ac\"}",
    "error": "internal_server_error",
    "status": 500,
    "cause": []
}'

Resposta sobre promoções que não pertençam ao canal MShop:

'{
"message": "Invalid promotion type",
"error": "bad_request",
"status": 400,
"cause": []
}'

Parâmetros

promotion_type: tipo de promoção que vai consultar.
promotion_id: identificador da campanha/promoção a consultar.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.



Gerenciar publicações com promoções

Com o recurso /seller-promotions você pode gerenciar publicações com diferentes promoções, tanto para marketplace como Mercado Shops de forma diferenciada, permitindo fazer ações no nível da loja e não individual por itens.


Consultar promoções de uma publicação

Esta funcionalidade permite reconhecer todas as promoções que se estão ativas em uma publicação.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?channel=$CHANNEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA932421975?channel=mshops

Resposta:

{
        "id": "TR-496907760-202112031641564156",
        "name": "Traditional Modificada 3",
        "status": "programmed",
        "type": "traditional",
        "start_date": "2120-03-13",
        "finish_date": "2120-02-12",
        "target": "SELECTED_PRODUCTS"
      "campaign_item_type": "traditional_campaign"
    }

Resposta se o item não existe:

{
    "message": "Item with id MLA082324822 not found",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Resposta se não contam com acesso:

{
    "message": "Caller don't have permissions to access this item",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parâmetros

promotion_type: tipo de promoção que vai consultar.
promotion_id: identificador da campanha/promoção a consultar.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.


Consultar publicações por promoção

Esta funcionalidade permite reconhecer todas as promoções que se estão ativas em uma publicação.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?channel=$CHANNEL&limit=$LIMIT&offset=$OFFSET

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156/items?channel=mshops&limit=100&offset=0

Resposta:

{
   "items": [
       {
           "final_price": 90000,
           "id": "MLA1123020613",
           "original_price": 100000,
           "title": "Samsung Galaxy A10 32 Gb Azul 2 Gb Ram"
       },
       {
           "final_price": 1350,
           "id": "MLA897947944",
           "original_price": 1500,
           "title": "Sticker Tarjetas"
       },
       {
           "final_price": 1350,
           "id": "MLA838847599",
           "original_price": 1500,
           "title": "Billetera Ideal Para Gente Como Vos!"
       }
   ],
   "pagination": {
       "offset": 0,
       "limit": 100,
       "total": 3
   }
}

Parámetros

promotion_id: identificador da campanha/promoção a consultar.
user_id: identificação do vendedor o qual queremos conhecer as promoções que tem em sua loja.
channel: canal o qual queremos consultar. Por funcionalidade, disponibilizaremos marketplace.
limit: limite do número de publicações que devolve a consulta.
offset: número de publicações a omitir antes de começar a devolver as publicações pela consulta. (paginação)


Adicionar publicações a uma promoção

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID/items?channel=$CHANNEL

Exemplo para promoção tradicional:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "items": [
        {
            "item_id": "MLA930546850"
        }
    ],
    "action": "add"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/10038085/items?channel=mshops

Exemplo para promoção massiva:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
   "items": [
       {
           "item_id": "MLA1112170643",
           "value_discount":10,
           "discount_type":"PERCENT"
       },
               {
           "item_id": "MLA931566278",
           "value_discount":10,
           "discount_type":"FIXED_PRICE"
       }
   ],
   "action": "add"
}
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/10038085/items?channel=mshops
Nota:
Considere que os campos de value_discount y discount_type, aplicam apenas para adicionar publicações para uma campanha massiva.

Resposta satisfatória:

{
    "status": "Success",
    "code": "201"
}

Parâmetros

promotion_id: identificador da campanha/promoção a consultar.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.
user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.


Excluir uma publicação de uma promoção

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID/items?channel=$CHANNEL

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"items": [
{
"item_id": "MLA932423847"
}
],
"action": "delete"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156/items?channel=mshops

Gerenciar promoções por loja

Com o recurso /seller-promotions você pode gerenciar diferentes promoções por cada loja do Mercado Shops de forma diferenciada.


Consultar promoções por loja

Com este recurso você pode consultar as promoções ativas de uma loja.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Resposta:

{
   "results": [
       {
           "id": "TR-496907760-202112031641564156",
           "name": "Traditional Modificada 3",
           "status": "ACTIVE",
           "type": "TRADITIONAL",
           "start_date": "2120-03-14T00:00:00.000+00:00",
           "end_date": "2120-02-13T00:00:00.000+00:00",
           "target": "SELECTED_PRODUCTS",
           "discount_type": "PERCENT",
           "value": 10,
           "shop_id": 496907780,
           "campaign_item_type": "traditional"
       },
       {
           "id": "INDIVIDUAL-MLB2038165685-202111021040184018",
           "status": "ACTIVE",
           "type": "INDIVIDUAL",
           "start_date": "2021-12-14T00:00:00.000+00:00",
           "end_date": "2021-12-20T00:00:00.000+00:00",
           "target": "SELECTED_PRODUCTS",
           "discount_type": "PERCENT",
           "value": 5,
           "shop_id": 496907780,
           "item_id": "MLB2038165685"
       },
       {
           "id": "10048392",
           "name": "Prueba usos",
           "status": "ACTIVE",
           "type": "coupon",
           "start_date": "2022-01-28T17:57:00.000+00:00",
           "end_date": "2022-10-29T05:00:00.000+00:00",
           "target": "ALL_PRODUCTS",
           "discount_type": "percent",
           "value": 20,
           "shop_id": 654461415,
           "description": "Usos",
           "code": "USOSCUPON",
           "use_limit": 1
       },
       {
           "id": "TRM-654461415-202201270318521852",
           "name": "Traditional Masivo",
           "status": "ACTIVE",
           "type": "traditional",
           "start_date": "2120-01-18T00:00:00.000+00:00",
           "end_date": "2120-02-13T00:00:00.000+00:00",
           "target": "LISTED_PRODUCTS",
           "discount_type": "by_item",
           "shop_id": 654461415,
           "campaign_item_type": "massive"
       }
   ]
}

Resposta com User_id inválido:

{
    "message": "Caller don't have permissions to access this user",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parâmetros

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.


Criar promoção por loja

Com o seguinte recurso poderá criar uma promoção para la tienda completa, portanto ela será aplicada a todos os itens que estiverem ativos na mesma.


Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d 
{...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL

Dependendo do tipo de promoção que publicar, o POST pode ter atributos como: "name", "discount_type", "value", "campaign_type", "start_date", "end_date", "target", "description", "code", "item_id", "min_payment_amount", "items", "action".

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo Prueba",
"code": "PRUEBA3",
"description": "Descripción cupon",
"discount_type": "fixed",
"value": 50000,
"start_date": "2021-12-01T00:00:00.000+0000",
"end_date": "2021-12-02T00:00:00.000+0000",
"min_payment_amount": 50001,
"max_user_budget": 50000,
"budget": 100000,
"type": "coupon",
"one_coupon_per_user": true,
"status": "active"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Resposta de promoção criada:

{
    "id": "10029844",
    "name": "Nombre Promo Prueba",
    "status": "ACTIVE",
    "type": "COUPON",
    "start_date": "2021-12-01T00:00:00.000+00:00",
    "target": "ALL_PRODUCTS",
    "discount_type": "FIXED",
    "value": 50000,
    "shop_id": 496907780,
    "description": "Descripcion cupon",
    "code": "PRUEBA3"
}

Parâmetros:

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.


Parâmetros esperados por tipo de campanha:

PROPRIEDAD BOLETO COUPON COUPON-FIXED TRADITIONAL TRADITIONAL-ITEM TRADITIONAL-MASIVO INDIVIDUAL
Name Nome da promoção Nome da promoção Nome da promoção Nome da promoção Nome da promoção Nome da promoção
Discount_type PERCENT PERCENT FIXED PERCENT PERCENT BY_ITEM
Value Valor da promoção Valor da promoção Valor da promoção (preço fixo) Valor da promoção Valor da promoção Valor da promoção
type boleto cupom cupom traditional traditional traditional individual
start_date Data de início Data de início Data de início Data de início Data de início Data de início Data de início
end_date Data final Data final Data final Data final Data final Data final Data final
target ALL_PRODUCTS SELECTED_PRODUCTS LISTED_PRODUCTS
min_payment_amount Valor mínimo Valor mínimo
Code Código associado a promoção Código associado a promoçãou
one_coupon_per_user true ou false
items Lista de itens na promoção
Item_id Id do item
campaign_item_type TRADITIONAL TRADITIONAL MASSIVE


Modificar promoções por loja

Com este recurso poder'realizar atualizações nas promoções de uma loja. Para isto é necessário ter o ID da loja e o ID da promoção que quiser modificar.


Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL

Explicações

Para cupom e cupom fixed poderá alterar as seguintes propriedades:

  • Name
  • Value (sempre e quando estiver programada)
  • start_date (sempre e quando estiver programada)
  • end_date (sempre e quando estiver programada)
  • Description
  • min Payment Amount (sempre e quando esteja programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

  • Name
  • Discount_type
  • Value
  • Type
  • start_date
  • end_date
  • start_date
  • code
  • min_payment_amount

Exemplo de coupon fixed:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 fixed",
"discount_type": "fixed",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 50005
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Exemplo de cupom:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 PERCENT",
"discount_type": "percent",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 1
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Explicações

Para boleto podem ser modificadas as seguites propriedades:

  • Name
  • Value (sempre e quando estiver programada)
  • start_date (sempre e quando estiver programada)
  • end_date (sempre e quando estiver programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

  • Name
  • Value
  • Type
  • start_date
  • end_date

Exemplo de boleto:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre PROMO 1 BOLETO",
"value": 20,
"type": "boleto",
"start_date": "2022-02-08T20:57:00.000+0000",
"end_date": "2022-12-08T00:00:00.000+0000"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Explicações

Para tradicionais (ALL_PRODUCTS) poderá modificar as seguintes propriedades:

  • Name
  • start_date (sempre e quando estiver programada)
  • end_date (sempre e quando estiver programada)

Ao realizar uma alteração devem ser enviados ao menos os seguintes dados (assim apenas as propriedades antes mencionadas podem ser modificadas):

  • Name
  • Value
  • Type
  • start_date
  • end_date
  • target

Exemplo de tradicional ALL_PRODUCTS:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Traditional Mod",
"value":10,
"type": "traditional",
"start_date": "2022-02-18T08:00:00.000+0000",
"end_date": "2023-12-13T00:00:00.000+0000",
"target": "ALL_PRODUCTS"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Resposta com algum parâmetro incorreto:

{
    "message": "type mismatch for key [target]",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Parâmetros

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.
promotion_id: identificador da campanha/promoção a consultar.


Excluir promoções por loja

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/INDIVIDUAL-MLA930546840-2021110811090191?channel=mshops

Parâmetros

user_id: identificação do vendedor que queremos consultar as promoções que tem em sua loja.
channel: canal onde queremos consultar. Por padrão, disponibilizaremos marketplace.
promotion_id: identificador da campanha/promoção a consultar.

ou registre-se para receber as últimas notícias sobre nossa API