Documentação do Mercado Shops

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

Documentação do

Última atualização em 13/07/2024

Gestão de promoções

Promoções

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) e descontos por volume (VOLUME, INDIVIDUAL_VOLUME).
Para começar a usar a central de promoções no canal e realizar promoções você deve apenas contar com a loja criada e ter itens.

Importante:
Um mesmo produto pode participar no máximo de 5 ofertas de quantidade, sem coincidir na mesma data. Se suas ofertas de quantidade (ex.: 2X1) coincidem em datas com uma oferta tradicional (ex.: 50% OFF), mostraremos ao comprador a que tem o maior benefício.


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 irá contar com o valor by_item. Também com discount_by_quantity, percentage_by_volume y percentage_by_unit, para os descontos por volume.
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 fim 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: ativo 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, coupon, traditional, individual, volume, individual_volume.
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, discount_by_quantity, percentage_by_unit y percentage_by_volume.
buy_quantity É a quantidade de produtos que fazem parte da promoção. Integer
pay_quantity É a quantidade de produtos pagos pela promoção. Integer

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 de ofertas por quantidade:

{
    "results": [
        {
            "id": "DXV-553421365-20230131110752752",
            "name": " DXV PRUEBA 1",
            "status": "ACTIVE",
            "type": "volume",
            "start_date": "2023-02-02T00:00:00.000+00:00",
            "end_date": "2023-03-31T00:00:00.000+00:00",
            "target": "SELECTED_PRODUCTS",
            "discount_type": "percentage_by_unit",
            "value": 20,
            "shop_id": 553421365,
            "buy_quantity": 6
        },
}

Resposta de 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 de 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 ao nível loja e não individual por itens.


Consultar promoções de uma publicação

Esta funcionalidade permite reconhecer todas as promoções que 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 desconto tradicional:

{
        "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 oferta por quantidade:

   {
        "id": "DXV-553421365-20230131110752752",
        "name": " DXV PRUEBA 1",
        "status": "programmed",
        "type": "volume",
        "start_date": "2023-02-01",
        "finish_date": "2023-03-30",
        "target": "SELECTED_PRODUCTS",
        "buy_quantity": 6
    }

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

Resposta de ofertas de quantidade:

{
    "items": [
        {
            "final_price": 591600000,
            "id": "MLA851258051",
            "original_price": 102000000,
            "title": "Smart Tv Tcl L50p8m Led 4k 50  100v/240v"
        },
        {
            "final_price": 116000,
            "id": "MLA1137574968",
            "original_price": 20000,
            "title": "Procesador De Alimentos"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 50,
        "total": 2
    }
}

Parâmetros

promotion_id: identificador da campanha/promoção a consultar.
user_id: identificação do vendedor que queremos conhecer as promoções que tem em sua loja.
channel: canal que queremos consultar. Por funcionalidade, disponibilizaremos marketplace.
limit: limite 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/promotion/$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/promotion/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/promotion/10038085/items?channel=mshops

Exemplo de ofertas para quantidade:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
    "items": [
        {
            "item_id": "MLA854184492"
        }
    ],
    "action": "add"
}
https://api.mercadolibre.com/seller-promotions/users/553421365/promotion/DXV-553421365-20230131110752752/items?channel=mshops
Nota:
Considere que os campos de value_discount ey discount_type, aplicam apenas para adicionar publicações empara 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

Exemplo de oferta para quantidade:

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

https://api.mercadolibre.com/seller-promotions/users/553421365/promotions/DXV-553421365-20230131110752752/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

Com este recurso você pode criar uma promoção para a loja completa que será aplicada para todos os itens ativos desta loja.


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, status, buy_quantity.


Exemplo de cupom:

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 cupom 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"
}

Exemplo oferta de quantidade, sobre todas as unidades (20%off na 6ta unidade):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
 "name": " DXV PRUEBA 1",
 "discount_type": "percentage_by_unit",
 "value": 20.0,
 "start_date": "2023-02-02T00:00:00.000+0000",
 "end_date": "2023-03-31T00:00:00.000+0000",
 "type": "volume",
 "target": "SELECTED_PRODUCTS",
 "buy_quantity": 6,
 "status": "ACTIVE"
}'
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops

Resposta da promoção criada:

{
    "id": "DXV-553421365-20230131110752752",
    "name": " DXV PRUEBA 1",
    "status": "ACTIVE",
    "type": "volume",
    "start_date": "2023-02-02T00:00:00.000+00:00",
    "end_date": "2023-03-31T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "percentage_by_unit",
    "value": 20,
    "shop_id": 553421365,
    "buy_quantity": 6
}

Exemplo de oferta de quantidade sobre uma unidade ( 20%off na 6ta unidade):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
"name": " DXV PRUEBA 2",
"discount_type": "percentage_by_volume",
"value": 20.0,
"start_date": "2023-04-02T00:00:00.000+0000",
"end_date": "2023-04-31T00:00:00.000+0000",
"type": "individual_volume",
"target": "SELECTED_PRODUCTS",
"buy_quantity": 6,
"status": "ACTIVE",
"item_id": "MLA1137574968"
}
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops

Resposta satisfatória:

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

