🏷️ Documentação de Entidades Promocionais

📋 Visão Geral

Uma entidade promocional é o objeto estrutural que define como um desconto deve se comportar dentro da plataforma.

Ela determina as regras fundamentais do desconto: qual campo do pedido será avaliado, qual formato o desconto assume e onde ele será aplicado.

Todo registro dos módulos de Promoções e Cupons está vinculado a uma entidade promocional.

É a entidade que carrega a configuração base do comportamento do desconto, enquanto os outros módulos adicionam regras específicas como agendamento, segmentação e limites de uso.

Uma entidade pode estar associada a políticas comerciais específicas, restringindo sua atuação apenas aos canais de venda desejados.

🔄 Entidades Envolvidas

A entidade promocional é a base de configuração compartilhada pelos módulos de Promoções e Cupons.

Ambos os módulos possuem vínculo direto com a entidade por meio de chave estrangeira, e dependem de sua configuração — em especial os campos itemField, type e target — para determinar o comportamento do desconto aplicado ao pedido.

Outros módulos promocionais, como Vouchers e Carteira do Cliente, não utilizam essa estrutura e mantêm suas próprias configurações independentes.

O vínculo com políticas comerciais permite que a entidade tenha atuação restrita a determinados canais, garantindo maior controle sobre onde os descontos são aplicados.

➕ Criação de Entidade Promocional

📋 Descrição

Endpoint responsável por criar uma nova entidade promocional, que define o comportamento base de um desconto na plataforma.

Ao criar uma entidade, o lojista configura como o desconto será calculado — por valor fixo ou percentual — e onde será aplicado no pedido do cliente.

A entidade pode ser vinculada a políticas comerciais específicas, restringindo sua atuação a determinados canais de venda. Quando nenhuma política comercial for informada, o campo tradePolicies deve ser omitido ou enviado como objeto vazio.

Após a criação, a entidade retorna com seu ID gerado, datas de criação e atualização, e a lista de políticas comerciais vinculadas.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/promotionals/entities \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "title": "Desconto no subtotal por valor",
7    "active": true,
8    "itemField": "quantity",
9    "type": "percentage",
10    "target": "subtotal",
11    "observation": "Entidade para campanhas de verão",
12    "tradePolicies": {
13      "1": true,
14      "2": true
15    }
16  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "title": "Desconto no subtotal por valor",
5    "observation": "Entidade para campanhas de verão",
6    "itemField": "quantity",
7    "type": "percentage",
8    "target": "subtotal",
9    "active": true,
10    "tradePolicies": [1, 2],
11    "id": 14,
12    "createdAt": "2026-03-12 08:45:00",
13    "updatedAt": "2026-03-12 08:45:00"
14  }
15}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

✏️ Atualização de Entidade Promocional

📋 Descrição

Endpoint responsável por atualizar os dados de uma entidade promocional existente, identificada pelo parâmetro promotionalEntityId na URL.

Antes de aplicar as alterações, o sistema valida se a entidade informada existe. Caso não seja encontrada, o endpoint retorna erro 404.

Os mesmos campos disponíveis na criação estão disponíveis na atualização.

O vínculo com políticas comerciais também pode ser atualizado: ao informar o campo tradePolicies, os vínculos anteriores são substituídos pelos novos.

Caso o campo seja omitido ou enviado como objeto vazio, os vínculos existentes são preservados — não é possível remover todos os vínculos de políticas comerciais por meio deste endpoint.

Após a atualização, a entidade retorna com todos os seus dados atualizados, incluindo a lista de políticas comerciais vinculadas.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/entities/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "title": "Desconto no subtotal atualizado",
7    "active": false,
8    "itemField": "value",
9    "type": "value",
10    "target": "subtotal-shipping",
11    "observation": null,
12    "tradePolicies": {
13      "1": true
14    }
15  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "title": "Desconto no subtotal atualizado",
5    "observation": null,
6    "itemField": "value",
7    "type": "value",
8    "target": "subtotal-shipping",
9    "active": false,
10    "tradePolicies": [1],
11    "id": 14,
12    "createdAt": "2026-03-12 08:45:00",
13    "updatedAt": "2026-03-12 09:20:00"
14  }
15}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.