🪙 Documentação do Sistema de Pontos

📋 Visão Geral

O Sistema de Pontos permite configurar regras de acumulação por política comercial e realizar operações manuais de crédito e débito no saldo de clientes.

Cada regra define a quantidade de pontos gerados via o campo pointAmount, cujo comportamento varia conforme o ruleType configurado. As transações operam em lote sobre múltiplos clientes em uma única requisição.

🔄 Entidades Envolvidas

O sistema de pontos é composto por dois módulos independentes:

Regras de acumulação

Definem o comportamento de ganho de pontos. Cada regra está vinculada a uma política comercial (tradePolicyId) e ao valor decimal pointAmount — que representa pontos por unidade monetária gasta (amount-spent) ou o total de pontos a distribuir proporcionalmente (fixed).

Cada regra suporta dois módulos opcionais:

Agendamento (scheduling) — delimita o período de vigência da regra com datas de início e fim.
Segmentação (segmentation) — determina quais clientes ou contextos de venda são elegíveis, com regras combinadas por operador lógico.

Transações manuais

Permitem crédito (transactions/add) ou débito (transactions/remove) direto no saldo do cliente, sem passar por uma regra automática.

A razão registrada para remoções manuais é sempre "manual".

📌 Notas e Considerações

O sistema aceita no máximo 10 regras por loja. Tentativas além desse limite retornam o erro UAPPI_STORE_POINT_SYSTEM_RULE_MAX_QUANTITY.
Transações são operações em lote — cada item é validado individualmente. Falhas por item são embutidas no campo error da resposta; o HTTP permanece 200 independentemente de erros parciais.
O campo pointAmount aceita até 6 casas decimais — por exemplo, 0.5 representa meio ponto por real no modo amount-spent.

📋 Listagem de Regras do Sistema de Pontos

GET /promotionals/point-system/rules

Retorna a listagem paginada de regras do sistema de pontos cadastradas na loja

📋 Descrição

Endpoint utilizado para listar todas as regras do sistema de pontos cadastradas na loja, com suporte a paginação, filtros e ordenação.

Por padrão, os campos opcionais scheduling e segmentation retornam como null. Para carregá-los, informe-os no parâmetro fields — útil para exibir os detalhes de vigência e elegibilidade de cada regra.

Requer o escopo POINT_SYSTEM_RULE_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🗂️ Campos Disponíveis (fields)

Campo	Descrição
scheduling	Agendamento da regra (período de vigência)
segmentation	Segmentação e regras de elegibilidade

🔍 Campos de Condição Disponíveis

Campo	Tipo	Descrição
id	integer	ID da regra
name	string	Nome da regra
tradePolicyId	integer	ID da política comercial vinculada
ruleType	string	Tipo de acumulação (`amount-spent` ou `fixed`)
active	boolean	Status de ativação da regra
createdAt	datetime	Data de criação
updatedAt	datetime	Data da última atualização
creatorUserId	integer	ID do usuário criador
creatorUserName	string	Nome do usuário criador
creatorUserEmail	string	E-mail do usuário criador
editorUserId	integer	ID do último usuário editor
editorUserName	string	Nome do último usuário editor
editorUserEmail	string	E-mail do último usuário editor

🔃 Campos de Ordenação Disponíveis

Campo	Descrição
id	ID da regra
createdAt	Data de criação

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/promotionals/point-system/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": ["scheduling", "segmentation"],
7    "limit": 10,
8    "offset": 0
9  }'
curl --request GET \
  --url {{MAIN_URL}}/promotionals/point-system/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": ["scheduling", "segmentation"],
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 3,
7        "tradePolicyId": 2,
8        "ruleType": "amount-spent",
9        "name": "Dobro de pontos em eletrônicos",
10        "pointAmount": 2,
11        "active": true,
12        "createdAt": "2026-03-10 08:00:00",
13        "updatedAt": "2026-03-10 08:00:00",
14        "creatorUserId": 5,
15        "creatorUserName": "Carlos Operações",
16        "creatorUserEmail": "carlos.operacoes@loja.com.br",
17        "editorUserId": 5,
18        "editorUserName": "Carlos Operações",
19        "editorUserEmail": "carlos.operacoes@loja.com.br",
20        "scheduling": null,
21        "segmentation": null
22      }
23    ],
24    "pagination": {
25      "limit": 10,
26      "offset": 0,
27      "pages": 1,
28      "registers": 1
29    }
30  }
31}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 3,
        "tradePolicyId": 2,
        "ruleType": "amount-spent",
        "name": "Dobro de pontos em eletrônicos",
        "pointAmount": 2,
        "active": true,
        "createdAt": "2026-03-10 08:00:00",
        "updatedAt": "2026-03-10 08:00:00",
        "creatorUserId": 5,
        "creatorUserName": "Carlos Operações",
        "creatorUserEmail": "carlos.operacoes@loja.com.br",
        "editorUserId": 5,
        "editorUserName": "Carlos Operações",
        "editorUserEmail": "carlos.operacoes@loja.com.br",
        "scheduling": null,
        "segmentation": null
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 1
    }
  }
}

