BRazucaFlow API - Documentação Técnica

Visão Geral

A API BRazucaFlow centraliza as operações financeiras do sistema: usuários, perfis, plano de contas, contas a pagar, contas a receber, receitas, despesas, auditoria, backups e dashboard.

Esta documentação descreve os endpoints disponíveis, parâmetros aceitos, exemplos de payload e regras relevantes para consumo da API.

Base URL
Em desenvolvimento local, a API normalmente responde em http://localhost:3000. Em produção, substitua pela URL pública configurada para o servidor.

Índice

Autenticação

A API utiliza autenticação por token JWT. Após autenticar o usuário pela rota de login, envie o token nas demais requisições usando o cabeçalho HTTP abaixo:

Authorization: Bearer <token_jwt>

A rota de login é pública. Todas as demais rotas exigem usuário autenticado, e algumas são restritas ao perfil Super Admin.

Padrão de Resposta

Sucesso

{
  "success": true,
  "data": {},
  "status": 200
}

Erro

{
  "success": false,
  "error": "Descrição do erro",
  "status": 400
}

Status	Uso
`200`	Consulta, atualização, exclusão ou ação executada com sucesso.
`201`	Registro criado com sucesso.
`400`	Validação ou regra de negócio impediu a operação.
`401`	Token ausente, token inválido ou credenciais inválidas.
`403`	Usuário autenticado sem permissão para a operação.
`404`	Registro não encontrado.
`409`	Conflito de dados, como registro duplicado.
`500`	Erro interno inesperado.

Convenções

Item	Descrição
Paginação	Quando disponível, use `page` e `limit`. O limite máximo aplicado pela API é 100 registros por página.
Ordenação	Use `sortBy` e `sortDirection`, conforme os campos aceitos em cada módulo.
Datas	Envie datas no formato `YYYY-MM-DD`.
Valores monetários	Envie números em formato decimal, por exemplo `1500.75`.
Booleanos	A API aceita booleanos em campos como `paid`, `status`, `person` e similares.
IDs de exemplo	Os IDs nos payloads são exemplos. Devem ser substituídos por registros existentes no banco.

Segurança: esta documentação não deve conter usuários reais, senhas, tokens ou dados sensíveis. Para testes, configure credenciais em ambiente seguro.

Rotas de login e manutenção de usuários do sistema.

POST

Autentica um usuário e retorna um token JWT.

/api/users/login

Autenticação: Não requerida
Permissão: Pública

Exemplo de payload

{
  "username": "login_do_usuario",
  "password": "senha_do_usuario"
}

Não documentar senhas reais nesta rota.
O token retornado deve ser enviado no cabeçalho Authorization das demais rotas.

GET

Lista usuários.

/api/users

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Número da página.
`limit`	Quantidade por página, até 100.
`search`	Busca por nome, login ou perfil.
`sortBy`	id, nome, login, perfil ou status.
`sortDirection`	asc ou desc.

Super Admin visualiza todos os usuários.
Administrador não visualiza Super Admin.
Operacional visualiza apenas a própria conta.

GET

Consulta um usuário específico.

/api/users/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria um usuário.

/api/users

Autenticação: Bearer Token
Permissão: Administrador ou Super Admin

Exemplo de payload

{
  "username": "operador",
  "name": "Usuário Operacional",
  "password": "senha_inicial",
  "active": 1,
  "profileId": 3
}

PUT

Atualiza um usuário.

/api/users/:id

Autenticação: Bearer Token
Permissão: Administrador ou Super Admin; Operacional somente a própria conta com restrições.

Exemplo de payload

{
  "username": "operador",
  "name": "Usuário Atualizado",
  "password": "nova_senha_opcional",
  "active": 1,
  "profileId": 3
}

Senha é opcional na alteração.

DELETE

Remove um usuário.

/api/users/:id

Autenticação: Bearer Token
Permissão: Administrador ou Super Admin

Super Admin não pode ser removido pela tela.
Usuário não pode remover a si mesmo.
A API protege contra remoção do único administrador ativo, exceto nas regras permitidas ao Super Admin.

Consulta e manutenção dos perfis de acesso.

GET

Lista os perfis disponíveis para uso no cadastro de usuários.

/api/profiles

Autenticação: Bearer Token
Permissão: Usuário autenticado

GET

Consulta um perfil específico.

/api/profiles/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria um perfil.