Exemplo de ofertas por quantidade de unidades grátis (2x1):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
"name": " DXV PRUEBA 3 2x1",
"discount_type": "discount_by_quantity",
"start_date": "2023-05-02T00:00:00.000+0000",
"end_date": "2023-05-31T00:00:00.000+0000",
"type": "volume",
"target": "SELECTED_PRODUCTS",
"buy_quantity": 2,
"pay_quantity": 1,
"status": "ACTIVE"
}
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops

Resposta satisfatória:

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

Note que não pode ter mais de 1 oferta por quantidade ao mesmo tempo sobre um produto, quer sejam datas exatas ou dias sobrepostos.
Além disso, as percentagens de ofertas podem situar-se entre (5% e 95%) e o número de unidades aplicáveis às promoções pode situar-se entre (2 e 10 unidades).


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
Name Nome da promoção Nome da promoção Nome da promoção Nome da promoção
Discount_type PERCENT PERCENT FIXED PERCENT
Value Valor da promoção Valor da promoção Valor da promoção (preço fixo) Valor da promoção
type boleto cupom cupom traditional
start_date 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
target ALL_PRODUCTS
min_payment_amount Valor mínimo Valor mínimo
Code Código associado a promoção Código associado a promoção
one_coupon_per_user true ou false
items
Item_id
campaign_item_type TRADITIONAL
buy_quantity
pay_quantity
TRADITIONAL-ITEM TRADITIONAL-MASIVO INDIVIDUAL VOLUME
Nome da promoção Nome da promoção Nome da promoção Nome da promoção
PERCENT BY_ITEM discount_by_quantity , percentage_by_volume, percentage_by_unit
Valor da promoção Valor da promoção Valor da promoção (Exceto para discount_by_quantity)
traditional traditional individual volume e individual_volume
Data de início Data de início Data de início Data de início
Data final Data final Data final Data final
SELECTED_PRODUCTS LISTED_PRODUCTS SELECTED_PRODUCTS
Lista de itens na promoção Lista de ítens na promoção (para quando é type - individual_volume)
Id do item Id do item
TRADITIONAL MASSIVE
quantidade de itens que aplicam a promoção (entre 2 e 10 unidades)
quantidade de itens que devem ser pagos (Menor que a quantidade que leva)


Modificar promoções por loja

Com este recurso você pode 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 coupon e coupon fixed você pode 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 coupon:

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

Exemplo:

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.


Consultar relatório de cupones


Através do recurso /coupons, você poderá obter um relatório dos cupons vigentes na loja, permitindo assim ter visibilidade dos cupons criados em um determinado intervalo de tempo.


Parâmetros:

É possível obter o relatório de cupons disponíveis em uma loja, realizando uma consulta com os seguintes parâmetros.


Nome Tipo Descrição Exemplo
Seller_id String ID do vendedor/loja 594239600
Start_date String Data de início do relatório no formato yyyy-MM-dd 2024-07-09
End_date String Data de término do relatório no formato yyyy-MM-dd 2024-07-12

Chamada:


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$SELLER_ID/coupons?start_date=$START_DATE&end_date=$END_DATE&channel=mshops

Exemplo:


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/123/coupons?start_date=2024-04-01&end_date=2024-04-30

Resposta bem-sucedida dos cupones


{
  "start_date": "2024-04-01",
  "end_date": "2024-04-30",
  "coupons": [
    {
      "id": 10996528,
      "campaign_name": "Cupon test",
      "coupon_code": "TESTCUPON",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-30",
      "start_date": "2024-03-30",
      "end_date": "2024-05-14",
      "status": "active"
    },
    {
      "id": 10993413,
      "campaign_name": "Cupon test 2",
      "coupon_code": "TESTCUPON2",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-24",
      "start_date": "2024-03-28",
      "end_date": "2024-04-30",
      "status": "active"
    },
    {
      "id": 10993343,
      "campaign_name": "Cupon test 3",
      "coupon_code": "TESTCUPON2",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-24",
      "start_date": "2024-03-28",
      "end_date": "2024-04-13",
      "status": "inactive"
    }
  ]
}

Resposta bem-sucedida dos cupones, mas sem cupons dentro do intervalo de datas selecionado:


{
  "start_date": "2024-04-01",
  "end_date": "2024-04-30",
  "coupons": []
}

Recuperação de cupones sem data de início e/ou sem data de término:


Request-code: 400
{
  "start and end dates must not be empty"
}

Campos da resposta:

A resposta de um GET ao recurso /coupons fornecerá os seguintes parâmetros

  • results:
    • id: id da promoção/cupom
    • campaign_name: Nome da promoção/cupom
    • coupon_code: Código atribuído para resgatar o cupom
    • used_coupon: Booleano que me permite saber se o cupom foi usado ou não
    • total_sales: Total de vendas geradas com os produtos vendidos que aplicaram o cupom
    • total_discount: Total de desconto gerado com os produtos vendidos que aplicaram o cupom
    • created_date: Data de criação da promoção/cupom
    • start_date: Data de início da promoção/cupom
    • end_date: Data de término da promoção/cupom
    • status: Estado da promoção, seus valores podem ser active (ativo) ou inactive (inativo)

Erros Cupons

Recuperação de cupons com um formato de data incorreto



    Request-code: 400
{
    "Start and end dates must be in correct format: yyyy-MM-dd"
}

Erro ao recuperar os cupons de um seller



 Request-code: 500
{
}

Erro no uso do access token para obter informações de cupons



 Request-code: 401
{
    "code": "unauthorized",
    "message": "invalid access token"
}

Próxima: Vendas de usuários convidados.