⚠️ 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.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_RULE_READ`.

🔍 Detalhamento de Regra do Sistema de Pontos

GET /promotionals/point-system/rules/{pointSystemRuleId}

Retorna os dados completos de uma regra do sistema de pontos pelo seu ID

📋 Descrição

Endpoint utilizado para carregar os dados completos de uma regra do sistema de pontos no painel administrativo, identificada pelo pointSystemRuleId na URL.

Os campos opcionais scheduling e segmentation retornam null por padrão. Para carregá-los, informe-os no parâmetro fields — útil para exibir detalhes completos da regra em telas de edição.

Caso a regra não seja encontrada, o retorno é um erro 400 com o código UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND.

Requer os escopos POINT_SYSTEM_RULE_READ e POINT_SYSTEM_RULE_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pointSystemRuleId	integer	✅ Sim	ID da regra do sistema de pontos

🗂️ Campos Disponíveis (fields)

Campo	Descrição
scheduling	Agendamento da regra com período de vigência
segmentation	Segmentação e regras de elegibilidade

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": ["scheduling", "segmentation"]
7  }'
curl --request GET \
  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": ["scheduling", "segmentation"]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "tradePolicyId": 2,
6    "ruleType": "amount-spent",
7    "name": "Dobro de pontos em eletrônicos",
8    "pointAmount": 2,
9    "active": true,
10    "createdAt": "2026-03-10 08:00:00",
11    "updatedAt": "2026-03-10 08:00:00",
12    "creatorUserId": 5,
13    "creatorUserName": "Carlos Operações",
14    "creatorUserEmail": "carlos.operacoes@loja.com.br",
15    "editorUserId": 5,
16    "editorUserName": "Carlos Operações",
17    "editorUserEmail": "carlos.operacoes@loja.com.br",
18    "scheduling": null,
19    "segmentation": null
20  }
21}
{
  "status": true,
  "data": {
    "id": 3,
    "tradePolicyId": 2,
    "ruleType": "amount-spent",
    "name": "Dobro de pontos em eletrônicos",
    "pointAmount": 2,
    "active": true,
    "createdAt": "2026-03-10 08:00:00",
    "updatedAt": "2026-03-10 08:00:00",
    "creatorUserId": 5,
    "creatorUserName": "Carlos Operações",
    "creatorUserEmail": "carlos.operacoes@loja.com.br",
    "editorUserId": 5,
    "editorUserName": "Carlos Operações",
    "editorUserEmail": "carlos.operacoes@loja.com.br",
    "scheduling": null,
    "segmentation": null
  }
}

⚠️ 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.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui as permissões `POINT_SYSTEM_RULE_READ` e `POINT_SYSTEM_RULE_WRITE`.
UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND	400	❌ A regra do sistema de pontos solicitada não foi encontrada.

➕ Criação de Regra do Sistema de Pontos

POST /promotionals/point-system/rules

Permite criar uma nova regra de acumulação de pontos na loja

📋 Descrição

Endpoint responsável por criar uma nova regra de acumulação de pontos, vinculada a uma política comercial (tradePolicyId).

O campo ruleType define a lógica de acumulação da regra:

amount-spent — o cliente acumula pontos proporcionalmente ao valor gasto. O campo pointAmount define quantos pontos são gerados por unidade monetária. Aceita até 6 casas decimais — por exemplo, 0.5 representa meio ponto por real.
fixed — o pointAmount define o total de pontos que o grupo de pedidos vai receber, distribuído proporcionalmente ao subtotal segmentado de cada pedido.

Os campos schedulingId e segmentationId associam respectivamente um agendamento e uma segmentação à regra. O valor null indica ausência de vínculo.

Limite de regras: a plataforma suporta no máximo 10 regras por loja. Ao atingir esse limite, a criação é bloqueada com o erro UAPPI_STORE_POINT_SYSTEM_RULE_MAX_QUANTITY.

Após a criação, a resposta retorna a regra com os campos scheduling e segmentation sempre carregados (podendo ser null).

Requer os escopos POINT_SYSTEM_RULE_READ e POINT_SYSTEM_RULE_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
tradePolicyId	integer	✅ Sim	ID da política comercial à qual a regra será vinculada
ruleType	string	✅ Sim	Tipo de acumulação. Valores aceitos: `amount-spent` ou `fixed`
name	string	✅ Sim	Nome descritivo da regra (máximo 255 caracteres)
pointAmount	decimal	✅ Sim	Quantidade de pontos da regra (até 6 casas decimais). Para `amount-spent`: pontos por unidade monetária gasta. Para `fixed`: total de pontos a distribuir proporcionalmente
active	boolean	✅ Sim	Define se a regra está ativa
schedulingId	integer ou null	❌ Não	ID do agendamento a ser associado à regra
segmentationId	integer ou null	❌ Não	ID da segmentação a ser associada à regra

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/promotionals/point-system/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "tradePolicyId": 2,
7    "ruleType": "amount-spent",
8    "name": "Dobro de pontos em eletrônicos",
9    "pointAmount": 2,
10    "active": true,
11    "schedulingId": null,
12    "segmentationId": null
13  }'
curl --request POST \
  --url {{MAIN_URL}}/promotionals/point-system/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "tradePolicyId": 2,
    "ruleType": "amount-spent",
    "name": "Dobro de pontos em eletrônicos",
    "pointAmount": 2,
    "active": true,
    "schedulingId": null,
    "segmentationId": null
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "tradePolicyId": 2,
6    "ruleType": "amount-spent",
7    "name": "Dobro de pontos em eletrônicos",
8    "pointAmount": 2,
9    "active": true,
10    "createdAt": "2026-05-05 09:00:00",
11    "updatedAt": "2026-05-05 09:00:00",
12    "creatorUserId": 5,
13    "creatorUserName": "Carlos Operações",
14    "creatorUserEmail": "carlos.operacoes@loja.com.br",
15    "editorUserId": 5,
16    "editorUserName": "Carlos Operações",
17    "editorUserEmail": "carlos.operacoes@loja.com.br",
18    "scheduling": null,
19    "segmentation": null
20  }
21}
{
  "status": true,
  "data": {
    "id": 3,
    "tradePolicyId": 2,
    "ruleType": "amount-spent",
    "name": "Dobro de pontos em eletrônicos",
    "pointAmount": 2,
    "active": true,
    "createdAt": "2026-05-05 09:00:00",
    "updatedAt": "2026-05-05 09:00:00",
    "creatorUserId": 5,
    "creatorUserName": "Carlos Operações",
    "creatorUserEmail": "carlos.operacoes@loja.com.br",
    "editorUserId": 5,
    "editorUserName": "Carlos Operações",
    "editorUserEmail": "carlos.operacoes@loja.com.br",
    "scheduling": null,
    "segmentation": null
  }
}

⚠️ 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.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_RULE_WRITE`.
UAPPI_STORE_POINT_SYSTEM_RULE_MAX_QUANTITY	400	❌ O limite de 10 regras por loja foi atingido.
UAPPI_STORE_SCHEDULING_NOT_FOUND	404	❌ O agendamento informado em `schedulingId` não foi encontrado.
UAPPI_STORE_SEGMENTATION_NOT_FOUND	404	❌ A segmentação informada em `segmentationId` não foi encontrada.