/api/profiles

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "name": "Nome do Perfil",
  "description": "Descrição do perfil",
  "statusProfile": true
}

PUT

Atualiza um perfil.

/api/profiles/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "name": "Perfil Atualizado",
  "description": "Descrição atualizada",
  "statusProfile": true
}

DELETE

Remove um perfil.

/api/profiles/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Controle de contas a pagar, geração em massa e pagamento com geração opcional de despesa.

GET

Lista contas a pagar.

/api/accounts-payable

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Número da página.
`limit`	Quantidade por página, até 100.
`search`	Busca por descrição, documento, origem, tipo de conta ou tipo de pagamento.
`status`	pago, pendente ou vencido.
`paymentTypeId`	ID do tipo de pagamento.
`accountTypeId`	ID do tipo de conta.
`originId`	ID da origem.
`dateFrom`	Data inicial de vencimento.
`dateTo`	Data final de vencimento.
`sortBy`	id, descricao, dataVencimento, valor ou status.
`sortDirection`	asc ou desc.

GET

Consulta uma conta a pagar.

/api/accounts-payable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma conta a pagar.

/api/accounts-payable

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "accountTypeId": 1,
  "paymentTypeId": 1,
  "originId": null,
  "documentNumber": "DOC-001",
  "description": "Descrição da conta",
  "value": 1500.75,
  "nominalDate": "2026-06-22",
  "dueDate": "2026-07-22",
  "paid": false
}

Documento e origem são opcionais.
Data nominal não pode ser maior que a data de vencimento.

POST

Gera contas a pagar em massa a partir de uma origem.

/api/accounts-payable/multiple

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "originId": 1,
  "installments": 3,
  "accountTypeId": 1,
  "paymentTypeId": 1,
  "value": 900,
  "nominalDate": "2026-06-22",
  "dueDate": "2026-07-22",
  "documentNumber": "DOC-MASSA",
  "description": "Compra parcelada"
}

O valor informado é o total e será dividido entre as parcelas.
A origem deve existir e estar de acordo com o fluxo de contas a pagar.

PUT

Atualiza uma conta a pagar.

/api/accounts-payable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "accountTypeId": 1,
  "paymentTypeId": 1,
  "originId": null,
  "documentNumber": "DOC-001",
  "description": "Descrição atualizada",
  "value": 1600,
  "nominalDate": "2026-06-22",
  "dueDate": "2026-07-25",
  "paid": false
}

DELETE

Remove uma conta a pagar.

/api/accounts-payable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

A remoção é bloqueada se a conta estiver paga ou possuir despesa vinculada.

PUT

Marca uma conta a pagar como paga.

/api/accounts-payable/:id/pay

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "paymentTypeId": 1,
  "generateExpense": true,
  "cashAccountId": 1
}

Quando generateExpense for true, a API cria uma despesa vinculada à conta paga.

PUT

Desmarca uma conta a pagar como paga.

/api/accounts-payable/:id/unpay

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{}

A operação é bloqueada se existir despesa vinculada.

POST

Busca avançada para relatórios.

/api/accounts-payable/search

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "status": "pending",
  "paymentTypeId": 1,
  "originId": 1,
  "dateField": "dueDate",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-12-31",
  "orderBy": "dueDate",
  "orderDirection": "ASC"
}

Controle de contas a receber, geração em massa e recebimento com geração opcional de receita.

GET

Lista contas a receber.

/api/accounts-receivable

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Número da página.
`limit`	Quantidade por página, até 100.
`search`	Busca por descrição, documento, origem, tipo de conta ou tipo de pagamento.
`status`	recebido, pendente ou vencido.
`paymentTypeId`	ID do tipo de pagamento.
`accountTypeId`	ID do tipo de conta.
`originId`	ID da origem.
`dateFrom`	Data inicial de vencimento.
`dateTo`	Data final de vencimento.
`sortBy`	id, descricao, dataVencimento, valor ou status.
`sortDirection`	asc ou desc.

GET

Consulta uma conta a receber.

/api/accounts-receivable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma conta a receber.

/api/accounts-receivable

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "accountTypeId": 1,
  "paymentTypeId": 1,
  "originId": null,
  "documentNumber": "DOC-001",
  "description": "Descrição da conta",
  "value": 2500,
  "nominalDate": "2026-06-22",
  "dueDate": "2026-07-22",
  "paid": false
}

POST

Gera contas a receber em massa a partir de uma origem.

