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 campo quantity dentro de trigger.
O campo pague será responsável por indicar o benefício aplicado ao ativar a promoção em quantidade de itens. Será enviado no campo pay dentro de benefits .

`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 campo quantity dentro de trigger .
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 campo discount dentro de benefits .

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 objeto promotion 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: buy_pay 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: "2022-01-25T13:11:24.394Z”	String
end_promotion	Indica a data/hora do fim da promoção. Exemplo: "2022-01-25T13:11:24.394Z”	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

{
    "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.