✏️ Atualização de Regra do Sistema de Pontos

PUT /promotionals/point-system/rules/{pointSystemRuleId}

Atualiza os dados de uma regra do sistema de pontos existente

📋 Descrição

Endpoint responsável por atualizar uma regra do sistema de pontos, identificada pelo pointSystemRuleId na URL.

Todos os campos do corpo são substituídos integralmente — a operação é um update completo, não parcial. Todos os campos obrigatórios devem ser enviados mesmo que não tenham sido alterados.

O campo ruleType define a lógica de acumulação da regra:

amount-spent — o cliente acumula pontos proporcionalmente ao valor gasto. O campo pointAmount define quantos pontos são gerados por unidade monetária.
fixed — o pointAmount define o total de pontos que o grupo de pedidos vai receber, distribuído proporcionalmente ao subtotal segmentado de cada pedido.

Caso o schedulingId ou segmentationId informado não exista na plataforma, o endpoint retorna o erro correspondente antes de persistir qualquer alteração.

Se a regra não for encontrada, o retorno é um erro 400 com o código UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND.

Requer os escopos POINT_SYSTEM_RULE_READ e POINT_SYSTEM_RULE_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pointSystemRuleId	integer	✅ Sim	ID da regra a ser atualizada

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
tradePolicyId	integer	✅ Sim	ID da política comercial vinculada à regra
ruleType	string	✅ Sim	Tipo de acumulação. Valores aceitos: `amount-spent` ou `fixed`
name	string	✅ Sim	Nome descritivo da regra (máximo 255 caracteres)
pointAmount	decimal	✅ Sim	Quantidade de pontos da regra (até 6 casas decimais). Para `amount-spent`: pontos por unidade monetária gasta. Para `fixed`: total de pontos a distribuir proporcionalmente
active	boolean	✅ Sim	Define se a regra está ativa
schedulingId	integer ou null	❌ Não	ID do agendamento a ser associado à regra
segmentationId	integer ou null	❌ Não	ID da segmentação a ser associada à regra

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "tradePolicyId": 2,
7    "ruleType": "amount-spent",
8    "name": "Triplo de pontos em eletrônicos",
9    "pointAmount": 3,
10    "active": true,
11    "schedulingId": null,
12    "segmentationId": null
13  }'
curl --request PUT \
  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "tradePolicyId": 2,
    "ruleType": "amount-spent",
    "name": "Triplo de pontos em eletrônicos",
    "pointAmount": 3,
    "active": true,
    "schedulingId": null,
    "segmentationId": null
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "tradePolicyId": 2,
6    "ruleType": "amount-spent",
7    "name": "Triplo de pontos em eletrônicos",
8    "pointAmount": 3,
9    "active": true,
10    "createdAt": "2026-03-10 08:00:00",
11    "updatedAt": "2026-05-05 10:30:00",
12    "creatorUserId": 5,
13    "creatorUserName": "Carlos Operações",
14    "creatorUserEmail": "carlos.operacoes@loja.com.br",
15    "editorUserId": 7,
16    "editorUserName": "Marina Gestão",
17    "editorUserEmail": "marina.gestao@loja.com.br",
18    "scheduling": null,
19    "segmentation": null
20  }
21}
{
  "status": true,
  "data": {
    "id": 3,
    "tradePolicyId": 2,
    "ruleType": "amount-spent",
    "name": "Triplo de pontos em eletrônicos",
    "pointAmount": 3,
    "active": true,
    "createdAt": "2026-03-10 08:00:00",
    "updatedAt": "2026-05-05 10:30:00",
    "creatorUserId": 5,
    "creatorUserName": "Carlos Operações",
    "creatorUserEmail": "carlos.operacoes@loja.com.br",
    "editorUserId": 7,
    "editorUserName": "Marina Gestão",
    "editorUserEmail": "marina.gestao@loja.com.br",
    "scheduling": null,
    "segmentation": null
  }
}