/api/accounts-receivable/multiple

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "originId": 1,
  "installments": 3,
  "accountTypeId": 1,
  "paymentTypeId": 1,
  "value": 900,
  "nominalDate": "2026-06-22",
  "dueDate": "2026-07-22",
  "documentNumber": "DOC-MASSA",
  "description": "Venda parcelada"
}

PUT

Atualiza uma conta a receber.

/api/accounts-receivable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma conta a receber.

/api/accounts-receivable/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

A remoção é bloqueada se a conta estiver recebida ou possuir receita vinculada.

PUT

Marca uma conta a receber como recebida.

/api/accounts-receivable/:id/receive

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "paymentTypeId": 1,
  "generateIncome": true,
  "cashAccountId": 1
}

Quando generateIncome for true, a API cria uma receita vinculada à conta recebida.

PUT

Desmarca uma conta a receber como recebida.

/api/accounts-receivable/:id/unreceive

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{}

A operação é bloqueada se existir receita vinculada.

POST

Busca avançada para relatórios.

/api/accounts-receivable/search

Autenticação: Bearer Token
Permissão: Usuário autenticado

Lançamentos realizados no caixa e contas caixa utilizadas nos vínculos financeiros.

GET

Lista receitas.

/api/incomes

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Número da página.
`limit`	Quantidade por página, até 100.
`search`	Busca por descrição, categoria, tipo de conta ou conta caixa.
`accountTypeId`	ID do tipo de conta.
`cashAccountId`	ID da conta caixa.
`dateFrom`	Data inicial.
`dateTo`	Data final.
`sortBy`	id, descricao, valor, dataReceita, tipoConta ou contaCaixa.
`sortDirection`	asc ou desc.

GET

Consulta uma receita.

/api/incomes/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma receita.

/api/incomes

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "cashAccountId": 1,
  "accountTypeId": 1,
  "accountReceivableId": null,
  "description": "Receita manual",
  "value": 1500.75,
  "incomeDate": "2026-06-22"
}

accountReceivableId deve ser nulo em receitas manuais.
Uma conta a receber pode possuir apenas uma receita vinculada.

PUT

Atualiza uma receita.

/api/incomes/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma receita.

/api/incomes/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

GET

Lista despesas.

/api/expenses

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Número da página.
`limit`	Quantidade por página, até 100.
`search`	Busca por descrição, categoria, tipo de conta ou conta caixa.
`accountTypeId`	ID do tipo de conta.
`cashAccountId`	ID da conta caixa.
`dateFrom`	Data inicial.
`dateTo`	Data final.
`sortBy`	id, descricao, valor, dataDespesa, tipoConta ou contaCaixa.
`sortDirection`	asc ou desc.

GET

Consulta uma despesa.

/api/expenses/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma despesa.

/api/expenses

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "cashAccountId": 1,
  "accountTypeId": 1,
  "accountPayableId": null,
  "description": "Despesa manual",
  "value": 500.75,
  "expenseDate": "2026-06-22"
}

accountPayableId deve ser nulo em despesas manuais.
Uma conta a pagar pode possuir apenas uma despesa vinculada.

PUT

Atualiza uma despesa.

/api/expenses/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma despesa.

/api/expenses/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

GET

Lista contas caixa.

/api/cash-accounts

Autenticação: Bearer Token
Permissão: Usuário autenticado

GET

Consulta uma conta caixa.

/api/cash-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma conta caixa.

/api/cash-accounts

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "name": "Conta Principal",
  "description": "Descrição da conta caixa",
  "status": true
}

PUT

Atualiza uma conta caixa.

/api/cash-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma conta caixa.

/api/cash-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Categorias, tipos de contas, tipos de pagamento e origens utilizadas pelo financeiro.

GET

Lista categorias de tipos de contas.

/api/category-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Página.
`limit`	Limite.
`search`	Busca.
`type`	Receita ou Despesa.
`status`	Ativo ou Inativo.
`specie`	Espécie.

GET

Consulta uma categoria.

/api/category-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma categoria.

/api/category-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "description": "Receitas operacionais",
  "type": "Receita",
  "specie": "Operacional",
  "status": true
}

PUT

Atualiza uma categoria.

/api/category-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma categoria.

/api/category-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Bloqueado se a categoria estiver vinculada a tipo de conta.

GET

Lista tipos de contas.

