Documentação - API CSBBenk - Versão 1.1

Versão: 1.1
Data: 27/08/2025

Autores:
Cezar Augusto Mezzalira (nav9),
Guilherme Rodrigues (nav9),
Guilherme Persch (nav9) e
Lucas Gabriel da Silva (nav9)

Tecnologias

Tecnologia/Framework	Versão
Node.js	v22
NestJS	v11.1.3
Redis (Ambiente Local)	latest
ValKey (Redis OSS AWS)	latest
Postgres (Ambiente Local)	latest
Aurora RDS (Postgres Compatible AWS)	latest

Integrações com Outras API’s

API	O que faz	Método de Integração
Celcoin	Operações bancárias	HTTP/JSON
Resend	Envio de emails	HTTP/JSON
Axiom	Logs	HTTP/JSON
AWS Secrets	Armazena variáveis de ambiente	AWS SDK
AWS S3	Armazena documentos	AWS SDK

Bibliotecas Usadas

A seguir, está a lista de todas as dependências usadas em produção pela API:

Dependência	Versão
@aws-sdk/client-secrets-manager	^3.427.0
@aws-sdk/rds-signer	^3.577.0
@axiomhq/js	^1.2.0
@axiomhq/winston	^1.2.0
@castleio/sdk	^2.2.2
@nestjs/axios	^4.0.0
@nestjs/common	^11.1.3
@nestjs/config	^4.0.2
@nestjs/core	^11.1.3
@nestjs/mapped-types	*
@nestjs/platform-express	^7.0.0
@nestjs/schedule	^6.0.0
@nestjs/swagger	^11.2.0
@nestjs/terminus	7
@nestjs/typeorm	8.0.3
@sentry/node	^7.62.0
@types/node	^18.15.12
@types/telebot	^1.2.4
aws-sdk	^2.1628.0
axios	^1.9.0
bcrypt	^5.1.0
blob-util	^2.0.2
body-parser	^1.20.0
bull	^4.10.4
cache-manager	^4.0.1
canvas	^3.1.0
class-transformer	^0.5.1
class-validator	^0.14.2
cookie-parser	^1.4.6
cors	^2.8.5
crypto	^1.0.1
crypto-js	^4.2.0
currency-formatter	^1.5.5
dotenv	^16.4.7
ejs	^3.1.9
form-data	^3.0.0
fs	^0.0.1-security
fs.promises	^0.1.2
html-pdf	^3.0.1
https	^1.0.0
image-conversion	^2.1.1
ioredis	^5.4.1
jsbarcode	^3.11.0
jsdom	^16.4.0
jsonwebtoken	^8.5.1
lodash	^4.17.21
moment	^2.30.1
moment-timezone	^0.6.0
nestjs-zod	^4.3.1
newrelic	^9.10.2
node-blob	^0.0.2
nodemailer	^6.7.3
pdf-lib	^1.17.1
pdfkit	^0.16.0
pg	^8.7.1
qrcode	^1.5.1
querystring	^0.2.1
react	^18.3.1
react-dom	^18.3.1
redis	^5.0.0-next.4
reflect-metadata	^0.1.13
resend	^3.5.0
rimraf	^3.0.2
rollbar	^2.25.1
rxjs	7.0.0
sharp	^0.34.3
speakeasy	^2.0.0
swagger-ui-express	^5.0.1
telebot	^1.4.1
tslint	^6.1.3
twilio	^3.83.3
typeorm	^0.3.18
typeorm-naming-strategies	^2.0.0
uuid	^3.4.0
winston	^3.15.0
xlsx-js-style	^1.2.0
zod	^3.21.4

A seguir estão todas as dependências usadas pelo ambiente de desenvolvimento:

Dependência	Versão
@faker-js/faker	^9.8.0
@nestjs/cli	^7.0.0
@nestjs/schematics	^7.0.0
@nestjs/testing	^11.1.3
@types/bcrypt	^5.0.0
@types/cache-manager	^4.0.1
@types/cookie-parser	^1.4.7
@types/cron	^2.4.0
@types/crypto-js	^4.1.3
@types/ejs	^3.0.2
@types/express	^4.17.3
@types/html-pdf	^2.2.0
@types/jest	^30.0.0
@types/lodash	^4.14.195
@types/moment	^2.13.0
@types/multer	^1.4.7
@types/redis	^2.8.32
@types/speakeasy	^2.0.10
@types/supertest	^6.0.3
@types/uuid	^3.4.7
@typescript-eslint/eslint-plugin	3.9.1
@typescript-eslint/parser	3.9.1
dotenv-cli	^8.0.0
eslint	7.7.0
eslint-config-prettier	^6.10.0
eslint-plugin-import	^2.20.1
eslint-plugin-unused-imports	^3.0.0
jest	^30.0.2
prettier	^1.19.1
supertest	^7.1.1
ts-jest	^29.4.0
ts-loader	^6.2.1
ts-node	^10.9.1
tsconfig-paths	^3.9.0
typeorm-extension	^3.7.1
typescript	4.7

Ambiente de Desenvolvimento

Requisitos necessários

Software	Versão recomendada
Node.js	22
Git	2.43.0
Docker	28.3.2
PostgreSQL (via Docker)	17
Redis Stack (via Docker)	latest
Yarn	1.22.22
VS Code	1.102.2

Configurando o Ambiente de Desenvolvimento

Certifique-se primeiro que todos os softwares da tabela acima estejam instalados e funcionando na sua máquina.
Certifique-se de ter acesso a este repositório https://github.com/CSBBenk/api/
Certifique-se de ter configurado a chave SSH no Github, pois, ela será necessária para clonar, fazer push e pull no repositório. Caso não tenha feito, siga esses passos: https://docs.github.com/pt/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
Faça o clone do projeto com o comando abaixo:

git clone git@github.com:CSBBenk/api.git

Execute o PostgreSQL através de um container Docker com o comando abaixo:

docker run -d \
    --name pg-db \
    --restart unless-stopped \
    -e POSTGRES_PASSWORD=root \
    -p 5432:5432 \
    -v pg_data:/var/lib/postgresql/data \
    postgres:16

Execute o Redis Stack através de um container Docker com o comando abaixo:

docker run -d \
--name redis-stack \
-p 6379:6379 \
-p 8001:8001 \
redis/redis-stack:latest

Abra o projeto dentro do VS Code
Configure o arquivo .env, fazendo uma cópia do arquivo .env.example ou solicite ao gestor do projeto para repassar o .env atualizado.
No terminal, faça a instalação das dependências do projeto usando o comando abaixo:

yarn

Caso queira utilizar a base de dados local em branco, será necessário executar as migrações através do comando abaixo:

yarn migration:run

Para finalizar a configuração do banco de dados em branco, execute também as configurações de seed, para poder popular o banco com as configurações mínimas:

yarn run:seed

Execute a API no modo debug com o comando abaixo:

yarn start:dev

Em um navegador, chame a seguinte URL: http://localhost:3000/api
Se a documentação do swagger foi mostrada, sua API está executando corretamente e você pode seguir com o desenvolvimento.

Diagramas

C4 Model - Contexto

No diagrama C4 abaixo, está exemplificado o funcionamento a nível de contexto do sistema como um todo.

C4 Model - Container - Interação Cliente

C4 Model - Container - Interação Administrador Banco

Módulos

A estrutura seguida para organização dos módulos segue os padrões do NestJS, bem como busca manter próximos os arquivos com o seu contexto de utilização.

A seguir, a árvore de arquivos de todos os módulos da API:

.
├── src/
│   ├── app.module.ts
│   └── common/
│       ├── errors/
│       │   └── exception.module.ts
│       └── logger/
│           └── logger.module.ts
└── src/
    ├── modules/
    │   └── admin/
    │       ├── admin.module.ts
    │       ├── auth/
    │       │   └── admin.auth.module.ts
    │       ├── bank-account/
    │       │   └── admin.bank-account.module.ts
    │       ├── fee-settings/
    │       │   └── fee-settings.module.ts
    │       ├── logs/
    │       │   └── logs.module.ts
    │       ├── subscription-plan/
    │       │   └── subscription-plan.module.ts
    │       ├── systems/
    │       │   └── admin.systems.module.ts
    │       ├── transactions-limits/
    │       │   └── admin.transactions-limits.module.ts
    │       ├── users/
    │       │   └── admin.users.module.ts
    │       ├── users-admin/
    │       │   └── admin.users-admin.module.ts
    │       └── whitelist/
    │           └── admin.whitelist.module.ts
    ├── auth/
    │   └── auth.module.ts
    ├── auth/
    │   └── totp/
    │       └── totp.module.ts
    ├── castle/
    │   └── castle.module.ts
    ├── corporate-user-admin/
    │   └── corporate-user-admin.module.ts
    ├── cron-jobs/
    │   └── subscription-plan/
    │       └── subscription-plan.module.ts
    ├── cron-jobs/
    │   └── subscription-plans/
    │       └── process-plans.module.ts
    ├── customer/
    │   └── customer.module.ts
    ├── fee/
    │   ├── fee.module.ts
    │   └── fee-setting/
    │       └── fee-setting.module.ts
    ├── notifications/
    │   └── notification.module.ts
    ├── payments/
    │   ├── payment.module.ts
    │   ├── accounts/
    │   │   └── account.module.ts
    │   ├── admin/
    │   │   └── accounts/
    │   │       └── admin.accounts.module.ts
    │   ├── billets/
    │   │   └── billet.module.ts
    │   ├── favorites/
    │   │   └── favorites.module.ts
    │   ├── fee/
    │   │   └── payment-fee.module.ts
    │   ├── gateways/
    │   │   └── gateway.module.ts
    │   ├── gateways/
    │   │   └── celcoin/
    │   │       ├── celcoin.module.ts
    │   │       └── client/
    │   │           └── client.module.ts
    │   ├── incoming-webhooks/
    │   │   ├── incoming-webhooks.module.ts
    │   │   └── webhook-handlers/
    │   │       └── webhook-handler.module.ts
    │   ├── pix/
    │   │   └── pix.module.ts
    │   ├── subscription-plan/
    │   │   └── payment-subscription-plan.module.ts
    │   ├── ted/
    │   │   └── ted.module.ts
    │   ├── transactions-limits/
    │   │   └── transactions-limits.module.ts
    │   └── webhooks/
    │       └── webhooks.module.ts
    ├── public/
    │   ├── public.module.ts
    │   └── faq/
    │       └── faq.module.ts
    ├── subscription-plan/
    │   └── subscription-plan.module.ts
    ├── terms-acceptance/
    │   └── terms-acceptance.module.ts
    └── shared/
        ├── database/
        │   └── entities/
        │       └── subscription-plan-entities.module.ts
        ├── mail/
        │   └── templates/
        │       └── templates.module.ts
        ├── repositories/
        │   └── redis/
        │       └── redis.module.ts
        ├── resend/
        │   └── resend.module.ts
        └── services/
            ├── account-validation/
            │   └── account-validation.module.ts
            ├── subscription-plan/
            │   └── subscription-plan-service.module.ts
            └── whitelabels/
                └── whitelabels.module.ts

Rotas

Na sequência, está organizada a documentação de todas as rotas, divididas por controlador dentro da API.

Rotas de Contas (v1)

A seguir estão detalhadas as rotas da API disponíveis no AccountsController, responsável pelo fluxo de criação, consulta e gerenciamento de contas de clientes (PF e PJ).

Onboarding e Cadastro

Registrar Conta (PF/PJ)

Rota: POST /v1/accounts/register
Descrição: Endpoint para cadastro de pessoas físicas e jurídicas. Esta rota é destinada a um contexto de marketplace.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard) e que a requisição seja feita por um marketplace (IsMarketPlaceGuard).
Corpo da Requisição:
- O payload pode ser para Pessoa Física (tipo ‘F’) ou Pessoa Jurídica (tipo ‘J’). Veja os DTOs CreatePfAccountDTO e CreatePjAccountDTO para detalhes.
Respostas Possíveis:
- 200 OK: Conta criada com sucesso.
- 400 Bad Request: Payload inválido.

Criar Proposta de Onboarding

Rota: POST /v1/accounts/create-proposal
Descrição: Cria uma proposta de onboarding para um futuro cliente (PF ou PJ). Esta rota é protegida por chave privada.
Autenticação: Requer uma chave privada válida na requisição (PrivateKeyGuard).
Corpo da Requisição:
- O payload pode ser para Pessoa Física (tipo ‘F’) ou Pessoa Jurídica (tipo ‘J’).
Respostas Possíveis:
- 201 Created: Proposta criada com sucesso.
- 400 Bad Request: Payload inválido.

Consultar Proposta de Onboarding

Rota: GET /v1/accounts/check-proposal
Descrição: Consulta o status e os dados de uma proposta de onboarding.
Autenticação: Rota pública.
Parâmetros de Query:
- proposalId (string, obrigatório): O ID da proposta a ser consultada.
- documentNumber (string, opcional): O documento do cliente associado à proposta.
Respostas Possíveis:
- 200 OK: Retorna os dados da proposta.
- 404 Not Found: Cliente com o proposalId informado não encontrado.

Consultar Status da Conta

Rota: GET /v1/accounts/account-status
Descrição: Consulta o status atual de uma conta de cliente.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard).
Parâmetros de Query:
- proposalId (string, obrigatório): O ID da proposta associada à conta.
- documentNumber (string, opcional): O documento do cliente.
Respostas Possíveis:
- 200 OK: Retorna o status da conta.
- 404 Not Found: Cliente com o proposalId informado não encontrado.

Enviar Documentos (KYC)

Rota: POST /v1/accounts/kyc
Descrição: Envia os documentos (PDF) para o processo de Know Your Customer (KYC) junto ao provedor (Celcoin).
Autenticação: Requer um contexto de marketplace (IsMarketPlaceGuard).
Corpo da Requisição:

{
  "accountNumber": "123456789",
  "pdf": "base64_encoded_pdf_string",
  "postbackUrl": "https://seu-webhook.com/kyc-status"
}

Respostas Possíveis:
- 200 OK: Solicitação de KYC enviada com sucesso.

Gerenciamento da Conta

Gerar Token de Conta

Rota: POST /v1/accounts/generate-token
Descrição: Gera um token para uma conta específica.
Autenticação: Requer que a requisição venha de um IP na whitelist (IpAllowListGuard) e de um contexto de marketplace (IsMarketPlaceGuard).
Corpo da Requisição:

{
  "accountNumber": "123456789",
  "documentNumber": "11122233344"
}

Respostas Possíveis:
- 200 OK: Retorna o número da conta e o token gerado.

Enviar OTP para Encerramento de Conta

Rota: POST /v1/accounts/close-send-otp
Descrição: Envia um código de verificação (OTP) para o e-mail do usuário logado, como primeiro passo para o encerramento da conta.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard).
Respostas Possíveis:
- 200 OK: OTP enviado com sucesso.

Encerrar Conta

Rota: POST /v1/accounts/close
Descrição: Efetiva o encerramento da conta do cliente, validando com o OTP recebido.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard).
Corpo da Requisição:

{
  "otp": "123456"
}

Respostas Possíveis:
- 200 OK: Conta encerrada com sucesso.
- 400 Bad Request: OTP inválido ou erro no processo.

Consultas (Marketplace)

As rotas a seguir são destinadas ao uso por um marketplace para consultar contas de seus clientes.

Listar Contas do Marketplace

Rota: GET /v1/accounts/account-master
Descrição: Retorna uma lista paginada de todas as contas vinculadas ao marketplace autenticado.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard) e um contexto de marketplace (IsMarketPlaceGuard).
Parâmetros de Query:
- startDate (string, opcional): Data de início do filtro (formato YYYY-MM-DD).
- endDate (string, opcional): Data de fim do filtro (formato YYYY-MM-DDTHH:mm:ss).
- offset (number, opcional): Offset para paginação.
- limit (number, opcional): Limite de resultados por página.
Respostas Possíveis:
- 200 OK: Retorna a lista de contas.

Consultar Conta Única do Marketplace

Rota: GET /v1/accounts/account/single
Descrição: Busca e retorna os detalhes de uma conta específica vinculada ao marketplace.
Autenticação: Requer um token de acesso de cliente (AccessTokenGuard) e um contexto de marketplace (IsMarketPlaceGuard).
Parâmetros de Query:
- documentNumber (string, opcional): Documento do cliente.
- accountNumber (string, opcional): Número da conta.
Respostas Possíveis:
- 200 OK: Retorna os detalhes da conta.
- 404 Not Found: Conta não encontrada.

Rotas de Contas do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminAccountsController, responsável pelo gerenciamento e consulta de contas de clientes por um administrador.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Consulta de Contas e Usuários

Listar Contas de Clientes

Rota: GET /v1/admin/accounts
Descrição: Retorna uma lista paginada de todas as contas de clientes, com opções de filtro.
Parâmetros de Query:
- document (string, opcional): Filtra por um número de documento específico.
- name (string, opcional): Filtra pelo nome do titular da conta.
- page (number, opcional): Número da página para a paginação.
- limit (number, opcional): Quantidade de itens por página.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de contas.

Obter Visão Geral das Contas

Rota: GET /v1/admin/accounts/overview
Descrição: Retorna um resumo geral das contas, como total de contas ativas, pendentes, etc.
Respostas Possíveis:
- 200 OK: Retorna o objeto com a visão geral das contas.

Obter Visão Geral das Contas por Período

Rota: POST /v1/admin/accounts/overview/range
Descrição: Retorna um resumo geral das contas para um período de datas específico.
Corpo da Requisição:

{
  "startDate": "2023-01-01",
  "endDate": "2023-12-31"
}

Respostas Possíveis:
- 200 OK: Retorna o objeto com a visão geral das contas para o período.

Listar Usuários de Clientes

Rota: GET /v1/admin/accounts/users
Descrição: Retorna uma lista paginada de todos os usuários vinculados a contas de clientes.
Parâmetros de Query:
- document (string, opcional): Filtra por um número de documento específico.
- name (string, opcional): Filtra pelo nome do usuário.
- page (number, opcional): Número da página para a paginação.
- limit (number, opcional): Quantidade de itens por página.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de usuários.

Obter Detalhes de uma Conta por ID

Rota: GET /v1/admin/accounts/:id
Descrição: Busca e retorna os detalhes completos de uma conta de cliente específica com base no seu ID.
Parâmetros de URL:
- id (string, obrigatório): O ID do cliente.
Respostas Possíveis:
- 200 OK: Retorna o objeto da conta.
- 404 Not Found: Conta não encontrada.

Transações e Chaves PIX

Listar Chaves PIX de um Cliente

Rota: GET /v1/admin/accounts/pix-keys/:customerId
Descrição: Retorna todas as chaves PIX associadas a uma conta de cliente específica.
Parâmetros de URL:
- customerId (number, obrigatório): O ID do cliente.
Respostas Possíveis:
- 200 OK: Retorna um array com as chaves PIX do cliente.

Listar Transações de um Cliente

Rota: GET /v1/admin/accounts/transactions/:customerId
Descrição: Retorna uma lista paginada das transações de um cliente específico, com filtros.
Parâmetros de URL:
- customerId (number, obrigatório): O ID do cliente.
Parâmetros de Query:
- startDate, endDate (string, opcional): Filtro por período.
- transactionType (string, opcional): Filtro por tipo de transação.
- limit, offset (number, opcional): Para paginação.
Respostas Possíveis:
- 200 OK: Retorna a lista de transações.

Gerenciamento de Taxas

Listar Transações de Taxas de um Cliente

Rota: GET /v1/admin/accounts/fee-transactions/:customerId
Descrição: Retorna o histórico de cobrança de taxas de um cliente específico.
Parâmetros de URL:
- customerId (number, obrigatório): O ID do cliente.
Parâmetros de Query:
- startDate, endDate, limit, offset, transactionType (opcionais).
Respostas Possíveis:
- 200 OK: Retorna a lista de transações de taxas.

Obter Transação de Taxa por ID de Conciliação

Rota: GET /v1/admin/accounts/fee-transactions/:customerId/conciliationId/:conciliationId
Descrição: Busca uma transação de taxa específica pelo seu ID de conciliação.
Parâmetros de URL:
- customerId (number, obrigatório): O ID do cliente.
- conciliationId (string, obrigatório): O ID de conciliação da transação.
Respostas Possíveis:
- 200 OK: Retorna a transação de taxa encontrada.

Cobrar Taxa Manualmente

Rota: POST /v1/admin/accounts/fee-transactions/charge
Descrição: Realiza uma cobrança de taxa manual na conta de um cliente.
Corpo da Requisição:

{
  "customerId": 123,
  "amount": 500 // Valor em centavos
}

Respostas Possíveis:
- 201 Created: Cobrança realizada com sucesso.

Estornar Taxa Manualmente

Rota: POST /v1/admin/accounts/fee-transactions/refund
Descrição: Realiza o estorno de uma cobrança de taxa na conta de um cliente.
Corpo da Requisição:

{
  "conciliationId": "id-da-transacao-original"
}

Respostas Possíveis:
- 201 Created: Estorno realizado com sucesso.

Onboarding (KYC)

Obter Arquivos da Proposta

Rota: GET /v1/admin/accounts/customer/:id/proposal/files
Descrição: Busca e retorna os links para os arquivos (documentos) enviados durante o processo de onboarding (KYC) de um cliente.
Parâmetros de URL:
- id (string, obrigatório): O ID do cliente.
Respostas Possíveis:
- 200 OK: Retorna os dados dos arquivos da proposta.

Rotas de Autenticação do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminAuthController, responsável pela autenticação de usuários administradores.

Autenticação

Rota: POST /v1/admin/auth/signin
Descrição: Autentica um usuário administrador com base em seu documento e senha.
Lógica de Negócio:
- Valida as credenciais (documento e senha) do administrador.
- Se as credenciais forem válidas, gera um accessToken (curta duração) e um refreshToken (longa duração).
- O refreshToken é enviado como um cookie httpOnly e secure, garantindo que ele não possa ser acessado por scripts no lado do cliente.
- O accessToken e os dados básicos do usuário são retornados no corpo da resposta para serem usados em requisições subsequentes.
Corpo da Requisição:

{
  "document": "111.222.333-44",
  "password": "sua_senha_admin"
}

Respostas Possíveis:
- 200 OK: Login bem-sucedido. Retorna o accessToken e os dados do usuário. Define o cookie refreshToken.
- 400 Bad Request: Dados de entrada inválidos (validação do Zod).
- 401 Unauthorized: Credenciais incorretas (WrongCredentialsError).

Atualizar Token de Acesso (Refresh Token)

Rota: POST /v1/admin/auth/refresh-token
Descrição: Gera um novo accessToken utilizando um refreshToken válido que foi obtido durante o login.
Autenticação:
- Esta rota espera que um accessToken (mesmo que expirado) seja enviado no cabeçalho Authorization para identificar o userId.
- Também requer um refreshToken válido enviado como cookie na requisição.
Lógica de Negócio:
- Lê o refreshToken do cookie da requisição.
- Valida se o refreshToken é válido e se pertence ao usuário identificado pelo accessToken.
- Se a validação for bem-sucedida, gera e retorna um novo accessToken com tempo de expiração renovado.
Corpo da Requisição: Vazio.
Cookies Esperados:
- refreshToken (string, obrigatório): O token de atualização recebido no momento do login.
Respostas Possíveis:
- 200 OK: Retorna um novo accessToken.

{
  "accessToken": "novo_token_de_acesso_jwt"
}

401 Unauthorized: O cookie refreshToken está ausente, é inválido ou não corresponde ao usuário da sessão.

Rotas de Configuração de Taxas do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminFeeSettingsController, responsável pelo gerenciamento das configurações de taxas aplicadas nas transações dos clientes.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Configurações de Taxas

Listar Todas as Configurações de Taxas

Rota: GET /v1/admin/fee-settings
Descrição: Retorna uma lista com todas as configurações de taxas já criadas no sistema, independentemente de estarem ativas ou não.
Respostas Possíveis:
- 200 OK: Retorna um array com as configurações de taxas.
- 500 Internal Server Error: Erro interno no servidor.

Obter a Configuração de Taxa Ativa

Rota: GET /v1/admin/fee-settings/current
Descrição: Busca e retorna os detalhes da configuração de taxa que está atualmente em vigor no sistema.
Respostas Possíveis:
- 200 OK: Retorna o objeto da configuração de taxa ativa.
- 404 Not Found: Nenhuma configuração de taxa foi encontrada ou ativada.
- 500 Internal Server Error: Erro interno no servidor.

Criar Nova Configuração de Taxa

Rota: POST /v1/admin/fee-settings
Descrição: Cria um novo conjunto de regras de regras de taxação. Uma vez criada, esta configuração pode ser ativada através de outra rota.
Lógica de Negócio:
- A rota valida se já não existe uma configuração com a mesma descrição para evitar duplicidade.
- A criação da taxa é associada ao administrador que realizou a requisição.
Corpo da Requisição:

{
  "description": "Taxa Padrão PIX e TED",
  "settings": [
    {
      "operation": "DEBIT",
      "transactionType": "PIX",
      "feeAmount": 150, // Valor em centavos
      "monthlyFree": 5 // Quantidade de transações gratuitas no mês
    },
    {
      "operation": "DEBIT",
      "transactionType": "TED",
      "feeAmount": 800,
      "monthlyFree": 2
    }
  ]
}

Respostas Possíveis:
- 201 Created: Configuração de taxa criada com sucesso.
- 409 Conflict: Já existe uma configuração de taxa com a descrição informada.
- 500 Internal Server Error: Erro interno no servidor.

Ativar uma Configuração de Taxa

Rota: PATCH /v1/admin/fee-settings/:id/activate
Descrição: Ativa uma configuração de taxa específica com base no seu ID. Se outra configuração estiver ativa, ela será desativada para dar lugar à nova.
Parâmetros de URL:
- id (number, obrigatório): O ID da configuração de taxa a ser ativada.
Lógica de Negócio:
- Impede a ativação de uma configuração que já está ativa.
- A ativação é registrada em nome do administrador que realizou a requisição.
Respostas Possíveis:
- 200 OK: Configuração ativada com sucesso.
- 400 Bad Request: A configuração de taxa informada já está ativa.
- 404 Not Found: Nenhuma configuração de taxa encontrada com o ID fornecido.
- 500 Internal Server Error: Erro interno no servidor.

Rotas de Planos de Assinatura do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminSubscriptionPlanController, responsável pelo gerenciamento dos planos de assinatura que podem ser atribuídos aos clientes.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Planos de Assinatura

Listar Todos os Planos de Assinatura

Rota: GET /v1/admin/subscription-plans
Descrição: Retorna uma lista com todos os planos de assinatura criados no sistema, incluindo os que estão publicados (ativos) e os que não estão.
Respostas Possíveis:
- 200 OK: Retorna um array com os planos de assinatura.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Criar Novo Plano de Assinatura

Rota: POST /v1/admin/subscription-plans
Descrição: Cria um novo plano de assinatura com suas respectivas regras de transações gratuitas.
Lógica de Negócio:
- Valida se já não existe um plano com o mesmo nome.
- Associa a criação do plano ao administrador que está realizando a requisição.
Corpo da Requisição:

{
  "name": "Plano Básico PF",
  "description": "Plano para pessoas físicas com transações básicas.",
  "pricePerMonth": 1990, // Valor em centavos
  "customerType": "PF", // "PF" ou "PJ"
  "transactionSettings": [
    {
      "operation": "DEBIT",
      "transactionType": "PIX",
      "monthlyFree": 10
    },
    {
      "operation": "DEBIT",
      "transactionType": "TED",
      "monthlyFree": 2
    }
  ]
}

Respostas Possíveis:
- 201 Created: Plano de assinatura criado com sucesso.
- 400 Bad Request: Dados de entrada inválidos.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 409 Conflict: Já existe um plano com o nome informado.
- 500 Internal Server Error: Erro interno no servidor.

Publicar um Plano de Assinatura

Rota: PATCH /v1/admin/subscription-plans/:id/publish
Descrição: Torna um plano de assinatura “público”, ou seja, disponível para ser atribuído a novos clientes.
Parâmetros de URL:
- id (number, obrigatório): O ID do plano de assinatura a ser publicado.
Respostas Possíveis:
- 200 OK: Plano publicado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Plano de assinatura não encontrado com o ID fornecido.
- 500 Internal Server Error: Erro interno no servidor.

Despublicar um Plano de Assinatura

