Documentação API de Promoções
A API de Gestão Promocional é responsável pela criação e ativação de ofertas nos meios de geração de pedido selecionados.
Atualmente temos os tipos:
- Leve e Pague
- Desconto
As ofertas poderão ser segmentadas por canais e locais em breve. No futuro, podemos colocar perfis de usuários.
Tipos de promoção
type: buy_pay
Leve Y e Pague X. Ao selecionar essa regra, exibiremos dois campos de texto: leve
e pague
.
- O campo
leve
será responsável por indicar a quantidade mínima que entrará no gatilho que ativará a promoção através do campoquantity
dentro detrigger
. - O campo
pague
será responsável por indicar o benefício aplicado ao ativar a promoção em quantidade de itens. Será enviado no campopay
dentro debenefits
.
type: discount
Ganhe uma porcentagem ao levar itens. Ao selecionar essa regra, exibiremos dois campos de texto: leve
e ganhe
.
- O campo
leve
será responsável por indicar a quantidade mínima que entrará no gatilho que ativará a promoção através do campoquantity
dentro detrigger
. - O campo
ganhe
será responsável por indicar o benefício aplicado ao ativar a promoção em porcentagem que será aplicada ao valor dos itens. Será enviado no campodiscount
dentro debenefits
.
Endpoint
Para cadastrar uma promoção na API de promoção será necessário fazer uma requisição POST para a seguinte url:
POST https://api.newtail.com.br
Autenticação
Seja mais sobre a autenticação em 🔐Documentação API Autenticação
Calculo de Promoções via API
O objetivo desta funcionalidade é conseguir calcular os descontos para uma cesta.
Parâmetro | Descrição | Valores | Obrigatório |
---|---|---|---|
nome_layout | O nome do layout indica o formato de dados recebido e o formato retornado | -generic | Sim |
JSON:
POST /api/promotion/calculate/{{nome_layout}}
Payload
Todos os campos devem ser enviados no body.
Atributo | Descrição | Tipo | Obrigatório |
---|---|---|---|
store_id | Código identificador da loja | String | Sim |
social_id | CPF/CNPJ do cliente | String | Sim |
items | Informações dos produtos | Array<Object> | Sim |
external_id | Código externo do item | string | Sim |
price | Preço do item | Number | Sim |
quantity | Quantidade do item | Number | sim |
Exemplo de requisição
{
"social_id": "11111111111",
"store_id": "001",
"items": [
{
"external_id": "1111",
"price": 5,
"quantity": 3
},
{
"external_id": "2222",
"price": 4.5,
"quantity": 3
},
{
"external_id": "3333",
"price": 5,
"quantity": 3
}
]
}
Exemplo de Resposta
[
{
"external_id": "001",
"price": 5,
"quantity": 3,
"discount": 5,
"promotion": {
"id": "6243574f1f8211073c9e04fd",
"promotion_type": "buy_pay",
"unit_price_promotion": 3.33,
"average_price": 3.33
}
},
{
"external_id": "002",
"price": 4.5,
"quantity": 3,
"discount": 4.5,
"promotion": {
"id": "6243574f1f8211073c9e04fd",
"promotion_type": "buy_pay",
"unit_price_promotion": 3,
"average_price": 3
}
},
{
"external_id": "003",
"price": 5,
"quantity": 3,
"discount": 0,
"promotion": {}
}
]
⚠️ * Os itens que tiverem promoção ativa, terá o campo discount
com o valor total do desconto do item e o objeto promotion
, terá as informações da promoção disparada para o item.
- Quando um item não tiver uma promoção, o campo
discount
irá retornar com o valor zero e o objetopromotion
estará vazio.
Criação de Promoção via API
Todos os campos devem ser enviados no body.
Atributo | Descrição | Tipo | Obrigatório |
name | Nome da promoção | String | Sim |
account_id | Código identificador da conta | String | Sim |
promotion_type |
Tipo da promoção Valores: discount
|
String | Sim |
description | Descrição da promoção | String | Não |
offers_ids | Código sku do produto | Array<String> | Sim |
location_ids | Código da Loja | Array<String> | Não |
trigger.quantity | Indica a quantidade minima para disparar a promoção | Number | Sim |
benefits.pay | Indica quantos itens serão pagos dentre os selecionados. Só é usado para o tipo de promoção buy_pay | Number | Sim (Quanto o tipo de promoção for buy_pay) |
benefits.discount | Indica o percentual de desconto. Só é usando para o tipo de promoção discount | Number | Sim (Quanto o tipo de promoção for discount) |
start_promotion |
Indica a data/hora do inicio da promoção. Exemplo: |
String | |
end_promotion |
Indica a data/hora do fim da promoção. Exemplo: |
String | |
active | Indica se a promoção está ativa | boolean | |
is_loyalty_promotion | is_loyalty_promotion | boolean | Não |
cover_url | URL da imagem da capa da promoção | String | Não |
template | Indica o template da promoção | String |
Não |
Exemplo de requisição
JSON:
{
"trigger": {
"quantity": 3
},
"benefits": {
"pay": 2
},
"location_ids": [],
"offers_ids": [
"2001261",
"21843"
],
"promotion_type": "buy_pay",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "leve 3 pague 2",
"start_promotion": "2022-01-25T13:11:24.394Z",
"end_promotion": "2022-02-25T13:11:24.394Z",
"active": true
"cover_url": "<https://s3.newtail.com.br/promotions/cover.jpg>",
"is_loyalty_promotion": false,
"template": "default"
}
Exemplo de Resposta
O retorno da requisição terá código HTTP 201 para caso que obtiveram sucesso na requisição. Em caso de erro será enviado um HTTP 4XX, com o possível problema.
Abaixo exemplo de requisição bem sucedida:
{
"_id": "620150ad1f6f55dc7b4f58b7",
"location_ids": [],
"offers_ids": [
"2001261"
],
"promotion_type": "buy_pay",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "leve 3 pague 2",
"trigger": {
"quantity": 3
},
"benefits": {
"pay": 2
},
"start_promotion": "2022-01-25T13:11:24.394Z",
"end_promotion": "2022-02-25T13:11:24.394Z",
"created_at": "2022-02-07T17:02:37.896Z",
"updated_at": "2022-02-07T17:02:37.896Z",
"__v": 0,
"active": true,
"cover_url": "<https://s3.newtail.com.br/promotions/cover.jpg>",
"is_loyalty_promotion": false,
"template": "default"
"id": "620150ad1f6f55dc7b4f58b7"
}
Para consultar uma promoção na API de promoção será necessário fazer uma requisição GET para a seguinte url:
GET /api/promotion/:id
Exemplo de Resposta
O retorno da requisição terá código HTTP 200 para caso que obtiveram sucesso na requisição. Em caso de erro será enviado um HTTP 4XX, com o possível problema.
Abaixo exemplo de requisição bem sucedida:
{
"trigger": {
"quantity": 3
},
"benefits": {
"pay": 2
},
"location_ids": [],
"offers_ids": [
"2001261"
],
"promotion_type": "buy_pay",
"_id": "62055e3310d035001c6e09f7",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "Leve 3 pague 2 - Teste Diego",
"description": "",
"start_promotion": "2022-02-10T00:00:00.000Z",
"end_promotion": "2022-03-11T02:59:00.000Z",
"created_at": "2022-02-10T18:49:23.917Z",
"updated_at": "2022-02-10T19:03:03.250Z",
"__v": 0,
"active": true,
"id": "62055e3310d035001c6e09f7",
"selected_offers": [
{
"id": "6140fde45834d9506e73287e",
"name": "NISSIN MIOJO PICANHA 01",
"external_id": "2001261",
"assets": {
"small": [],
"large": [],
"raw": [
{
"mime": "image/webp",
"url": "<https://cdn.newtail.com.br/assets/products/612fb084873b7000081af8be/raw.6130e72afec07ad637a43839.webp>"
}
],
"medium": []
}
}
]
}
Para consultar todas as promoções de uma conta na API será necessário fazer uma requisição GET para a seguinte url:
GET /api/promotion
Exemplo de Resposta
O retorno da requisição terá código HTTP 200 para caso que obtiveram sucesso na requisição. Em caso de erro será enviado um HTTP 4XX, com o possível problema.
Abaixo exemplo de requisição bem sucedida:
{
"total": 4,
"pages": 1,
"currentPage": 1,
"data": [
{
"trigger": {
"quantity": 5
},
"benefits": {
"pay": 3
},
"location_ids": [],
"offers_ids": [
"6140feff5834d956353a8ae3",
"614101b95834d94c57638708",
"6140ff5b5834d956353a9f18"
],
"promotion_type": "buy_pay",
"_id": "61f94b31d74a36001bbad618",
"target": {
"quantity": 0,
"offers_ids": []
},
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "Leve 5 batatas e pague 3",
"description": "O cliente levará 5 refrigerantes participantes e pagará 3.",
"start_promotion": "2021-12-01T13:00:00.000Z",
"end_promotion": "2022-02-02T01:00:00.000Z",
"created_at": "2022-02-01T15:01:05.793Z",
"updated_at": "2022-02-07T21:51:37.952Z",
"__v": 0,
"disabled_at": "2022-02-07T21:51:37.950Z",
"active": false,
"id": "61f94b31d74a36001bbad618"
},
{
"trigger": {
"quantity": 20
},
"benefits": {
"discount": 20
},
"target": {
"offers_ids": []
},
"location_ids": [],
"offers_ids": [
"35843",
"18130",
"2005364",
"13783",
"2025130010",
"2025130003"
],
"promotion_type": "discount",
"_id": "6201bae891bf31001b2324aa",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "Nestlé fevereiro 2022",
"description": "Teste",
"start_promotion": "2022-02-10T13:00:00.000Z",
"end_promotion": "2022-02-19T02:59:00.000Z",
"created_at": "2022-02-08T00:35:52.627Z",
"updated_at": "2022-02-10T20:27:30.099Z",
"__v": 1,
"active": true,
"id": "6201bae891bf31001b2324aa"
},
{
"trigger": {
"quantity": 12
},
"benefits": {
"pay": 10
},
"location_ids": [],
"offers_ids": [
"2007606",
"2014080",
"2017944",
"2029482",
"2017295",
"2012228",
"2039808",
"2007099",
"2008843",
"21971",
"2016778",
"2016205",
"24631",
"2011799",
"2029113",
"36185",
"2030809"
],
"promotion_type": "buy_pay",
"_id": "62066f2f0a4024001bfaa199",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "SEXTOU!!!",
"description": "",
"start_promotion": "2022-02-11T03:00:00.000Z",
"end_promotion": "2022-02-12T02:59:00.000Z",
"created_at": "2022-02-11T14:14:07.692Z",
"updated_at": "2022-02-11T14:14:07.692Z",
"__v": 0,
"active": true,
"id": "62066f2f0a4024001bfaa199"
},
{
"trigger": {
"quantity": 10
},
"benefits": {
"discount": 50
},
"target": {
"offers_ids": []
},
"location_ids": [],
"offers_ids": [
"2025160009",
"2025160010",
"2001261"
],
"promotion_type": "discount",
"_id": "62019e8410d035001c6e07b2",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "Compre 10 baldes e ganha 50%",
"description": "Comprando 10 baldes o cliente ganhará 50%",
"start_promotion": "2022-02-15T08:00:00.000Z",
"end_promotion": "2022-08-02T01:00:00.000Z",
"created_at": "2022-02-07T22:34:44.594Z",
"updated_at": "2022-02-07T22:34:44.594Z",
"__v": 0,
"active": true,
"id": "62019e8410d035001c6e07b2"
}
]
}
Para atualizar uma promoção na API de promoção será necessário fazer uma requisição PUT para a seguinte url:
PUT /api/promotion/:id
Exemplo de Resposta
O retorno da requisição terá código HTTP 200 para caso que obtiveram sucesso na requisição. Em caso de erro será enviado um HTTP 4XX, com o possível problema.
Abaixo exemplo de requisição bem sucedida:
{
"trigger": {
"quantity": 3
},
"benefits": {
"pay": 2
},
"location_ids": [],
"offers_ids": [
"2001261",
"21843"
],
"promotion_type": "buy_pay",
"_id": "620150ad1f6f55dc7b4f58b7",
"account_id": "b9531180-a367-11eb-8e86-a140f88b70d4",
"name": "leve 3 pague 2",
"start_promotion": "2022-01-25T13:11:24.394Z",
"end_promotion": "2022-02-25T13:11:24.394Z",
"created_at": "2022-02-07T17:02:37.896Z",
"updated_at": "2022-02-11T18:47:37.063Z",
"__v": 0,
"disabled_at": "2022-02-11T18:47:37.054Z",
"active": false,
"id": "620150ad1f6f55dc7b4f58b7"
}
Para excluir uma promoção na API de promoção será necessário fazer uma requisição DELETE para a seguinte url:
DELETE /api/promotion/:id
Exemplo de Resposta
O retorno da requisição terá código HTTP 200 para caso que obtiveram sucesso na requisição. Em caso de erro será enviado um HTTP 4XX, com o possível problema.
Abaixo exemplo de requisição bem sucedida:
{
"deleted_id": "61fc1896a9c486f60c6f59ca"
}
Comentários
0 comentário
Por favor, entre para comentar.