/api/account-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Página.
`limit`	Limite.
`search`	Busca.
`type`	Receita ou Despesa.
`status`	Ativo ou Inativo.
`categoryId`	ID da categoria.

GET

Consulta um tipo de conta.

/api/account-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria um tipo de conta.

/api/account-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "description": "Vendas de produtos",
  "type": "Receita",
  "specie": "Operacional",
  "status": true,
  "categoryId": 1
}

PUT

Atualiza um tipo de conta.

/api/account-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove um tipo de conta.

/api/account-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Bloqueado se houver vínculo com contas, receitas ou despesas.

GET

Lista tipos de pagamento.

/api/payment-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

GET

Consulta um tipo de pagamento.

/api/payment-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria um tipo de pagamento.

/api/payment-types

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "name": "Pix",
  "description": "Pagamento via Pix",
  "status": true
}

PUT

Atualiza um tipo de pagamento.

/api/payment-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove um tipo de pagamento.

/api/payment-types/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Bloqueado se estiver vinculado a contas a pagar ou receber.

GET

Lista origens de contas.

/api/origin-accounts

Autenticação: Bearer Token
Permissão: Usuário autenticado

Parâmetros de consulta

Nome	Descrição
`page`	Página.
`limit`	Limite.
`search`	Busca por nome ou observação.
`category`	1 Despesa ou 2 Receita.
`person`	Pessoa ou Operação.
`status`	Ativo ou Inativo.

GET

Consulta uma origem.

/api/origin-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma origem.

/api/origin-accounts

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "description": "Fornecedor exemplo",
  "obs": "Observação opcional",
  "category": 1,
  "person": true,
  "status": true
}

PUT

Atualiza uma origem.

/api/origin-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma origem.

/api/origin-accounts/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

Bloqueado se estiver vinculada a contas a pagar ou receber.

Rotas técnicas de manutenção e consulta consolidada.

GET

Lista logs de auditoria.

/api/audit-logs

Autenticação: Bearer Token
Permissão: Super Admin

Parâmetros de consulta

Nome	Descrição
`page`	Página.
`limit`	Limite até 100.
`module`	Módulo filtrado.
`action`	Ação filtrada.
`login`	Login do usuário.
`status`	SUCESSO, ERRO ou INFO.
`startDate`	Data inicial.
`endDate`	Data final.
`sortBy`	dataHora, login, perfil, acao, modulo, status ou ip.
`sortDirection`	asc ou desc.

GET

Consulta opções disponíveis para filtros da auditoria.

/api/audit-logs/filter-options

Autenticação: Bearer Token
Permissão: Super Admin

GET

Consulta a última limpeza manual de logs.

/api/audit-logs/last-manual-cleanup

Autenticação: Bearer Token
Permissão: Super Admin

POST

Gera backup SQL dos logs antes da limpeza.

/api/audit-logs/cleanup-backup

Autenticação: Bearer Token
Permissão: Super Admin

Exemplo de payload

{
  "months": 12
}

Períodos aceitos: 6, 12 ou 24 meses.
A resposta é um arquivo SQL.

DELETE

Remove logs antigos.

/api/audit-logs/cleanup

Autenticação: Bearer Token
Permissão: Super Admin

Exemplo de payload

{
  "months": 12
}

Períodos aceitos: 6, 12 ou 24 meses.
Operação definitiva.

GET

Gera backup SQL completo do banco.

/api/backups/sql

Autenticação: Bearer Token
Permissão: Super Admin

A resposta é um arquivo SQL.

GET

Retorna dados consolidados da Home.

/api/dashboard/home

Autenticação: Bearer Token
Permissão: Usuário autenticado

Inclui dados mensais, contas pendentes, receitas e despesas recentes.

GET

Lista formas de pagamento legadas.

/api/payment-methods

Autenticação: Bearer Token
Permissão: Usuário autenticado

Rota mantida por compatibilidade com a tabela formas_pgto.

GET

Consulta uma forma de pagamento legada.

/api/payment-methods/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

POST

Cria uma forma de pagamento legada.

/api/payment-methods

Autenticação: Bearer Token
Permissão: Usuário autenticado

Exemplo de payload

{
  "name": "À vista",
  "description": "Pagamento à vista",
  "status": true
}

PUT

Atualiza uma forma de pagamento legada.

/api/payment-methods/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado

DELETE

Remove uma forma de pagamento legada.

/api/payment-methods/:id

Autenticação: Bearer Token
Permissão: Usuário autenticado