Rota: PATCH /v1/admin/subscription-plans/:id/unpublish
Descrição: “Despublica” um plano de assinatura, tornando-o indisponível para novas atribuições. Os clientes que já possuem o plano não são afetados.
Parâmetros de URL:
- id (number, obrigatório): O ID do plano de assinatura a ser despublicado.
Respostas Possíveis:
- 200 OK: Plano despublicado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Plano de assinatura não encontrado com o ID fornecido.
- 500 Internal Server Error: Erro interno no servidor.

Obter Configurações de Assinatura

Rota: GET /v1/admin/subscription-plans/settings
Descrição: Retorna as configurações globais relacionadas à cobrança de assinaturas, como o modo de cobrança e o dia do pagamento.
Respostas Possíveis:
- 200 OK: Retorna o objeto de configurações.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Rotas de Parâmetros do Sistema (Admin v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminSystemsController, responsável pelo gerenciamento de parâmetros e configurações gerais do sistema.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Parâmetros do Sistema

Listar Parâmetros do Sistema (Paginado)

Rota: GET /v1/admin/systems
Descrição: Retorna uma lista paginada de todos os parâmetros de configuração do sistema, com possibilidade de filtro.
Parâmetros de Query:
- parameter (string, opcional): Filtra por um nome de parâmetro específico.
- page (number, opcional): Número da página para a paginação.
- limit (number, opcional): Quantidade de itens por página.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de parâmetros.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Consultar Parâmetro Específico

Rota: GET /v1/admin/systems/:parameter
Descrição: Busca e retorna o valor de um parâmetro de sistema específico pelo seu nome.
Parâmetros de URL:
- parameter (string, obrigatório): O nome do parâmetro a ser consultado (ex: bank_account, subscription_settings).
Respostas Possíveis:
- 200 OK: Retorna o objeto do parâmetro encontrado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Parâmetro não encontrado.

Atualizar Parâmetro Específico

Rota: PATCH /v1/admin/systems/:parameter
Descrição: Atualiza o valor de um parâmetro de sistema existente.
Parâmetros de URL:
- parameter (string, obrigatório): O nome do parâmetro a ser atualizado.
Corpo da Requisição:

{
  "value": { "novo": "valor" } // O conteúdo de 'value' pode ser qualquer objeto JSON válido
}

Respostas Possíveis:
- 200 OK: Parâmetro atualizado com sucesso. Retorna o objeto do parâmetro atualizado.
- 400 Bad Request: Dados de entrada inválidos (validação do Zod).
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Parâmetro não encontrado para atualização.

Rotas de Limites de Transação do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminTransactionsLimitsController, responsável por gerenciar as solicitações de alteração de limites transacionais dos clientes.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Solicitações de Limite de Transação

Listar Solicitações Pendentes de Aprovação

Rota: GET /v1/admin/transaction-limits/pending-approval
Descrição: Retorna uma lista paginada de todas as solicitações de alteração de limite de transação que estão aguardando análise (status “pendente”).
Parâmetros de Query:
- page (number, opcional): Número da página para a paginação.
- limit (number, opcional): Quantidade de itens por página.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de solicitações pendentes.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Aprovar Solicitação de Alteração de Limite

Rota: POST /v1/admin/transaction-limits/approve
Descrição: Aprova uma solicitação de alteração de limite. Ao ser aprovada, o novo limite de transação do cliente é efetivado.
Lógica de Negócio: O serviço atualiza o status da solicitação para “APROVADO” e aplica os novos valores de limite na conta do cliente correspondente.
Corpo da Requisição:

{
  "id": 123,
  "status": "APPROVED"
}

Respostas Possíveis:
- 201 Created: Solicitação aprovada e limites atualizados com sucesso.
- 400 Bad Request: A solicitação ou o limite de transação associado não foi encontrado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Rejeitar Solicitação de Alteração de Limite

Rota: POST /v1/admin/transaction-limits/reject
Descrição: Rejeita uma solicitação de alteração de limite. O limite do cliente permanece inalterado.
Lógica de Negócio: O serviço atualiza o status da solicitação para “REJEITADO”.
Corpo da Requisição:

{
  "id": 123,
  "status": "REJECTED"
}

Respostas Possíveis:
- 201 Created: Solicitação rejeitada com sucesso.
- 400 Bad Request: A solicitação ou o limite de transação associado não foi encontrado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Rotas de Usuários Administradores (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminUsersAdminController, responsável pelo gerenciamento de outros usuários administradores do sistema.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Usuários Administradores

Listar Todos os Usuários Administradores

Rota: GET /v1/admin/users-admin/get-all-users
Descrição: Retorna uma lista paginada de todos os usuários administradores, com opções de filtro e ordenação.
Parâmetros de Query:
- limit (number, opcional): Número máximo de itens por página. Padrão: 10.
- page (number, opcional): Número da página. Padrão: 1.
- orderBy (string, opcional): Campo para ordenação (ex: ‘id’, ‘name’, ‘email’). Padrão: ‘id’.
- search (string, opcional): Termo de busca para nome ou email.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de usuários.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 500 Internal Server Error: Erro interno no servidor.

Obter um Usuário Administrador por ID

Rota: GET /v1/admin/users-admin/get-user/:id
Descrição: Busca e retorna os detalhes de um usuário administrador específico com base no seu ID.
Parâmetros de URL:
- id (number, obrigatório): O ID do usuário administrador a ser buscado.
Respostas Possíveis:
- 200 OK: Retorna o objeto do usuário encontrado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Usuário não encontrado.
- 500 Internal Server Error: Erro interno no servidor.

Obter Dados do Usuário Logado

Rota: GET /v1/admin/users-admin/my-user
Descrição: Retorna os detalhes do usuário administrador que está atualmente autenticado, com base no token de acesso.
Respostas Possíveis:
- 200 OK: Retorna o objeto do usuário logado.
- 401 Unauthorized: Token de acesso inválido ou ausente.

Criar Novo Usuário Administrador

Rota: POST /v1/admin/users-admin/
Descrição: Cria um novo usuário administrador no sistema.
Corpo da Requisição:

{
  "name": "Novo Admin",
  "email": "novo.admin@exemplo.com",
  "phoneNumber": "11987654321",
  "password": "senha_forte_123",
  "isActive": true,
  "originIp": "192.168.1.100",
  "document": "11122233344"
}

Respostas Possíveis:
- 201 Created: Usuário criado com sucesso. Retorna os dados do novo usuário.
- 401 Unauthorized: Token de acesso inválido ou ausente.

Atualizar Usuário Administrador

Rota: PATCH /v1/admin/users-admin/update-admin
Descrição: Atualiza os dados de um usuário administrador. Se o campo id não for fornecido no corpo, a rota atualizará os dados do próprio usuário logado.
Corpo da Requisição:

{
  "id": 2, // Opcional. Se omitido, atualiza o usuário logado.
  "name": "Admin Atualizado", // Opcional
  "email": "admin.atualizado@exemplo.com", // Opcional
  "phoneNumber": "11999998888", // Opcional
  "isActive": false // Opcional
}

Respostas Possíveis:
- 200 OK: Usuário atualizado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Usuário não encontrado.

Atualizar Senha de Usuário Administrador

Rota: PATCH /v1/admin/users-admin/update-password
Descrição: Atualiza a senha de um usuário administrador. Se o campo id não for fornecido no corpo, a rota atualizará a senha do próprio usuário logado.
Corpo da Requisição:

{
  "id": 2, // Opcional. Se omitido, atualiza a senha do usuário logado.
  "password": "nova_senha_super_forte"
}

Respostas Possíveis:
- 200 OK: Senha atualizada com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Usuário não encontrado.

Deletar Usuário Administrador

Rota: DELETE /v1/admin/users-admin/:id
Descrição: Remove permanentemente um usuário administrador do sistema.
Parâmetros de URL:
- id (number, obrigatório): O ID do usuário administrador a ser deletado.
Respostas Possíveis:
- 200 OK: Usuário deletado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Usuário não encontrado.

Rotas de Usuários do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminUsersController, responsável pelo gerenciamento de usuários do sistema por um administrador.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Usuários

Atualizar E-mail e Status de um Usuário

Rota: PATCH /v1/admin/users/update
Descrição: Atualiza o e-mail e/ou o status (ativo/inativo) de um usuário específico do sistema.
Lógica de Negócio: O serviço localiza o usuário pelo ID fornecido e atualiza os campos email e status conforme o payload da requisição.
Corpo da Requisição:

{
  "id": 123,
  "email": "usuario.atualizado@exemplo.com",
  "status": "INACTIVE"
}

Observação: Os campos email e status são opcionais. Você pode enviar apenas um deles para atualização.
Respostas Possíveis:
- 200 OK: Usuário atualizado com sucesso.
- 400 Bad Request: Dados de entrada inválidos (validação do Zod).
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Usuário com o ID informado não foi encontrado.
- 500 Internal Server Error: Erro interno no servidor.

Rotas de Whitelist do Admin (v1)

A seguir estão detalhadas as rotas da API disponíveis no AdminWhitelistController, responsável pelo gerenciamento da lista de documentos (CPFs/CNPJs) autorizados a se cadastrarem no sistema.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de administrador válido (AdminAccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento da Whitelist

Listar Documentos na Whitelist

Rota: GET /v1/admin/whitelist
Descrição: Retorna uma lista paginada de todos os documentos na whitelist, com opções de filtro.
Parâmetros de Query:
- document (string, opcional): Filtra por um número de documento específico.
- name (string, opcional): Filtra pelo nome associado ao documento.
- page (number, opcional): Número da página para a paginação.
- limit (number, opcional): Quantidade de itens por página.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de documentos.
- 401 Unauthorized: Token de acesso inválido ou ausente.

Obter Documento da Whitelist por ID

Rota: GET /v1/admin/whitelist/:id
Descrição: Busca e retorna os detalhes de um registro específico da whitelist com base no seu ID.
Parâmetros de URL:
- id (number, obrigatório): O ID do registro na whitelist.
Respostas Possíveis:
- 200 OK: Retorna o objeto do registro encontrado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Registro não encontrado.

Registrar Novo Documento na Whitelist

Rota: POST /v1/admin/whitelist
Descrição: Adiciona um novo documento (CPF/CNPJ) à whitelist, permitindo que ele seja usado para um futuro cadastro de cliente.
Corpo da Requisição:

{
  "document": "11122233344",
  "name": "Nome do Titular",
  "type": "PF"
}

Respostas Possíveis:
- 201 Created: Documento registrado na whitelist com sucesso.
- 400 Bad Request: Dados de entrada inválidos (validação do Zod).
- 401 Unauthorized: Token de acesso inválido ou ausente.

Atualizar Informações de um Documento na Whitelist

Rota: PATCH /v1/admin/whitelist/:id
Descrição: Atualiza as informações (nome, tipo) de um documento já existente na whitelist.
Parâmetros de URL:
- id (number, obrigatório): O ID do registro a ser atualizado.
Corpo da Requisição:

{
  "name": "Nome Atualizado do Titular"
}

Respostas Possíveis:
- 200 OK: Registro atualizado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Registro não encontrado.

Deletar Documento da Whitelist

Rota: DELETE /v1/admin/whitelist/:id
Descrição: Remove um documento da whitelist, impedindo futuros cadastros com ele.
Parâmetros de URL:
- id (number, obrigatório): O ID do registro a ser deletado.
Respostas Possíveis:
- 200 OK: Registro deletado com sucesso.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: Registro não encontrado.

Rotas de Boletos (v1)

A seguir estão detalhadas as rotas da API disponíveis no BilletController, responsável pelo gerenciamento de boletos de cobrança, pagamentos de contas e funcionalidades de DDA (Débito Direto Autorizado).

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

DDA (Débito Direto Autorizado)

Listar Boletos DDA

Rota: GET /v1/customer/dda-billets
Descrição: Retorna uma lista paginada de boletos de DDA para o cliente.
Parâmetros de Query:
- limit, offset (number, opcional): Para paginação.
- name, document (string, opcional): Filtra pelo nome ou documento do sacado.
- dueDate (string, opcional): Filtra pela data de vencimento (YYYY-MM-DD).
- status (string, opcional): Filtra pelo status (OPEN, PAID).
- isScheduledForPayment, isHidden (boolean, opcional): Filtra por boletos agendados ou ocultos.
- digitableOrCodeBar (string, opcional): Busca pela linha digitável ou código de barras.
Respostas Possíveis:
- 200 OK: Retorna a lista paginada de boletos DDA.

Agendar/Cancelar Pagamento de Boleto DDA

Rota: PATCH /v1/customer/dda-billets/schedule-payment/:id
Descrição: Ativa ou desativa o pagamento automático para um boleto DDA.
Lógica de Negócio: Requer senha transacional (TransactionPasswordGuard) e permissão para transacionar (TransactionPermissionGuard).
Parâmetros de URL:
- id (number, obrigatório): ID do boleto DDA.
Corpo da Requisição:

{
  "isScheduledForPayment": true, // ou false
  "transactionPassword": "sua_senha_transacional"
}

Respostas Possíveis:
- 200 OK: Agendamento atualizado com sucesso.
- 403 Forbidden: Senha transacional incorreta ou permissão negada.

Ocultar/Reexibir Boleto DDA

Rota: PATCH /v1/customer/dda-billets/hide/:id
Descrição: Altera a visibilidade de um boleto DDA na listagem padrão.
Parâmetros de URL:
- id (number, obrigatório): ID do boleto DDA.
Corpo da Requisição:

{
  "isHidden": true // ou false
}

Respostas Possíveis:
- 200 OK: Visibilidade do boleto atualizada com sucesso.

Cancelar Adesão ao DDA

Rota: DELETE /v1/customer/dda-register
Descrição: Inicia o processo de cancelamento da adesão do cliente ao DDA.
Respostas Possíveis:
- 200 OK: Solicitação de cancelamento recebida com sucesso.

Pagamento de Contas

Efetivar Pagamento de Boleto

Rota: POST /v1/customer/transactions/bill-payment
Descrição: Efetiva o pagamento de um boleto.
Lógica de Negócio:
- Se o usuário logado for um Consultor (UserRoleConsultantCashoutGuard): A operação cria uma solicitação de transação que fica pendente de aprovação, em vez de executar o pagamento imediatamente.
- Se o usuário logado tiver permissão para transacionar (ex: Administrador ou Aprovador): O pagamento é processado na hora, após validação da senha transacional (TransactionPasswordGuard) e dos limites da conta.
Corpo da Requisição:

{
  "amount": 50000,
  "transactionPassword": "sua_senha_transacional",
  "barCode": {
    "digitable": "23793381286008348323423434000000195890000012345"
  }
}

Respostas Possíveis:
- 200 OK: Pagamento realizado ou solicitação criada com sucesso.
- 403 Forbidden: Senha transacional incorreta, permissões insuficientes ou limite excedido.

Verificar Status do Pagamento de Boleto

Rota: GET /v1/customer/transactions/bill-payment
Descrição: Verifica o status de um pagamento de boleto realizado.
Parâmetros de Query:
- conciliationId (string, obrigatório): ID de conciliação retornado na efetivação do pagamento.
Respostas Possíveis:
- 200 OK: Retorna o status do pagamento.

Boletos de Cobrança

Emitir Boleto de Cobrança

Rota: POST /v1/customer/transactions/charge-bill
Descrição: Gera um novo boleto de cobrança para um cliente (pagador).
Corpo da Requisição:

{
  "externalId": "cobranca-servico-123",
  "amount": 25000,
  "duedate": "2024-12-31",
  "debtor": {
    "name": "Cliente Pagador Exemplo",
    "document": "11122233344",
    "city": "São Paulo",
    "state": "SP",
    "neighborhood": "Centro",
    "publicArea": "Avenida Principal",
    "number": "123",
    "zipCode": "01000000"
  }
}

Respostas Possíveis:
- 201 Created: Boleto emitido com sucesso.

Consultar Boleto por ID Externo

Rota: GET /v1/customer/transactions/charge-bill
Descrição: Busca os detalhes de um boleto de cobrança pelo ID externo fornecido na criação.
Parâmetros de Query:
- externalId (string, obrigatório): ID externo do boleto.
Respostas Possíveis:
- 200 OK: Retorna os dados do boleto.
- 404 Not Found: Boleto não encontrado.

Cancelar Boleto

Rota: DELETE /v1/customer/transactions/charge-bill
Descrição: Cancela um boleto de cobrança que ainda não foi pago.
Parâmetros de Query:
- externalId (string, obrigatório): ID externo do boleto.
Respostas Possíveis:
- 200 OK: Boleto cancelado com sucesso.
- 404 Not Found: Boleto não encontrado.

Baixar PDF do Boleto

Rota: GET /v1/customer/transactions/charge-bill-pdf
Descrição: Retorna o arquivo PDF de um boleto de cobrança emitido.
Parâmetros de Query:
- externalId (string, obrigatório): ID externo do boleto.
Respostas Possíveis:
- 200 OK: Retorna o arquivo PDF para download.
- 404 Not Found: Boleto não encontrado.

Pagamento de Contas

Validar Boleto para Pagamento

Rota: POST /v1/customer/transactions/bill-payment-authorize
Descrição: Valida uma linha digitável de um boleto. Se for válido, retorna os detalhes (valor, vencimento, etc.) para confirmação do pagamento.
Corpo da Requisição:

{
  "barCode": {
    "digitable": "23793381286008348323423434000000195890000012345"
  }
}

Respostas Possíveis:
- 201 Created: Boleto validado com sucesso e pronto para pagamento.
- 400 Bad Request: Linha digitável inválida.

Efetivar Pagamento de Boleto

Rota: POST /v1/customer/transactions/bill-payment
Descrição: Efetiva o pagamento de um boleto previamente validado.
Lógica de Negócio:
- Requer senha transacional (transactionPassword).
- Se o usuário for Consultor, cria uma solicitação de pagamento pendente de aprovação.
- Para outros usuários, executa o pagamento diretamente após validar os limites.
Corpo da Requisição:

{
  "amount": 50000, // Valor em centavos
  "transactionPassword": "sua_senha_transacional",
  "barCode": {
    "digitable": "23793381286008348323423434000000195890000012345"
  }
}

Respostas Possíveis:
- 200 OK: Pagamento realizado ou solicitação criada com sucesso.
- 400 Bad Request: Dados inválidos ou saldo insuficiente.
- 403 Forbidden: Senha transacional incorreta.

Verificar Status do Pagamento de Boleto

Rota: GET /v1/customer/transactions/bill-payment
Descrição: Verifica o status de um pagamento de boleto realizado.
Parâmetros de Query:
- conciliationId (string, obrigatório): ID de conciliação retornado na efetivação do pagamento.
Respostas Possíveis:
- 200 OK: Retorna o status do pagamento.
- 404 Not Found: Pagamento não encontrado.

DDA (Débito Direto Autorizado)

Cadastrar Cliente no DDA

Rota: POST /v1/customer/dda-register
Descrição: Inicia o processo de adesão do cliente ao serviço de DDA.
Respostas Possíveis:
- 201 Created: Solicitação de adesão ao DDA recebida.
- 400 Bad Request: O cliente já está cadastrado ou houve um erro.

Cancelar Adesão ao DDA

Rota: DELETE /v1/customer/dda-register
Descrição: Inicia o processo de cancelamento da adesão do cliente ao DDA.
Respostas Possíveis:
- 200 OK: Solicitação de cancelamento recebida.
- 400 Bad Request: O cliente não está cadastrado ou houve um erro.

Consultar Status da Adesão ao DDA

Rota: GET /v1/customer/dda-customer
Descrição: Verifica e retorna o status atual da adesão do cliente ao DDA.
Respostas Possíveis:
- 200 OK: Retorna o status da adesão (ex: CREATED, ACTIVE).
- 404 Not Found: Cliente sem adesão ao DDA.

Listar Boletos DDA

Rota: GET /v1/customer/dda-billets
Descrição: Retorna uma lista paginada de boletos de DDA para o cliente.
Parâmetros de Query:
- limit, offset (number, opcional): Para paginação.
- name, document (string, opcional): Filtra pelo nome ou documento do sacado.
- dueDate (string, opcional): Filtra pela data de vencimento (YYYY-MM-DD).
- status (string, opcional): Filtra pelo status (OPEN, PAID).
- isScheduledForPayment, isHidden (boolean, opcional): Filtra por boletos agendados ou ocultos.
- digitableOrCodeBar (string, opcional): Busca pela linha digitável ou código de barras.
Respostas Possíveis:
- 200 OK: Retorna a lista de boletos DDA.
- 400 Bad Request: Cliente não cadastrado no DDA.

Agendar/Cancelar Pagamento de Boleto DDA

Rota: PATCH /v1/customer/dda-billets/schedule-payment/:id
Descrição: Ativa ou desativa o pagamento automático para um boleto DDA.
Lógica de Negócio: Requer senha transacional para autorização.
Parâmetros de URL:
- id (number, obrigatório): ID do boleto DDA.
Corpo da Requisição:

{
  "isScheduledForPayment": true, // ou false
  "transactionPassword": "sua_senha_transacional"
}

Respostas Possíveis:
- 200 OK: Agendamento atualizado com sucesso.
- 400 Bad Request: Boleto não encontrado ou inválido.
- 403 Forbidden: Senha transacional incorreta.

Ocultar/Reexibir Boleto DDA

Rota: PATCH /v1/customer/dda-billets/hide/:id
Descrição: Altera a visibilidade de um boleto DDA na listagem padrão.
Parâmetros de URL:
- id (number, obrigatório): ID do boleto DDA.
Corpo da Requisição:

{
  "isHidden": true // ou false
}

Respostas Possíveis:
- 200 OK: Visibilidade do boleto atualizada com sucesso.
- 400 Bad Request: Boleto não encontrado.

Rotas de Administração de Usuários Corporativos (v1)

A seguir estão detalhadas as rotas da API disponíveis no CorporateUserAdminController, responsável pelo gerenciamento de usuários vinculados a uma conta corporativa (PJ).

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso válido (AccessTokenGuard). Além disso, o acesso é restrito a clientes do tipo “Pessoa Jurídica” (CorporateCustomerTypeGuard).

Fluxo de Convite e Criação de Usuários

Enviar OTP para Criar Novo Usuário

Rota: POST /v1/corporate-admin/create-user-send-otp
Descrição: Envia um código de verificação (OTP) para o e-mail do administrador logado. Este OTP será necessário para confirmar a criação de um novo usuário.
Respostas Possíveis:
- 201 Created: OTP enviado com sucesso.
- 400 Bad Request: Erro ao enviar o e-mail (ex: já enviado recentemente).
- 401 Unauthorized: Token de acesso inválido.
- 404 Not Found: Cliente não encontrado.

Convidar Novo Usuário

Rota: POST /v1/corporate-admin/invite-user
Descrição: Cria e convida um novo usuário para a conta corporativa, associando-o a um perfil (role).
Lógica de Negócio:
- Valida o OTP enviado pelo administrador logado.
- Cria o novo usuário com os dados fornecidos e o vincula à conta corporativa.
- Envia um e-mail de convite para o novo usuário.
Corpo da Requisição:

{
  "otp": "123456",
  "name": "Nome do Novo Usuário",
  "email": "novo.usuario@empresa.com",
  "document": "11122233344",
  "role": "CONSULTOR"
}

Respostas Possíveis:
- 201 Created: Usuário convidado com sucesso.
- 400 Bad Request: OTP inválido ou dados incorretos.
- 409 Conflict: Já existe um usuário com o e-mail ou documento informado.

Reenviar Convite para Usuário

Rota: POST /v1/corporate-admin/resend-invite/:id
Descrição: Reenvia o e-mail de convite para um usuário que ainda não ativou sua conta.
Parâmetros de URL:
- id (number, obrigatório): O ID do usuário para o qual o convite será reenviado.
Respostas Possíveis:
- 201 Created: Convite reenviado com sucesso.
- 404 Not Found: Usuário não encontrado.
- 409 Conflict: O usuário já está ativo e não pode receber um novo convite.

Gerenciamento de Usuários

Listar Usuários da Conta Corporativa

Rota: GET /v1/corporate-admin/list-users
Descrição: Retorna uma lista paginada de todos os usuários associados à conta corporativa do cliente logado.
Parâmetros de Query:
- limit, offset (number, opcional): Para paginação.
- id (number, opcional): Filtra por um ID de usuário específico.
- name (string, opcional): Busca por nome (case-insensitive).
- document (string, opcional): Filtra por documento (CPF).
- type (enum, opcional): Filtra pelo perfil do usuário (ADMINISTRADOR, APROVADOR, CONSULTOR).
- isActive (boolean, opcional): Filtra por status (ativo/inativo).
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de usuários.

Enviar OTP para Desativar Usuário

Rota: POST /v1/corporate-admin/delete-user-send-otp
Descrição: Envia um código de verificação (OTP) para o e-mail do administrador logado. Este OTP será necessário para confirmar a desativação de um usuário.
Respostas Possíveis:
- 201 Created: OTP enviado com sucesso.
- 401 Unauthorized: Token de acesso inválido.
- 404 Not Found: Cliente não encontrado.

Desativar um Usuário

Rota: POST /v1/corporate-admin/deactivate-user
Descrição: Desativa um usuário da conta corporativa, impedindo seu acesso ao sistema.
Lógica de Negócio: Valida o OTP do administrador logado antes de proceder com a desativação.
Corpo da Requisição:

{
  "otp": "123456",
  "userId": 25
}

Respostas Possíveis:
- 201 Created: Usuário desativado com sucesso.
- 404 Not Found: Usuário a ser desativado não encontrado.
- 409 Conflict: O usuário já está inativo ou a operação não é permitida (ex: tentar desativar a si mesmo).

Gerenciamento de Perfis (Roles)

Enviar OTP para Atualizar Perfil de Usuário

Rota: POST /v1/corporate-admin/update-user-send-otp
Descrição: Envia um código de verificação (OTP) para o e-mail do administrador logado. Este OTP será necessário para confirmar a alteração do perfil de um usuário.
Respostas Possíveis:
- 201 Created: OTP enviado com sucesso.
- 401 Unauthorized: Token de acesso inválido.
- 404 Not Found: Cliente não encontrado.

Atualizar Perfil de um Usuário

Rota: POST /v1/corporate-admin/update-user-role
Descrição: Altera o perfil (role) de um usuário dentro da conta corporativa.
Lógica de Negócio: Valida o OTP do administrador logado antes de proceder com a alteração.
Corpo da Requisição:

{
  "otp": "123456",
  "userId": 25,
  "role": "APROVADOR"
}

Respostas Possíveis:
- 201 Created: Perfil do usuário atualizado com sucesso.
- 400 Bad Request: OTP inválido.
- 409 Conflict: O usuário já possui o perfil informado.

Rotas de Cliente (v1)

A seguir estão detalhadas as rotas da API disponíveis no CustomerV1Controller, responsável por gerenciar as operações do cliente.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Saldo e Extrato

Obter Saldo

Rota: GET /v1/customer/balance
Descrição: Busca e retorna o saldo atual da conta de pagamento do cliente.
Respostas Possíveis:
- 200 OK: Retorna o objeto de saldo com sucesso.
- 404 Not Found: Conta do cliente não encontrada.
- 500 Internal Server Error: Erro interno no servidor.

Exportar Extrato

Rota: GET /v1/customer/export-statement
Descrição: Gera e baixa um arquivo de extrato para um período selecionado, nos formatos PDF, CSV ou OFX.
Parâmetros de Query:
- startDate (string, obrigatório): Data de início do período (formato YYYY-MM-DD).
- endDate (string, obrigatório): Data de fim do período (formato YYYY-MM-DD).
- extensionType (string, obrigatório): Formato do arquivo (pdf, csv, ofx).
- transactionType (string, opcional): Filtra por um tipo de transação específico.
Lógica de Negócio: O serviço busca as transações no período, formata os dados de acordo com a extensão solicitada e retorna o arquivo com os cabeçalhos HTTP apropriados para download.
Respostas Possíveis:
- 200 OK: Retorna o arquivo de extrato para download.
- 400 Bad Request: Período ou tipo de extensão inválido.

Transações PIX

Gerar QR Code PIX (Cash-in)

Rota: POST /v1/customer/transactions
Descrição: Gera um QR Code para receber um pagamento PIX.
Corpo da Requisição:

{
  "paymentMethod": "pix",
  "amount": 1000, // em centavos
  "pix": {
    "expiresAt": "2023-12-31 23:59:59",
    "description": "Descrição do pagamento",
    "conciliationId": "id-unico-da-cobranca"
  },
  "postbackUrl": "https://seu-webhook.com/notificacao",
  "ip": "192.168.1.1"
}

Respostas Possíveis:
- 201 Created: Retorna os dados do QR Code (qrCode, encodedValue).
- 400 Bad Request: Dados inválidos no payload.
- 500 Internal Server Error: Erro interno no servidor.

Realizar PIX (Cash-out por Chave)

Rota: POST /v1/customer/transactions/cashout
Descrição: Efetua uma transferência PIX para uma chave específica ou a partir de um QR Code (EMV).
Lógica de Negócio:
- Requer senha transacional (transactionPassword) no corpo da requisição.
- Se o usuário logado for do tipo Consultor, cria uma solicitação de transação que necessita de aprovação, em vez de executar a transação imediatamente.
- Para outros usuários, executa a transação diretamente após validar os limites.
Corpo da Requisição:

{
  "amount": 1500, // em centavos
  "transactionPassword": "sua_senha_transacional",
  "pixKey": {
    "type": "CPF",
    "key": "11122233344"
  },
  "description": "Pagamento de serviço"
}

Respostas Possíveis:
- 201 Created: Transação ou solicitação criada com sucesso.
- 400 Bad Request: Dados inválidos, conciliationId já em uso, ou tentativa de transferência para a própria conta.
- 403 Forbidden: Senha transacional incorreta ou permissões insuficientes.

Realizar PIX (Cash-out por Dados Bancários)

Rota: POST /v1/customer/transactions/cashout/direct
Descrição: Efetua uma transferência PIX informando os dados bancários do destinatário.
Lógica de Negócio: Idêntica à rota de cash-out por chave. Usuários Consultor criam uma solicitação pendente; outros usuários executam a transação diretamente.
Corpo da Requisição:

{
  "amount": 15050,
  "transactionPassword": "sua_senha_transacional",
  "recipient": {
    "name": "Maria da Silva",
    "document": "11122233344",
    "account": {
      "bank": "001", // Código do Banco do Brasil
      "branch": "1234",
      "accountNumber": "567890",
      "accountType": "CACC" // CACC para Corrente, POUP para Poupança
    }
  }
}

Respostas Possíveis:
- 200 OK: Transação ou solicitação criada com sucesso.
- 400 Bad Request: Dados inválidos ou violação de regras de negócio (ex: limite excedido).
- 403 Forbidden: Senha transacional incorreta ou permissões insuficientes.

Consultar Transação por ID de Conciliação

Rota: GET /v1/customer/transactions/:conciliationId/conciliation
Descrição: Retorna os detalhes de uma transação específica com base no seu ID de conciliação.
Parâmetros de URL:
- conciliationId (string, obrigatório): ID de conciliação da transação.
Respostas Possíveis:
- 200 OK: Retorna o objeto da transação.
- 404 Not Found: Transação não encontrada.

Estornar Transação PIX por EndToEndId

Rota: POST /v1/customer/transactions/:endToEndId/refund/e2e
Descrição: Inicia o processo de devolução de uma transação PIX utilizando o EndToEndId da transação original.
Parâmetros de URL:
- endToEndId (string, obrigatório): O EndToEndId da transação a ser estornada.
Lógica de Negócio: Requer permissão específica para estorno (TransactionPermissionGuard).
Respostas Possíveis:
- 201 Created: Solicitação de estorno processada com sucesso.
- 400 Bad Request: A transação não pode ser estornada (ex: já estornada).
- 403 Forbidden: Permissão negada.

Estornar Transação por ID de Conciliação

Rota: POST /v1/customer/transactions/:conciliationId/refund
Descrição: Inicia o processo de devolução de uma transação (PIX, TED, etc.) utilizando o ID de Conciliação.
Parâmetros de URL:
- conciliationId (string, obrigatório): O ID de Conciliação da transação a ser estornada.
Lógica de Negócio: Requer permissão específica para estorno (TransactionPermissionGuard).
Respostas Possíveis:
- 201 Created: Solicitação de estorno processada com sucesso.
- 400 Bad Request: A transação não pode ser estornada.
- 403 Forbidden: Permissão negada.
- 404 Not Found: Transação não encontrada.

Decodificar QR Code PIX

Rota: POST /v1/customer/qrcode/decode
Descrição: Valida e extrai as informações de um payload EMV de um QR Code PIX, sem iniciar um pagamento.
Corpo da Requisição:

{
  "emv": "payload_emv_do_qrcode"
}

Respostas Possíveis:
- 200 OK: Retorna os dados decodificados do QR Code.
- 400 Bad Request: Payload EMV inválido.

Chaves PIX

Criar Chave PIX

Rota: POST /v1/customer/transactions/pix-keys
Descrição: Registra uma nova chave PIX para a conta do cliente (CPF, CNPJ, E-mail, Celular ou Aleatória/EVP).
Corpo da Requisição:
- Para chave aleatória: { “type”: “EVP” }
- Para outras chaves: { “type”: “CPF”, “key”: “11122233344” }
Respostas Possíveis:
- 201 Created: Chave criada com sucesso.
- 400 Bad Request: Chave PIX inválida ou já existente.

Listar Chaves PIX

Rota: GET /v1/customer/transactions/pix-keys
Descrição: Lista todas as chaves PIX cadastradas para a conta do cliente.
Respostas Possíveis:
- 200 OK: Retorna um array com as chaves PIX.

Deletar Chave PIX

Rota: DELETE /v1/customer/transactions/pix-keys
Descrição: Remove uma chave PIX da conta do cliente.
Corpo da Requisição:

{
  "type": "EMAIL",
  "key": "usuario@exemplo.com"
}

Respostas Possíveis:
- 200 OK: Chave PIX deletada com sucesso.
- 404 Not Found: Chave PIX não encontrada.

Consultar Informações de Chave PIX

Rota: POST /v1/customer/transactions/pix-key-info
Descrição: Retorna os dados do titular associado a uma chave PIX, sem iniciar uma transação.
Corpo da Requisição:

{
  "type": "CPF",
  "key": "11122233344"
}

Respostas Possíveis:
- 200 OK: Retorna os dados do titular da chave.
- 404 Not Found: Chave PIX não encontrada.

Solicitar Portabilidade/Reivindicação de Chave

Rota: POST /v1/customer/transactions/pix-keys/claim
Descrição: Inicia um processo de portabilidade ou reivindicação de posse de uma chave PIX.
Corpo da Requisição:

{
  "claimType": "PORTABILITY", // ou "OWNERSHIP"
  "keyType": "PHONE",
  "key": "+5511987654321"
}

Respostas Possíveis:
- 201 Created: Solicitação criada com sucesso.

Listar Solicitações de Portabilidade/Reivindicação

Rota: GET /v1/customer/transactions/pix-keys/claim
Descrição: Lista as solicitações de portabilidade/reivindicação de chaves PIX.
Parâmetros de Query:
- status (enum, opcional): Filtra as solicitações por status (OPEN, CONFIRMED, etc.).
Respostas Possíveis:
- 200 OK: Retorna a lista de solicitações.

Resolver Solicitação de Portabilidade/Reivindicação

Rota: POST /v1/customer/transactions/pix-keys/claim/resolve
Descrição: Aceita ou recusa uma solicitação de portabilidade/reivindicação pendente.
Corpo da Requisição:

{
  "claimId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "resolution": "ACCEPTED" // ou "REJECTED"
}

Respostas Possíveis:
- 200 OK: Solicitação resolvida com sucesso.
- 400 Bad Request: Dados inválidos.
- 404 Not Found: Solicitação não encontrada.

Gerenciamento da Conta

Consultar Status da Proposta de Onboarding

Rota: GET /v1/customer/account/proposal
Descrição: Consulta o status atual do processo de abertura e aprovação da conta do cliente.
Respostas Possíveis:
- 200 OK: Retorna o status da proposta.
- 404 Not Found: Proposta não encontrada.

Iniciar Recuperação de Senha Transacional

Rota: GET /v1/customer/transaction-password/forgot
Descrição: Envia um código de verificação (OTP) para o e-mail do usuário para redefinição da senha transacional.
Lógica de Negócio: Gera um OTP, armazena no Redis com tempo de expiração e envia um e-mail para o usuário.
Respostas Possíveis:
- 200 OK: Fluxo de recuperação iniciado.

Alterar Senha Transacional

Rota: POST /v1/customer/transaction-password/change
Descrição: Define uma nova senha transacional utilizando o código OTP recebido.
Lógica de Negócio: Valida o OTP do Redis. Se válido, atualiza a senha (hash) do cliente no banco de dados.
Corpo da Requisição:

{
  "otp": "123456",
  "newTransactionPassword": "nova_senha_forte_123"
}

Respostas Possíveis:
- 200 OK: Senha alterada com sucesso.
- 400 Bad Request: Token inválido ou senha fraca.
- 401 Unauthorized: OTP inválido.

Verificar Existência de Senha Transacional

Rota: GET /v1/customer/transactions/pin-exists
Descrição: Retorna um booleano indicando se uma senha transacional (PIN) já foi cadastrada para a conta.
Respostas Possíveis:
- 200 OK: Retorna { “exist”: true } ou { “exist”: false }.

Enviar OTP para Atualização de Dados

Rota: GET /v1/customer/accounts/update/send-otp
Descrição: Envia um código OTP para o e-mail do usuário, necessário para confirmar a alteração de dados cadastrais.
Respostas Possíveis:
- 204 No Content: OTP enviado com sucesso.

Atualizar Dados Cadastrais

Rota: PATCH /v1/customer/accounts/update
Descrição: Altera informações como e-mail, telefone ou endereço do cliente, validando com o código OTP.
Corpo da Requisição (Exemplo PF):

{
  "type": "F",
  "otp": "123456",
  "phoneNumber": "11998765432"
}

Respostas Possíveis:
- 200 OK: Dados atualizados com sucesso.
- 400 Bad Request: OTP inválido ou dados incorretos.

Consultar Dados da Conta

Rota: GET /v1/customer/account-data
Descrição: Retorna informações detalhadas sobre a conta do cliente, incluindo o status do onboarding.
Respostas Possíveis:
- 200 OK: Retorna os dados da conta.
- 404 Not Found: Cliente ou conta não encontrada.

Notificações

Listar Notificações

Rota: GET /v1/customer/notifications/
Descrição: Retorna uma lista paginada de notificações do cliente.
Parâmetros de Query:
- page, limit (number, opcional): Para paginação.
- read (boolean, opcional): Filtra por notificações lidas (true) ou não lidas (false).
Respostas Possíveis:
- 200 OK: Retorna a lista de notificações.

Marcar Notificação como Lida

Rota: POST /v1/customer/notifications/
Descrição: Atualiza o status de uma notificação específica para “lida”.
Corpo da Requisição:

{
  "id": 123
}

Respostas Possíveis:
- 204 No Content: Notificação marcada como lida com sucesso.
- 404 Not Found: Notificação não encontrada.

Solicitações de Transação (Fluxo de Aprovação)

Estas rotas são usadas para gerenciar transações que requerem um fluxo de aprovação (criadas por usuários Consultor e aprovadas por Aprovador).

Listar Solicitações de Transação

Rota: GET /v1/customer/transaction-requests
Descrição: Lista as solicitações de transações (PIX, TED, etc.) que aguardam aprovação.
Parâmetros de Query:
- limit, offset (number, opcional): Para paginação.
- status (enum, opcional): Filtra por status (PENDING, APPROVED, REJECTED).
- type (enum, opcional): Filtra por tipo de transação (PIX, TED, BILLET).
Respostas Possíveis:
- 200 OK: Retorna a lista de solicitações.

Aprovar Solicitação de Transação

Rota: POST /v1/customer/transaction-approve
Descrição: Permite que um usuário Aprovador aprove uma solicitação pendente, efetivando a transação.
Lógica de Negócio: Requer senha transacional do aprovador e que o usuário tenha o perfil Aprovador.
Corpo da Requisição:

{
  "transactionRequestId": "uuid-da-solicitacao",
  "transactionPassword": "senha_transacional_do_aprovador"
}

Respostas Possíveis:
- 200 OK: Transação aprovada e processada com sucesso.
- 400 Bad Request: Solicitação não encontrada ou já processada.
- 403 Forbidden: Permissão negada (não é aprovador, senha incorreta, etc.).

Reprovar Solicitação de Transação

Rota: POST /v1/customer/transaction-repprove
Descrição: Permite que um usuário Aprovador reprove uma solicitação pendente.
Lógica de Negócio: Requer senha transacional do aprovador e que o usuário tenha o perfil Aprovador.
Corpo da Requisição:

{
  "transactionRequestId": "uuid-da-solicitacao",
  "reason": "Motivo da reprovação",
  "transactionPassword": "senha_transacional_do_aprovador"
}

Respostas Possíveis:
- 200 OK: Solicitação reprovada com sucesso.
- 400 Bad Request: Solicitação não encontrada ou já processada.
- 403 Forbidden: Permissão negada.

Rotas de Favoritos (v1)

A seguir estão detalhadas as rotas da API disponíveis no FavoritesController, responsável pelo gerenciamento de contatos favoritos para transferências (PIX e TED).

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Favoritos

Listar Favoritos por Tipo

Rota: GET /v1/favorites/:type
Descrição: Retorna uma lista paginada de favoritos com base no tipo especificado (PIX ou TED).
Parâmetros de URL:
- type (string, obrigatório): O tipo de favorito a ser listado. Valores possíveis: PIX, TED.
Parâmetros de Query:
- page (number, opcional): Número da página para a paginação. Padrão: 1.
- limit (number, opcional): Quantidade de itens por página. Padrão: 10.
Respostas Possíveis:
- 200 OK: Retorna um objeto de paginação com a lista de favoritos.
- 400 Bad Request: O parâmetro type é inválido ou está ausente.

Obter um Favorito por ID e Tipo

Rota: GET /v1/favorites/:type/:id
Descrição: Busca e retorna os detalhes de um favorito específico.
Parâmetros de URL:
- type (string, obrigatório): O tipo do favorito (PIX ou TED).
- id (number, obrigatório): O ID do favorito a ser buscado.
Respostas Possíveis:
- 200 OK: Retorna o objeto do favorito encontrado.
- 401 Unauthorized: O favorito não pertence ao usuário autenticado.
- 404 Not Found: Favorito não encontrado.

Criar Novo Favorito

Rota: POST /v1/favorites
Descrição: Cria um novo favorito para transferências PIX ou TED. A estrutura do corpo da requisição varia conforme o type.
Corpo da Requisição (Exemplo TED):

{
  "type": "TED",
  "name": "João da Silva",
  "alias": "Aluguel",
  "bankIspb": "60701190",
  "agency": "0001",
  "accountNumber": "123456789"
}

Corpo da Requisição (Exemplo PIX):

{
  "type": "PIX",
  "name": "Maria Oliveira",
  "alias": "Conta de Investimentos",
  "pixType": "CPF",
  "pixKey": "12345678900"
}

Respostas Possíveis:
- 201 Created: Favorito criado com sucesso.
- 400 Bad Request: Dados inválidos, ou já existe um favorito com as mesmas informações (ex: mesma chave PIX ou mesma conta TED para o usuário).

Atualizar Favorito

Rota: PUT /v1/favorites/:type/:id
Descrição: Atualiza os dados de um favorito existente. Atualmente, a atualização é suportada apenas para favoritos do tipo TED.
Parâmetros de URL:
- type (string, obrigatório): O tipo do favorito. Deve ser TED.
- id (number, obrigatório): O ID do favorito a ser atualizado.
Corpo da Requisição:

{
  "name": "Nome Atualizado",
  "alias": "Apelido Atualizado",
  "bankIspb": "00000000",
  "agency": "0002",
  "accountNumber": "987654321"
}

Respostas Possíveis:
- 200 OK: Favorito atualizado com sucesso.
- 400 Bad Request: Tipo inválido (diferente de TED) ou dados da requisição incorretos.
- 401 Unauthorized: O favorito não pertence ao usuário autenticado.
- 404 Not Found: Favorito não encontrado.

Deletar Favorito

Rota: DELETE /v1/favorites/:type/:id
Descrição: Remove um favorito do sistema.
Parâmetros de URL:
- type (string, obrigatório): O tipo do favorito (PIX ou TED).
- id (number, obrigatório): O ID do favorito a ser deletado.
Respostas Possíveis:
- 200 OK: Favorito deletado com sucesso.
- 401 Unauthorized: O favorito não pertence ao usuário autenticado.
- 404 Not Found: Favorito não encontrado.

Rotas de Taxas (Fee v1)

A seguir estão detalhadas as rotas da API disponíveis no FeeController, responsável por fornecer informações sobre taxas e histórico de pagamentos para o cliente.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Consulta de Taxas e Histórico

Obter Informações de Taxas do Cliente

Rota: GET /v1/fee/
Descrição: Retorna as taxas aplicáveis ao cliente autenticado, incluindo os preços, a quantidade de transações gratuitas por mês e a quantidade já utilizada no mês corrente.
Respostas Possíveis:
- 200 OK: Informações de taxas retornadas com sucesso.

{
  "prices": {
    "DEBIT": { "PIX": 1.5, "TED": 2.5 },
    "CREDIT": { "PIX": 1.0, "TED": 2.0 }
  },
  "monthlyFreeUse": {
    "DEBIT": { "PIX": 10, "TED": 5 },
    "CREDIT": { "PIX": 5, "TED": 2 }
  },
  "usedThisMonth": {
    "DEBIT": { "PIX": 3, "TED": 1 },
    "CREDIT": { "PIX": 2, "TED": 0 }
  }
}

401 Unauthorized: Token de acesso inválido ou ausente.
500 Internal Server Error: Erro interno no servidor.

Obter Histórico de Pagamentos de Taxas

Rota: GET /v1/fee/payment-history
Descrição: Retorna o histórico de pagamentos de taxas do cliente autenticado.
Respostas Possíveis:
- 200 OK: Histórico de pagamentos retornado com sucesso.

[
  {
    "amount": 100.0,
    "feeAmount": 1.5,
    "transactionType": "PIX",
    "operation": "DEBIT",
    "date": "2024-06-01T12:00:00.000Z"
  },
  {
    "amount": 200.0,
    "feeAmount": 2.5,
    "transactionType": "TED",
    "operation": "CREDIT",
    "date": "2024-06-02T15:30:00.000Z"
  }
]

401 Unauthorized: Token de acesso inválido ou ausente.
500 Internal Server Error: Erro interno no servidor.

Documentação da Rota de Webhooks (v1)

A seguir estão detalhadas a rota da API disponível no IncomingWebhooksController, que atua como um ponto de entrada genérico para receber e processar eventos de webhook de diferentes instituições financeiras (provedores).

Autenticação: Esta rota é pública, mas espera-se que seja chamada apenas pelos serviços de webhook dos provedores configurados (ex: Celcoin). A validação da origem, se necessária, deve ser implementada no manipulador (handler) específico de cada provedor.

Recebimento de Eventos de Webhook

Manipulador Genérico de Eventos

Rota: POST /v1/incoming-webhooks/:bank/events/:event
Descrição: Endpoint centralizado para receber notificações (webhooks) de diferentes provedores. A lógica de processamento é delegada a um manipulador específico com base no provedor (bank).
Lógica de Negócio:
- O parâmetro bank na URL é usado para identificar a instituição financeira de origem (ex: “celcoin”).
- Um serviço de fábrica (IncomingWebhookService) seleciona o manipulador (handler) apropriado para o banco especificado.
- O manipulador selecionado é então responsável por processar o event e o corpo da requisição (payload) de acordo com as regras de negócio daquele provedor.
Parâmetros de URL:
- bank (string, obrigatório): O identificador da instituição financeira (ex: “celcoin”).
- event (string, obrigatório): O tipo de evento específico enviado pela instituição (ex: “pix-payment-in”, “onboarding-create”).
Corpo da Requisição:
- O payload JSON enviado pelo provedor do webhook. A estrutura varia completamente dependendo do bank e do event.

{
  "transactionId": "12345",
  "amount": 100.0,
  "status": "CONFIRMED",
  "body": {
    // ... dados específicos do evento
  }
}

Respostas Possíveis:
- 200 OK: O webhook foi recebido e reconhecido com sucesso. A resposta é padronizada para confirmar o recebimento e evitar que o provedor tente reenviar o evento.

{
  "received": true
}

500 Internal Server Error: Ocorre se um manipulador (handler) para o bank especificado não for encontrado ou se houver um erro inesperado no processamento.

Rotas de Autenticação do Mobile (v1/v2)

A seguir estão detalhadas as rotas da API disponíveis no AuthController, responsável pelo fluxo de autenticação, recuperação de senha e gerenciamento de sessão para clientes no aplicativo móvel.

Enviar OTP para Cadastro/Login

Rota: POST /mobile/auth/send-otp
Descrição: Envia um código de verificação (OTP) para o e-mail do usuário, utilizado para registrar um novo dispositivo ou para recuperar a senha.
Corpo da Requisição:

{
  "email": "usuario@exemplo.com"
}

Respostas Possíveis:
- 200 OK: OTP enviado com sucesso.

Rota: POST /mobile/auth/register-device
Descrição: Realiza o primeiro login do usuário, validando o OTP e registrando o dispositivo.
Lógica de Negócio:
- Valida o OTP, a senha e os dados do dispositivo.
- Se válido, cria a sessão do usuário, gerando um accessToken e um refreshToken.
- O refreshToken é enviado como um cookie httpOnly e também no corpo da resposta para compatibilidade.
Corpo da Requisição:

{
  "otp": "123456",
  "password": "senha_do_usuario",
  "email": "usuario@exemplo.com",
  "device": {
    "id": "uuid-do-dispositivo",
    "name": "iPhone de João"
  }
}

Respostas Possíveis:
- 200 OK: Dispositivo registrado e login realizado. Retorna accessToken, refreshToken e dados do usuário.
- 400 Bad Request: Dados inválidos.
- 401 Unauthorized: Credenciais (OTP, senha) incorretas.

Rota: POST /mobile/auth/signin
Descrição: Autentica um usuário em um dispositivo já registrado.
Lógica de Negócio:
- Valida o e-mail, senha e ID do dispositivo.
- Gera um novo par de accessToken e refreshToken.
- Define o refreshToken em um cookie httpOnly.
Corpo da Requisição:

{
  "email": "usuario@exemplo.com",
  "password": "senha_do_usuario",
  "deviceId": "uuid-do-dispositivo"
}

Respostas Possíveis:
- 200 OK: Login bem-sucedido. Retorna accessToken, refreshToken e dados do usuário.
- 401 Unauthorized: Credenciais incorretas.
- 403 Forbidden: Conta bloqueada.
- 404 Not Found: Usuário não encontrado.

Rota: POST /mobile/auth/v2/signin
Descrição: Versão do login que suporta usuários associados a múltiplas contas. Se mais de uma conta for encontrada, retorna um token temporário para seleção de conta.
Lógica de Negócio:
- Se o usuário tem apenas uma conta, o comportamento é idêntico ao signin v1.
- Se o usuário tem múltiplas contas, retorna uma resposta indicando a necessidade de seleção, junto com um selectAccountToken.
Respostas Possíveis:
- 200 OK: Login bem-sucedido (cenário de conta única) ou token para seleção de conta retornado.
- 401 Unauthorized: Credenciais incorretas.

Selecionar Conta (v2)

Rota: POST /mobile/auth/v2/select-account
Descrição: Após o login v2, o cliente usa esta rota para selecionar com qual conta deseja prosseguir.
Autenticação: Requer o selectAccountToken (retornado pelo /v2/signin) no cabeçalho Authorization.
Corpo da Requisição:

{
  "id": 1, // ID da conta do cliente a ser selecionada
  "userId": 10 // ID do usuário
}

Respostas Possíveis:
- 200 OK: Conta selecionada. Retorna accessToken, refreshToken e dados do usuário.
- 401 Unauthorized: selectAccountToken inválido ou o usuário não tem permissão para acessar a conta selecionada.

Gerenciamento de Sessão e Senha

Atualizar Token de Acesso (Refresh Token via Body)

Rota: POST /mobile/auth/body-refresh-token
Descrição: Gera um novo accessToken e refreshToken a partir de um refreshToken válido enviado no corpo da requisição.
Autenticação: Requer um accessToken (pode estar expirado) para identificar o usuário.
Corpo da Requisição:

{
  "refreshToken": "refresh_token_valido_do_usuario"
}

Respostas Possíveis:
- 200 OK: Retorna um novo accessToken e um novo refreshToken.
- 401 Unauthorized: refreshToken inválido ou não correspondente ao usuário.

Solicitar Recuperação de Senha

Rota: POST /mobile/auth/password/forgot
Descrição: Inicia o fluxo de recuperação de senha, enviando um OTP para o e-mail do usuário.
Corpo da Requisição:

{
  "email": "usuario@exemplo.com"
}

Respostas Possíveis:
- 200 OK: Solicitação processada.
- 404 Not Found: Usuário não encontrado.

Alterar Senha

Rota: POST /mobile/auth/password/change
Descrição: Define uma nova senha para o usuário, validando com o OTP recebido por e-mail.
Corpo da Requisição:

{
  "otp": "123456",
  "newPassword": "nova_senha_forte_123",
  "email": "usuario@exemplo.com"
}

Respostas Possíveis:
- 200 OK: Senha alterada com sucesso.
- 401 Unauthorized: OTP inválido.

Atualizar Informações do Usuário

Rota: POST /mobile/auth/signin-update-user
Descrição: Atualiza informações cadastrais do usuário, como nome, e-mail e telefone.
Corpo da Requisição:

{
  "name": "Nome Completo Atualizado",
  "email": "novo.email@exemplo.com",
  "phoneNumber": "11987654321"
}

Respostas Possíveis:
- 200 OK: Dados do usuário atualizados com sucesso.

Editar Acesso Múltiplo

Rota: PUT /mobile/auth/edit-multiple
Descrição: Ativa ou desativa a permissão para que o usuário possa estar logado em múltiplos dispositivos simultaneamente.
Autenticação: Requer um accessToken válido.
Corpo da Requisição:

{
  "active": true // ou false
}

Respostas Possíveis:
- 200 OK: Configuração de acesso múltiplo atualizada com sucesso.

Rotas de Pagamentos (v1)

A seguir estão detalhadas as rotas da API disponíveis no PaymentController, responsável por consultar transações e gerenciar o fluxo de aprovação de pagamentos para contas corporativas.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Consulta de Transações

Listar Transações do Cliente

Rota: GET /v1/payments/transactions
Descrição: Retorna uma lista formatada de transações para o cliente autenticado, com base nos filtros fornecidos.
Parâmetros de Query:
- startDate, endDate (string, opcional): Filtra as transações por um período.
- transactionType (string, opcional): Filtra por um tipo de transação específico (ex: PIX, TED).
- limit, offset (number, opcional): Para paginação.
Respostas Possíveis:
- 200 OK: Retorna a lista de transações formatada.
- 401 Unauthorized: Token de acesso inválido ou ausente.

Transferências (Cash-out)

Realizar Transferência Direta (PIX/TED)

Rota: POST /v1/payments/transactions/cashout/direct
Descrição: Efetua uma transferência (PIX ou TED) a partir da conta do cliente.
Lógica de Negócio:
- Esta rota implementa um fluxo de aprovação para contas corporativas.
- Se o usuário logado for um Consultor (UserRoleConsultantCashoutGuard): A operação não é executada imediatamente. Em vez disso, é criada uma solicitação de transação que fica pendente de aprovação.
- Se o usuário logado tiver permissão para transacionar (ex: Administrador ou Aprovador): A transferência é processada na hora, após validação da senha transacional (TransactionPasswordGuard) e dos limites da conta (TransactionsLimitsService).
Corpo da Requisição:

{
  "amount": 15050,
  "transactionPassword": "sua_senha_transacional", // Obrigatória para execução direta
  "recipient": {
    "name": "Maria da Silva",
    "document": "11122233344",
    "account": {
      "bank": "001",
      "branch": "1234",
      "accountNumber": "567890",
      "accountType": "CACC"
    }
  }
}

Respostas Possíveis:
- 200 OK ou 201 Created: Transação executada ou solicitação criada com sucesso.
- 403 Forbidden: Senha transacional incorreta, permissões insuficientes ou limite excedido.

Gerenciamento de Solicitações de Transação (Fluxo de Aprovação)

Estas rotas são usadas para gerenciar transações que requerem um fluxo de aprovação, criadas por usuários Consultor e aprovadas/reprovadas por usuários Aprovador.

Listar Solicitações de Transação

Rota: GET /v1/payments/transaction-requests
Descrição: Lista as solicitações de transações (PIX, TED, etc.) que aguardam aprovação na conta corporativa.
Parâmetros de Query:
- limit, offset (number, opcional): Para paginação.
- status (enum, opcional): Filtra por status (PENDING, APPROVED, REJECTED).
- type (enum, opcional): Filtra por tipo de transação (PIX, TED, BILLET).
Respostas Possíveis:
- 200 OK: Retorna a lista paginada de solicitações.

Aprovar Solicitação de Transação

Rota: POST /v1/payments/transaction-approve
Descrição: Permite que um usuário com perfil Aprovador aprove uma solicitação pendente, efetivando a transação.
Lógica de Negócio:
- Protegida pelo UserRoleApproverCashoutGuard, garantindo que apenas aprovadores possam usá-la.
- Requer a senha transacional do aprovador (TransactionPasswordGuard) para confirmar a operação.
Corpo da Requisição:

{
  "transactionRequestId": "uuid-da-solicitacao",
  "transactionPassword": "senha_transacional_do_aprovador"
}

Respostas Possíveis:
- 200 OK ou 201 Created: Transação aprovada e processada com sucesso.
- 400 Bad Request: Solicitação não encontrada ou já processada.
- 403 Forbidden: Permissão negada (não é aprovador, senha incorreta, etc.).

Reprovar Solicitação de Transação

Rota: POST /v1/payments/transaction-repprove
Descrição: Permite que um usuário com perfil Aprovador reprove (rejeite) uma solicitação pendente.
Lógica de Negócio:
- Protegida pelo UserRoleApproverCashoutGuard.
- Requer a senha transacional do aprovador (TransactionPasswordGuard) para confirmar a operação.
Corpo da Requisição:

{
  "transactionRequestId": "uuid-da-solicitacao",
  "reason": "Motivo da reprovação",
  "transactionPassword": "senha_transacional_do_aprovador"
}

Respostas Possíveis:
- 200 OK ou 201 Created: Solicitação reprovada com sucesso.
- 400 Bad Request: Solicitação não encontrada ou já processada.
- 403 Forbidden: Permissão negada.

Rotas de PIX (v1)

A seguir estão detalhadas as rotas da API disponíveis no PixController, responsável por gerenciar as operações de PIX, incluindo saldo, QR Codes, transferências (cash-out) e gerenciamento de chaves.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Saldo

Obter Saldo

Rota: GET /v1/pix/balance
Descrição: Busca e retorna o saldo atual da conta de pagamento do cliente.
Respostas Possíveis:
- 200 OK: Retorna o objeto de saldo com sucesso.
- 404 Not Found: Conta do cliente não encontrada.

QR Code (Cash-in)

Gerar QR Code PIX

Rota: POST /v1/pix/transactions
Descrição: Gera um QR Code para receber um pagamento PIX.
Corpo da Requisição:

{
  "paymentMethod": "pix",
  "amount": 1000, // em centavos
  "pix": {
    "expiresAt": "2023-12-31 23:59:59",
    "description": "Descrição do pagamento",
    "conciliationId": "id-unico-da-cobranca"
  },
  "postbackUrl": "https://seu-webhook.com/notificacao",
  "ip": "192.168.1.1"
}

Respostas Possíveis:
- 201 Created: Retorna os dados do QR Code (qrCode, encodedValue).
- 400 Bad Request: Dados inválidos no payload.

Decodificar QR Code PIX

Rota: POST /v1/pix/qrcode/decode
Descrição: Valida e extrai as informações de um payload EMV de um QR Code PIX, sem iniciar um pagamento.
Corpo da Requisição:

{
  "emv": "payload_emv_do_qrcode"
}

Respostas Possíveis:
- 200 OK: Retorna os dados decodificados do QR Code.
- 400 Bad Request: Payload EMV inválido.

Transferências PIX (Cash-out)

Realizar PIX (Cash-out)

Rota: POST /v1/pix/transactions/cashout
Descrição: Efetua uma transferência PIX para uma chave específica ou a partir de um QR Code (EMV).
Lógica de Negócio:
- Se o usuário logado for um Consultor (UserRoleConsultantCashoutGuard): A operação cria uma solicitação de transação que fica pendente de aprovação, em vez de executar a transferência imediatamente.
- Se o usuário logado tiver permissão para transacionar (ex: Administrador ou Aprovador): A transferência é processada na hora, após validação da senha transacional (TransactionPasswordGuard) e dos limites da conta.
Corpo da Requisição:

{
  "amount": 1500, // em centavos
  "transactionPassword": "sua_senha_transacional",
  "pixKey": {
    "type": "CPF",
    "key": "11122233344"
  },
  "description": "Pagamento de serviço"
}

Respostas Possíveis:
- 201 Created: Transação ou solicitação criada com sucesso.
- 400 Bad Request: Dados inválidos, conciliationId já em uso, ou tentativa de transferência para a própria conta.
- 403 Forbidden: Senha transacional incorreta ou permissões insuficientes.

Consultar Transação por ID de Conciliação

Rota: GET /v1/pix/transactions/:conciliationId/conciliation
Descrição: Retorna os detalhes de uma transação PIX específica com base no seu ID de conciliação.
Parâmetros de URL:
- conciliationId (string, obrigatório): O ID de conciliação da transação a ser estornada.
Respostas Possíveis:
- 200 OK: Retorna o objeto da transação.
- 404 Not Found: Transação não encontrada.

Estornar Transação PIX

Rota: POST /v1/pix/transactions/:conciliationId/refund
Descrição: Inicia o processo de devolução de uma transação PIX utilizando o ID de Conciliação.
Lógica de Negócio: Requer permissão específica para estorno (TransactionPermissionGuard).
Parâmetros de URL:
- conciliationId (string, obrigatório): O ID de Conciliação da transação a ser estornada.
Respostas Possíveis:
- 200 OK: Solicitação de estorno processada com sucesso.
- 403 Forbidden: Permissão negada.
- 404 Not Found: Transação não encontrada.

Chaves PIX

Criar Chave PIX

Rota: POST /v1/pix/transactions/pix-keys
Descrição: Registra uma nova chave PIX para a conta do cliente (CPF, CNPJ, E-mail, Celular ou Aleatória/EVP).
Corpo da Requisição:
- Para chave aleatória: { “type”: “EVP” }
- Para outras chaves: { “type”: “CPF”, “key”: “11122233344” }
Respostas Possíveis:
- 201 Created: Chave criada com sucesso.
- 400 Bad Request: Chave PIX inválida ou já existente.

Listar Chaves PIX

Rota: GET /v1/pix/transactions/pix-keys
Descrição: Lista todas as chaves PIX cadastradas para a conta do cliente.
Respostas Possíveis:
- 200 OK: Retorna um array com as chaves PIX.

Deletar Chave PIX

Rota: DELETE /v1/pix/transactions/pix-keys
Descrição: Remove uma chave PIX da conta do cliente.
Corpo da Requisição:

{
  "type": "EMAIL",
  "key": "usuario@exemplo.com"
}

Respostas Possíveis:
- 200 OK: Chave PIX deletada com sucesso.
- 404 Not Found: Chave PIX não encontrada.

Consultar Informações de Chave PIX

Rota: POST /v1/pix/transactions/pix-key-info
Descrição: Retorna os dados do titular associado a uma chave PIX, sem iniciar uma transação.
Corpo da Requisição:

{
  "type": "CPF",
  "key": "11122233344"
}

Respostas Possíveis:
- 200 OK: Retorna os dados do titular da chave.
- 404 Not Found: Chave PIX não encontrada.

Portabilidade/Reivindicação de Chaves

Solicitar Portabilidade/Reivindicação

Rota: POST /v1/pix/transactions/pix-keys/claim
Descrição: Inicia um processo de portabilidade ou reivindicação de posse de uma chave PIX.
Corpo da Requisição:

{
  "claimType": "PORTABILITY", // ou "OWNERSHIP"
  "keyType": "PHONE",
  "key": "+5511987654321"
}

Respostas Possíveis:
- 200 OK: Solicitação criada com sucesso.

Listar Solicitações de Portabilidade/Reivindicação

Rota: GET /v1/pix/transactions/pix-keys/claim
Descrição: Lista as solicitações de portabilidade/reivindicação de chaves PIX.
Parâmetros de Query:
- status (enum, opcional): Filtra as solicitações por status (OPEN, CONFIRMED, etc.).
Respostas Possíveis:
- 200 OK: Retorna a lista de solicitações.

Resolver Solicitação de Portabilidade/Reivindicação

Rota: POST /v1/pix/transactions/pix-keys/claim/resolve
Descrição: Aceita ou recusa uma solicitação de portabilidade/reivindicação pendente.
Corpo da Requisição:

{
  "claimId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "resolution": "ACCEPTED" // ou "REJECTED"
}

Respostas Possíveis:
- 200 OK: Solicitação resolvida com sucesso.
- 400 Bad Request: Dados inválidos.
- 404 Not Found: Solicitação não encontrada.

Rotas Públicas (v1)

A seguir estão detalhadas as rotas da API disponíveis no PublicController, que são acessíveis publicamente (ou com autenticação via x-token) e são usadas principalmente para o fluxo de onboarding, verificação de dados e ativação de usuários.

Verificação de Dados

Verificar Existência de E-mail

Rota: GET /v1/public/check-existing-email
Descrição: Checa se um endereço de e-mail já está cadastrado no sistema.
Autenticação: Pública.
Parâmetros de Query:
- email (string, obrigatório): O e-mail a ser verificado.
Respostas Possíveis:
- 200 OK: Retorna true se o e-mail existir, caso contrário false.

Verificar Existência de Proposta

Rota: GET /v1/public/check-existing-proposal
Descrição: Checa se já existe uma proposta de abertura de conta para um determinado documento (CPF/CNPJ).
Autenticação: Pública.
Parâmetros de Query:
- document (string, obrigatório): O documento a ser verificado.
Respostas Possíveis:
- 200 OK: Retorna true se a proposta existir, caso contrário false.

Verificar Status da Proposta

Rota: GET /v1/public/check-existing-proposal-status
Descrição: Retorna o status atual de uma proposta de abertura de conta.
Autenticação: Pública.
Parâmetros de Query:
- document (string, obrigatório): O documento da proposta a ser consultada.
Respostas Possíveis:
- 200 OK: Retorna um objeto com a existência e o status da proposta (ex: { “exists”: true, “status”: “PENDING” }).

Onboarding e Ativação de Conta

Enviar OTP para Onboarding

Rota: POST /v1/public/onboarding-send-otp
Descrição: Gera e envia um código de uso único (OTP) para o e-mail informado para verificação durante o onboarding.
Autenticação: Pública.
Corpo da Requisição:

{
  "email": "novo.usuario@example.com",
  "name": "Novo Usuário"
}

Respostas Possíveis:
- 201 Created: OTP enviado com sucesso.
- 400 Bad Request: Payload inválido ou erro no envio.

Confirmar e Ativar Novo Usuário (Auto-Onboarding)

Rota: POST /v1/public/confirm-user
Descrição: Finaliza o processo de auto-onboarding, validando o token de confirmação, ativando o usuário e criando o cliente associado a ele.
Autenticação: Pública (a segurança é garantida pelo token JWT no corpo da requisição).
Corpo da Requisição:

{
  "token": "jwt-token-de-confirmacao-aqui",
  "newPassword": "Password@123",
  "name": "Maria da Silva",
  "birthDate": "1995-05-15",
  "addressLine1": "Rua das Flores, 456",
  "addressLine2": "Apto 101",
  "neighborhood": "Centro",
  "city": "Cidade Exemplo",
  "state": "EX",
  "postalCode": "12345-000",
  "motherName": "Ana da Silva",
  "isPoliticallyExposedPerson": false,
  "transactionPassword": "1234"
}

Respostas Possíveis:
- 201 Created: Usuário confirmado e ativado com sucesso.
- 400 Bad Request: Token inválido ou expirado.

Ativar Novo Usuário Convidado

Rota: POST /v1/public/activate-user
Descrição: Ativa um usuário que foi convidado por um cliente corporativo existente. Requer o preenchimento de dados pessoais e a criação de uma senha.
Autenticação: Pública (a segurança é garantida pelo token JWT no corpo da requisição).
Corpo da Requisição:

{
  "token": "jwt-token-de-convite-aqui",
  "newPassword": "Password@123",
  "name": "John Doe",
  "birthDate": "1990-01-15",
  "addressLine1": "Main Street, 123",
  "neighborhood": "Downtown",
  "city": "Anytown",
  "state": "SP",
  "postalCode": "12345-678",
  "motherName": "Jane Doe"
}

Respostas Possíveis:
- 201 Created: Usuário ativado com sucesso.
- 400 Bad Request: Token inválido ou expirado.

Ativar Usuário Convidado Existente

Rota: POST /v1/public/activate-existing-user
Descrição: Ativa um usuário que foi convidado, mas cujos dados já foram pré-cadastrados. Apenas confirma a ativação via token, sem necessidade de enviar dados pessoais novamente.
Autenticação: Pública (a segurança é garantida pelo token JWT no corpo da requisição).
Corpo da Requisição:

{
  "token": "jwt-token-de-convite-aqui"
}

Respostas Possíveis:
- 201 Created: Usuário ativado com sucesso.
- 400 Bad Request: Token inválido ou expirado.

Informações do Sistema (Requer x-token)

Obter Informações do Sistema

Rota: GET /v1/public/system-info
Descrição: Retorna configurações e informações do sistema, como dados do whitelabel (cores, logos, etc.).
Autenticação: Requer um x-token válido no cabeçalho da requisição.
Respostas Possíveis:
- 200 OK: Informações do sistema retornadas com sucesso.
- 401 Unauthorized: x-token inválido ou ausente.

Verificar Permissão de Documento (Whitelist)

Rota: GET /v1/public/check-dock
Descrição: Verifica se um documento (CPF/CNPJ) está na lista de permissões (whitelist) para abrir uma conta.
Autenticação: Requer um x-token válido no cabeçalho da requisição.
Parâmetros de Query:
- document (string, obrigatório): O número do documento.
- type (string, obrigatório): O tipo do documento (ex: ‘CPF’, ‘CNPJ’).
Respostas Possíveis:
- 200 OK: Retorna false se o documento for permitido.
- 400 Bad Request: Documento não permitido.
- 401 Unauthorized: x-token inválido ou ausente.

Rotas de Planos de Assinatura (v1)

A seguir estão detalhadas as rotas da API disponíveis no SubscriptionPlanController, responsável pelo gerenciamento dos planos de assinatura dos clientes.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Planos

Listar Planos de Assinatura Disponíveis

Rota: GET /v1/subscription-plans/
Descrição: Retorna uma lista de todos os planos de assinatura publicados e disponíveis para o tipo de cliente (PF/PJ) autenticado.
Respostas Possíveis:
- 200 OK: Retorna um array com os planos de assinatura disponíveis.

[
  {
    "id": 1,
    "name": "Plano Básico",
    "description": "Acesso a funcionalidades básicas.",
    "pricePerMonth": 1990,
    "customerType": "F"
  }
]

401 Unauthorized: Token de acesso inválido ou ausente.

Obter Plano de Assinatura Atual

Rota: GET /v1/subscription-plans/current
Descrição: Retorna os detalhes do plano de assinatura atualmente ativo para o cliente autenticado.
Respostas Possíveis:
- 200 OK: Retorna o objeto do plano atual. Se o cliente não tiver um plano, retorna null ou um objeto vazio.

{
  "id": 1,
  "name": "Plano Básico",
  "description": "Acesso a funcionalidades básicas.",
  "pricePerMonth": 1990,
  "customerType": "F",
  "endDate": "2024-12-31T23:59:59.000Z",
  "autoRenew": true
}

401 Unauthorized: Token de acesso inválido ou ausente.

Ativar/Desativar Renovação Automática

Rota: PATCH /v1/subscription-plans/current/auto-renew
Descrição: Ativa ou desativa a renovação automática para o plano de assinatura atual do cliente.
Respostas Possíveis:
- 200 OK: Retorna o novo estado da renovação automática.

{
  "autoRenew": true
}

400 Bad Request: O cliente não possui um plano ativo para modificar.
401 Unauthorized: Token de acesso inválido ou ausente.

Comprar um Plano de Assinatura

Rota: POST /v1/subscription-plans/purchase
Descrição: Inicia o processo de compra (ou troca) de um plano de assinatura para o cliente.
Corpo da Requisição:

{
  "planId": 1
}

Respostas Possíveis:
- 201 Created: Compra realizada com sucesso. A resposta pode variar dependendo se o pagamento é imediato ou agendado.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: O plano com o planId especificado não foi encontrado.

Obter Histórico de Pagamentos

Rota: GET /v1/subscription-plans/payment-history
Descrição: Retorna o histórico de transações relacionadas aos pagamentos do plano de assinatura do cliente.
Respostas Possíveis:
- 200 OK: Retorna um array com o histórico de pagamentos.

[
  {
    "id": 101,
    "amount": 1990,
    "paymentDate": "2024-05-20T10:00:00.000Z",
    "description": "Pagamento Plano Básico",
    "status": 2
  }
]

401 Unauthorized: Token de acesso inválido ou ausente.

Obter Configurações de Assinatura

Rota: GET /v1/subscription-plans/settings
Descrição: Retorna as configurações gerais do sistema de assinaturas, como o modo de cobrança (débito/crédito) e o dia do pagamento.
Respostas Possíveis:
- 200 OK: Retorna o objeto de configurações.

// Exemplo modo débito
{
  "mode": "debit",
  "paymentDay": null
}

// Exemplo modo crédito
{
  "mode": "credit",
  "paymentDay": 15
}

401 Unauthorized: Token de acesso inválido ou ausente.

Rotas de TED (v1)

A seguir estão detalhadas as rotas da API disponíveis no TedController, responsável por gerenciar as operações de transferência via TED.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Transferências TED

Realizar Transferência TED

Rota: POST /v1/ted/transactions/transfer/ted
Descrição: Envia uma transferência via TED para uma conta em outra instituição. Esta rota possui um fluxo de aprovação para contas corporativas.
Lógica de Negócio:
- A operação está restrita a horários comerciais (Segunda a Sexta, das 6:30h às 17:00h), validação feita pelo pipe TedTimeConstraints.
- Se o usuário logado for um Consultor (UserRoleConsultantCashoutGuard): A operação não é executada imediatamente. Em vez disso, é criada uma solicitação de transação que fica pendente de aprovação.
- Se o usuário logado tiver permissão para transacionar (ex: Administrador ou Aprovador): A transferência é processada na hora, após validação da senha transacional (TransactionPasswordGuard) e dos limites da conta.
Corpo da Requisição:

{
  "amount": 750000,
  "transactionPassword": "sua_senha_transacional",
  "receiverAccount": {
    "holder": {
      "name": "Empresa Destino LTDA",
      "document": "11222333000144"
    },
    "account": {
      "bank": "033",
      "branch": "1111",
      "accountNumber": "222222",
      "accountType": "CACC"
    }
  },
  "clientFinality": "Pagamento de Fornecedor",
  "description": "Pagamento ref. NF 123"
}

Respostas Possíveis:
- 201 Created: TED enviada ou solicitação criada com sucesso.
- 400 Bad Request: Fora do horário permitido para TED ou dados inválidos.
- 403 Forbidden: Senha transacional incorreta, permissões insuficientes ou limite excedido.
- 500 Internal Server Error: Erro interno no servidor.

Rotas de Aceite de Termos (v1)

A seguir estão detalhadas as rotas da API disponíveis no TermsAcceptanceController, responsável por gerenciar as versões dos termos de uso e o aceite por parte dos usuários.

Rotas para Clientes

Autenticação: As rotas a seguir requerem um token de acesso de cliente válido (AccessTokenGuard) para obter a última versão dos termos e registrar o aceite.

Obter a Última Versão dos Termos

Rota: GET /v1/terms-acceptance/latest-version
Descrição: Retorna a versão mais recente dos termos de uso cadastrados no sistema.
Respostas Possíveis:
- 200 OK: Retorna o objeto da última versão dos termos.

{
  "latestVersion": {
    "id": 1,
    "version": "1.0.0",
    "createdAt": "2023-10-27T10:00:00.000Z",
    "updatedAt": "2023-10-27T10:00:00.000Z"
  }
}

401 Unauthorized: Token de acesso inválido ou ausente.
500 Internal Server Error: Nenhuma versão dos termos foi encontrada no sistema.

Aceitar os Termos de Uso

Rota: POST /v1/terms-acceptance/accept
Descrição: Registra o aceite do usuário para a versão mais recente dos termos de uso.
Lógica de Negócio:
- Verifica se o usuário já aceitou a última versão. Se sim, retorna uma mensagem informativa.
- Se não, cria um novo registro de aceite vinculando o usuário à versão mais recente dos termos.
Respostas Possíveis:
- 201 Created: Termos aceitos com sucesso. Retorna o registro do aceite.

{
  "message": "Termos aceitos.",
  "acceptance": {
    "id": 1,
    "userId": 123,
    "termsVersion": "1.0.0",
    "acceptedAt": "2023-10-27T10:00:00.000Z"
  }
}

201 Created (Já aceito): Retorna uma mensagem indicando que os termos já foram aceitos.

{
  "message": "Termos já aceitos."
}

401 Unauthorized: Token de acesso inválido ou ausente.

Rotas Administrativas

Autenticação: As rotas a seguir requerem um token de acesso de administrador válido (AdminAccessTokenGuard).

Criar Nova Versão dos Termos

Rota: POST /v1/terms-acceptance/version
Descrição: Cria uma nova versão para os termos de uso.
Corpo da Requisição:

{
  "version": "2.0.0"
}

Respostas Possíveis:
- 201 Created: Nova versão criada com sucesso.

{
  "message": "Nova versão dos termos criada com sucesso.",
  "version": {
    "id": 2,
    "version": "2.0.0",
    "createdAt": "2024-01-15T14:00:00.000Z",
    "updatedAt": "2024-01-15T14:00:00.000Z"
  }
}

401 Unauthorized: Token de acesso de administrador inválido ou ausente.
500 Internal Server Error: A versão especificada já existe.

Semear Aceitação de Termos (Seed)

Rota: POST /v1/terms-acceptance/seed
Descrição: Registra a versão mais recente dos termos para todos os usuários existentes, sem marcá-los como aceitos. Útil ao introduzir uma nova versão para garantir que todos os usuários sejam solicitados a aceitá-la.
Respostas Possíveis:
- 201 Created: Processo de semeadura concluído com sucesso.

{
  "message": "Aceitação de termos registrada para todos os usuários."
}

401 Unauthorized: Token de acesso de administrador inválido ou ausente.

Rotas de Limites de Transação (v1)

A seguir estão detalhadas as rotas da API disponíveis no TransactionsLimitsController, responsável pelo gerenciamento dos limites de transação para a conta do cliente.

Autenticação: Todas as rotas descritas abaixo são protegidas e requerem um token de acesso de cliente válido (AccessTokenGuard) enviado no cabeçalho da requisição.

Gerenciamento de Limites

Obter Limites de Transação

Rota: GET /v1/transaction-limits
Descrição: Retorna os limites de transação configurados para o cliente autenticado, incluindo o valor máximo permitido para cada tipo e período.
Parâmetros de Query:
- transactionsType (string | string[], opcional): Filtra por um ou mais tipos de transação (ex: PIX, TED).
Respostas Possíveis:
- 200 OK: Retorna um array com os limites do cliente.

[
  {
    "id": 1,
    "transactionsType": "PIX",
    "value": 5000,
    "period": "DAY",
    "maxLimit": 10000
  },
  {
    "id": 2,
    "transactionsType": "PIX",
    "value": 2000,
    "period": "NIGHT",
    "maxLimit": 5000
  }
]

401 Unauthorized: Token de acesso inválido ou ausente.

Atualizar Limite de Transação

Rota: PATCH /v1/transaction-limits
Descrição: Solicita a atualização de um limite de transação. Se o novo valor for menor que o atual, a alteração é imediata. Se for maior, uma solicitação é criada para aprovação.
Corpo da Requisição:

{
  "transactionsType": "PIX",
  "value": 7000,
  "period": "DAY"
}

Respostas Possíveis:
- 200 OK: Retorna uma mensagem indicando o status da solicitação (atualização imediata ou solicitação pendente).
  - Exemplo (solicitação pendente): {“message”: “Solicitação de atualização de limite recebida. A atualização está sendo processada e você será notificado assim que for concluída.”}
  - Exemplo (atualização imediata): {“message”: “Limite de transação atualizado com sucesso.”}
- 400 Bad Request: Dados inválidos, como value negativo ou solicitação pendente já existente.
- 401 Unauthorized: Token de acesso inválido ou ausente.
- 404 Not Found: O limite para o tipo e período especificados não foi encontrado.

Listar Solicitações de Alteração de Limite

Rota: GET /v1/transaction-limits/requests
Descrição: Retorna o histórico de solicitações de alteração de limite feitas pelo cliente.
Parâmetros de Query:
- transactionsType (string | string[], opcional): Filtra por um ou mais tipos de transação.
Respostas Possíveis:
- 200 OK: Retorna um array com as solicitações de alteração de limite.

[
  {
    "id": 1,
    "value": 7000,
    "status": "PENDING",
    "createdAt": "2024-06-20T10:00:00.000Z",
    "updatedAt": "2024-06-20T10:00:00.000Z"
  }
]

401 Unauthorized: Token de acesso inválido ou ausente.

Documentação - API CSBBenk - Versão 1.1

Tecnologias

Integrações com Outras API’s

Bibliotecas Usadas

Ambiente de Desenvolvimento

Requisitos necessários

Configurando o Ambiente de Desenvolvimento

Diagramas

C4 Model - Contexto

C4 Model - Container - Interação Cliente

C4 Model - Container - Interação Administrador Banco

Módulos

Rotas

Rotas de Contas (v1)

Onboarding e Cadastro

Registrar Conta (PF/PJ)

Criar Proposta de Onboarding

Consultar Proposta de Onboarding

Consultar Status da Conta

Enviar Documentos (KYC)

Gerenciamento da Conta

Gerar Token de Conta

Enviar OTP para Encerramento de Conta

Encerrar Conta

Consultas (Marketplace)

Listar Contas do Marketplace

Consultar Conta Única do Marketplace

Rotas de Contas do Admin (v1)

Consulta de Contas e Usuários

Listar Contas de Clientes

Obter Visão Geral das Contas

Obter Visão Geral das Contas por Período

Listar Usuários de Clientes

Obter Detalhes de uma Conta por ID

Transações e Chaves PIX

Listar Chaves PIX de um Cliente

Listar Transações de um Cliente

Gerenciamento de Taxas

Listar Transações de Taxas de um Cliente

Obter Transação de Taxa por ID de Conciliação

Cobrar Taxa Manualmente

Estornar Taxa Manualmente

Onboarding (KYC)

Obter Arquivos da Proposta

Rotas de Autenticação do Admin (v1)

Autenticação

Realizar Login (Sign-in)

Atualizar Token de Acesso (Refresh Token)

Rotas de Configuração de Taxas do Admin (v1)

Gerenciamento de Configurações de Taxas

Listar Todas as Configurações de Taxas

Obter a Configuração de Taxa Ativa

Criar Nova Configuração de Taxa

Ativar uma Configuração de Taxa

Rotas de Planos de Assinatura do Admin (v1)

Gerenciamento de Planos de Assinatura

Listar Todos os Planos de Assinatura

Criar Novo Plano de Assinatura

Publicar um Plano de Assinatura

Despublicar um Plano de Assinatura

Obter Configurações de Assinatura

Rotas de Parâmetros do Sistema (Admin v1)

Gerenciamento de Parâmetros do Sistema

Listar Parâmetros do Sistema (Paginado)

Consultar Parâmetro Específico

Atualizar Parâmetro Específico

Rotas de Limites de Transação do Admin (v1)

Gerenciamento de Solicitações de Limite de Transação

Listar Solicitações Pendentes de Aprovação

Aprovar Solicitação de Alteração de Limite

Rejeitar Solicitação de Alteração de Limite

Rotas de Usuários Administradores (v1)

Gerenciamento de Usuários Administradores

Listar Todos os Usuários Administradores

Obter um Usuário Administrador por ID

Obter Dados do Usuário Logado

Criar Novo Usuário Administrador

Atualizar Usuário Administrador

Atualizar Senha de Usuário Administrador

Deletar Usuário Administrador