⚠️ 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.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_RULE_WRITE`.
UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND	400	❌ A regra do sistema de pontos solicitada não foi encontrada.
UAPPI_STORE_SCHEDULING_NOT_FOUND	404	❌ O agendamento informado em `schedulingId` não foi encontrado.
UAPPI_STORE_SEGMENTATION_NOT_FOUND	404	❌ A segmentação informada em `segmentationId` não foi encontrada.

🗑️ Exclusão de Regra do Sistema de Pontos

DELETE /promotionals/point-system/rules/{pointSystemRuleId}

Remove permanentemente uma regra do sistema de pontos da plataforma

📋 Descrição

Endpoint responsável por remover permanentemente uma regra do sistema de pontos, identificada pelo pointSystemRuleId na URL.

Ao excluir a regra, seus vínculos com agendamento e segmentação também são removidos automaticamente.

Caso a regra não seja encontrada, o endpoint retorna erro 400 com o código UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND. Quando a exclusão é bem-sucedida, o campo data retorna true.

Requer os escopos POINT_SYSTEM_RULE_READ e POINT_SYSTEM_RULE_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pointSystemRuleId	integer	✅ Sim	ID da regra a ser removida

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request DELETE \
  --url {{MAIN_URL}}/promotionals/point-system/rules/3 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ 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.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_RULE_WRITE`.
UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND	400	❌ A regra do sistema de pontos solicitada não foi encontrada.

➕ Adição de Pontos em Lote

PUT /promotionals/point-system/transactions/add

Credita pontos manualmente no saldo de um ou mais clientes em uma única operação

📋 Descrição

Endpoint responsável por creditar pontos manualmente no saldo de clientes, processando múltiplos itens em uma única requisição.

O array transactions aceita até 100 itens por chamada. Cada item é validado individualmente — falhas por item são embutidas no campo error da resposta, e o HTTP permanece 200 independentemente de erros parciais.

Os campos orderId, reason e available são gerenciados internamente e não devem ser enviados na requisição. Eles estarão presentes na resposta com valores calculados pelo sistema.

Requer o escopo POINT_SYSTEM_TRANSACTION_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
transactions	array	✅ Sim	Lista de transações a processar (máximo 100 itens)
transactions.*.customerId	integer	✅ Sim	ID do cliente que receberá os pontos
transactions.*.amount	decimal	✅ Sim	Quantidade de pontos a creditar (maior que zero, até 6 casas decimais)
transactions.*.expiresAt	string ou null	❌ Não	Data de expiração dos pontos. `null` indica que os pontos nunca expiram

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/point-system/transactions/add \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "transactions": [
7      {
8        "customerId": 42,
9        "amount": 150,
10        "expiresAt": "2026-12-31 23:59:59"
11      },
12      {
13        "customerId": 87,
14        "amount": 75,
15        "expiresAt": null
16      }
17    ]
18  }'
curl --request PUT \
  --url {{MAIN_URL}}/promotionals/point-system/transactions/add \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "transactions": [
      {
        "customerId": 42,
        "amount": 150,
        "expiresAt": "2026-12-31 23:59:59"
      },
      {
        "customerId": 87,
        "amount": 75,
        "expiresAt": null
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

O array retornado contém todos os itens enviados, incluindo os que falharam. Itens com erro possuem o campo error preenchido com o código do problema — os demais têm error como null.

1{
2  "status": true,
3  "data": [
4    {
5      "customerId": 42,
6      "orderId": null,
7      "amount": 150,
8      "error": null,
9      "expiresAt": "2026-12-31 23:59:59",
10      "available": true
11    },
12    {
13      "customerId": 87,
14      "orderId": null,
15      "amount": 75,
16      "error": null,
17      "expiresAt": null,
18      "available": true
19    }
20  ]
21}
{
  "status": true,
  "data": [
    {
      "customerId": 42,
      "orderId": null,
      "amount": 150,
      "error": null,
      "expiresAt": "2026-12-31 23:59:59",
      "available": true
    },
    {
      "customerId": 87,
      "orderId": null,
      "amount": 75,
      "error": null,
      "expiresAt": null,
      "available": true
    }
  ]
}

⚠️ Exemplo com erro parcial

Quando um ou mais itens falham, a resposta HTTP ainda é 200. O campo error identifica o problema no item específico:

1{
2  "status": true,
3  "data": [
4    {
5      "customerId": 999,
6      "orderId": null,
7      "amount": 50,
8      "error": "UAPPI_STORE_CUSTOMER_NOT_FOUND",
9      "expiresAt": null,
10      "available": true
11    }
12  ]
13}
{
  "status": true,
  "data": [
    {
      "customerId": 999,
      "orderId": null,
      "amount": 50,
      "error": "UAPPI_STORE_CUSTOMER_NOT_FOUND",
      "expiresAt": null,
      "available": true
    }
  ]
}

⚠️ 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.

Erros globais (bloqueiam toda a requisição):

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_TRANSACTION_WRITE`.

Erros por item (embutidos no campo error de cada item na resposta):

Código Interno	Descrição
UAPPI_STORE_CUSTOMER_NOT_FOUND	❌ O cliente informado em `customerId` não foi encontrado.
UAPPI_STORE_POINT_SYSTEM_INVALID_VALUE	❌ O valor de `amount` deve ser maior que zero.
UAPPI_STORE_POINT_SYSTEM_INVALID_EXPIRATION_DATE	❌ A data em `expiresAt` deve ser maior que a data atual.

➖ Remoção de Pontos em Lote

PUT /promotionals/point-system/transactions/remove

Debita pontos manualmente do saldo de um ou mais clientes em uma única operação

📋 Descrição

Endpoint responsável por debitar pontos manualmente do saldo de clientes, processando múltiplos itens em uma única requisição.

O campo reason na resposta sempre retorna "manual" para este endpoint — é gerenciado internamente e não deve ser enviado. O campo orderId também é interno e não deve ser incluído na requisição.

Requer o escopo POINT_SYSTEM_TRANSACTION_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
transactions	array	✅ Sim	Lista de transações a processar (máximo 100 itens)
transactions.*.customerId	integer	✅ Sim	ID do cliente que terá pontos debitados
transactions.*.amount	decimal	✅ Sim	Quantidade de pontos a debitar (maior que zero, até 6 casas decimais; não pode exceder o saldo do cliente)

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/point-system/transactions/remove \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "transactions": [
7      {
8        "customerId": 42,
9        "amount": 30
10      },
11      {
12        "customerId": 87,
13        "amount": 10
14      }
15    ]
16  }'
curl --request PUT \
  --url {{MAIN_URL}}/promotionals/point-system/transactions/remove \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "transactions": [
      {
        "customerId": 42,
        "amount": 30
      },
      {
        "customerId": 87,
        "amount": 10
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

O array retornado contém todos os itens enviados, incluindo os que falharam. Itens com erro possuem o campo error preenchido — os demais têm error como null. O campo reason sempre retorna "manual".

1{
2  "status": true,
3  "data": [
4    {
5      "customerId": 42,
6      "orderId": null,
7      "amount": 30,
8      "error": null,
9      "reason": "manual"
10    },
11    {
12      "customerId": 87,
13      "orderId": null,
14      "amount": 10,
15      "error": null,
16      "reason": "manual"
17    }
18  ]
19}
{
  "status": true,
  "data": [
    {
      "customerId": 42,
      "orderId": null,
      "amount": 30,
      "error": null,
      "reason": "manual"
    },
    {
      "customerId": 87,
      "orderId": null,
      "amount": 10,
      "error": null,
      "reason": "manual"
    }
  ]
}

⚠️ Exemplo com erro parcial

Quando um ou mais itens falham, a resposta HTTP ainda é 200. O campo error identifica o problema no item específico:

1{
2  "status": true,
3  "data": [
4    {
5      "customerId": 999,
6      "orderId": null,
7      "amount": 10,
8      "error": "UAPPI_STORE_CUSTOMER_NOT_FOUND",
9      "reason": "manual"
10    }
11  ]
12}
{
  "status": true,
  "data": [
    {
      "customerId": 999,
      "orderId": null,
      "amount": 10,
      "error": "UAPPI_STORE_CUSTOMER_NOT_FOUND",
      "reason": "manual"
    }
  ]
}

⚠️ 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.

Erros globais (bloqueiam toda a requisição):

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `POINT_SYSTEM_TRANSACTION_WRITE`.

Erros por item (embutidos no campo error de cada item na resposta):

Código Interno	Descrição
UAPPI_STORE_CUSTOMER_NOT_FOUND	❌ O cliente informado em `customerId` não foi encontrado.
UAPPI_STORE_POINT_SYSTEM_INVALID_VALUE	❌ O valor de `amount` deve ser maior que zero.
UAPPI_STORE_POINT_SYSTEM_INVALID_SUBTRACTED_AMOUNT	❌ O valor a debitar excede o saldo disponível do cliente.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

🪙 Documentação do Sistema de Pontos

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

📋 Listagem de Regras do Sistema de Pontos

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

🗂️ Campos Disponíveis (fields)

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🔍 Detalhamento de Regra do Sistema de Pontos

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

🗂️ Campos Disponíveis (fields)

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

➕ Criação de Regra do Sistema de Pontos

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

✅ Resposta de Sucesso