v1.0.052 endpoints ativos

Documentação da API

Referência oficial da API REST do ContaUp — endpoints, parâmetros, exemplos de request/response e regras de autenticação, módulo por módulo.

Visão Geral e Padrões

1. Base URL

Todas as requisições devem ser feitas para a seguinte URL base em produção (o Gateway Nginx):

https://nginx-production-6d15.up.railway.app

2. Fluxo Completo de Onboarding

Cadastrar o dono em POST /auth/registrar-dono.
Fazer login em POST /auth/login e guardar o token.
Criar a empresa em POST /empresas.
Usar o token em todas as chamadas para os demais módulos.

Segurança & DDoS (Nginx)

Para garantir resiliência contra ataques de força bruta, implementamos um API Gateway na nuvem (Railway) usando Nginx. Ele atua como um Proxy Reverso com Rate Limiting estrito configurado para 5 requisições/segundo por IP.

GETBloqueio Automático (Rate Limit)

Infraestrutura

Qualquer tentativa de sobrecarregar a API com múltiplas requisições simultâneas (acima de 10 requests em rajada) será interceptada antes de atingir o servidor Node.js. O Nginx derruba a conexão instantaneamente para economizar CPU/Memória do Backend.

Body (JSON)

Sem corpo de requisição.

Resposta (429 Too Many Requests)

429 Too Many Requests response.json

<html>
  <head><title>429 Too Many Requests</title></head>
  <body>
    <center><h1>429 Too Many Requests</h1></center>
    <hr><center>nginx</center>
  </body>
</html>

Possíveis Erros

Status / Código	Quando ocorre
429 TOO_MANY_REQUESTS	O IP do cliente excede a taxa de 5 requisições por segundo configurada na limit_req_zone do Nginx.

Atenção

Esta é uma camada de infraestrutura (Reverse Proxy) e não uma rota Express. A validação ocorre a nível de rede no Railway.
Protege rotas sensíveis como POST /auth/login contra ataques de dicionário e brute force.

Autenticação

Login e cadastro inicial de donos. /login e /registrar-dono são as únicas rotas públicas deste módulo. Cadastro de funcionário (/registrar-usuario) exige token e cargo DONO.

POST/auth/login

Rota Pública

Autentica via Supabase Auth e retorna o token JWT junto com os dados básicos do usuário.

Body (JSON)

Campo	Tipo	Descrição
email*	string	E-mail cadastrado do usuário.
senha*	string	Senha em texto puro.

Exemplo

request.json

{
  "email": "carlos@acmecorp.com",
  "senha": "senha123"
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsIn...",
    "usuario": { "id": "uuid", "nome": "string", "email": "string" }
  }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Credenciais inválidas, ou usuário autenticado no Supabase Auth mas sem registro correspondente na tabela usuarios.
500	Falha inesperada de comunicação com Supabase/banco.

POST/auth/registrar-dono

Rota Pública

Cria o usuário inicial com cargo DONO, ainda sem empresa vinculada. O fluxo de onboarding completo é: registrar o dono aqui → fazer login → criar a empresa em POST /empresas.

Body (JSON)

Campo	Tipo	Descrição
nome*	string	Nome completo. Mínimo 2 caracteres.
email*	string	E-mail válido (formato verificado por Zod).
senha*	string	Mínimo 6 caracteres.

Exemplo

request.json

{
  "nome": "Carlos Gestor",
  "email": "carlos@acmecorp.com",
  "senha": "senha123"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "message": "Dono registrado com sucesso!"
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Campos ausentes ou fora das regras de validação.
409 CONFLITO	Já existe um usuário com este e-mail.

Atenção

A resposta não retorna token — após registrar, o frontend deve chamar POST /auth/login separadamente.
O usuário criado fica sem empresaId. Qualquer chamada autenticada a rotas que dependem de empresa (funcionários, plano de contas, lançamentos etc.) retornará 400 até que POST /empresas seja chamado.

POST/auth/registrar-usuario

Token JWT Requerido (cargo DONO)

Cria um funcionário (cargo definido pelo dono) já vinculado à empresa do usuário autenticado. A empresa é sempre a do dono que faz a chamada — empresa_id não é aceito no body, evitando que um cliente vincule o novo usuário a outra empresa.

Body (JSON)

Campo	Tipo	Descrição
nome*	string	Mínimo 2 caracteres.
email*	string	E-mail válido e único.
senha*	string	Mínimo 6 caracteres.
cargo*	string	Cargo do funcionário (nome livre, exceto 'DONO', que é reservado).
ativo	boolean
foto_url	string (URL)	URL válida da foto de perfil.

Exemplo

request.json

{
  "nome": "Maria Caixa",
  "email": "maria@acmecorp.com",
  "senha": "senha123",
  "cargo": "CAIXA"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "message": "Funcionário registrado com sucesso!",
  "data": { "id": "uuid" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Campos inválidos no schema Zod.
403 NAO_AUTORIZADO	Usuário autenticado não é DONO, ou não possui empresa vinculada.
409 CONFLITO	E-mail já cadastrado.

GET/auth/me

Token JWT Requerido

Retorna os dados do usuário autenticado e, se houver, da empresa vinculada.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": {
    "usuario": { "id": "uuid", "nome": "string", "email": "string", "cargo": "string", "ativo": true, "foto_url": "string | null" },
    "empresa": { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" } | null
  }
}

Possíveis Erros

Status / Código	Quando ocorre
404 NAO_ENCONTRADO	Usuário autenticado não existe mais na tabela usuarios.

GET/auth/sessoes

Token JWT Requerido

Lista o histórico recente de logins (sessões) do usuário autenticado.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    { "id": "uuid", "device": "Chrome · Windows", "location": "string | 'Desconhecida'", "time": "string (data)", "status": "ok" }
  ]
}

POST/auth/sessoes/desconectar-todas

Token JWT Requerido

Invalida globalmente (Supabase Auth signOut escopo 'global') todos os tokens do usuário, derrubando todas as sessões ativas em qualquer dispositivo.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Todos os dispositivos foram desconectados."
}

Possíveis Erros

Status / Código	Quando ocorre
500	Token ausente, mal formatado, ou falha ao comunicar com o Supabase Auth.

GET/auth/usuarios

Token JWT Requerido

Lista os usuários da empresa do usuário autenticado, exceto o próprio usuário que faz a chamada.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    { "id": "uuid", "nome": "string", "email": "string", "cargo": "string", "ativo": true, "foto_url": "string | null" }
  ]
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário autenticado não possui empresa vinculada.

PUT/auth/usuarios/:id

Token JWT Requerido

Atualiza dados de um usuário (nome, cargo, ativo, foto_url), sempre revinculando-o à empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)	ID do usuário a atualizar.

Body (JSON)

Campo	Tipo	Descrição
nome	string
cargo	string
ativo	boolean
foto_url	string (URL)

Exemplo

request.json

{
  "nome": "Maria Caixa",
  "ativo": false
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "nome": "string", "email": "string", "cargo": "string", "ativo": true }
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário autenticado não possui empresa vinculada.
404	Usuário não encontrado.

DELETE/auth/usuarios/:id

Token JWT Requerido

Remove um usuário. Se a query excluirContas=true for enviada, remove também as contas a pagar geradas para ele (ex.: salários).

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)	ID do usuário a remover.

Query Params

Campo	Tipo	Descrição
excluirContas	boolean ('true'\|'false')	Se 'true', apaga contas a pagar com descrição '[Salário] {nome}' vinculadas ao usuário.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Usuário removido com sucesso"
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário autenticado não possui empresa vinculada.
404	Usuário não encontrado.

Empresas

CRUD de empresas. Todas as rotas exigem JWT. O acesso é restrito à própria empresa do usuário autenticado: empresaId é sempre derivado do token (nunca de parâmetros da requisição).

POST/empresas

Token JWT Requerido

Cria a empresa e gera automaticamente um plano de contas padrão com 15 contas (Ativo, Passivo, PL, Receita, Despesa).

Body (JSON)

Campo	Tipo	Descrição
nome*	string	Mínimo 2 caracteres.
nome_fantasia*	string	Mínimo 2 caracteres.
razao_social*	string	Mínimo 2 caracteres.
cnpj*	string	Exatamente 14 caracteres/dígitos. Deve ser único.

Exemplo

request.json

{
  "nome": "Acme Corp",
  "nome_fantasia": "Acme",
  "razao_social": "Acme Corp Finance Ltda",
  "cnpj": "12345678000199"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "message": "Empresa criada com plano de contas padrao.",
  "data": {
    "empresa": { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" },
    "plano_contas_padrao": [
      { "id": "uuid", "empresa_id": "uuid", "codigo": "1.1.01", "nome": "Caixa", "tipo": "ATIVO" }
    ]
  }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Campos ausentes ou inválidos.
409 CONFLITO	CNPJ já cadastrado em outra empresa.
500 ERRO_BANCO_DE_DADOS	Falha ao persistir empresa ou plano de contas.

Atenção

Contas padrão criadas incluem códigos fixos usados por outras rotas: 1.1.01 (Caixa), 4.1.01 (Receita) e 5.1.01 (Despesa) — essenciais para lançamentos simplificados e baixa de contas a receber.

GET/empresas

Token JWT Requerido

Retorna, em formato de lista, apenas a empresa vinculada ao usuário autenticado (req.usuario.empresaId, derivado do token).

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" }
  ]
}

GET/empresas/:id

Token JWT Requerido

Busca uma empresa por ID. Só é permitido buscar a própria empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)	ID da empresa.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	O :id da URL não corresponde à empresa vinculada ao usuário autenticado.

PUT/empresas/:id

Token JWT Requerido (cargo DONO)

Atualiza dados cadastrais da própria empresa. Aceita atualização parcial (ao menos um campo).

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)	ID da empresa.

Body (JSON)

Campo	Tipo	Descrição
nome	string	Mínimo 2 caracteres.
nome_fantasia	string	Mínimo 2 caracteres.
razao_social	string	Mínimo 2 caracteres.
cnpj	string	Exatamente 14 caracteres.

Exemplo

request.json

{
  "nome_fantasia": "Acme 2.0"
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Nenhum campo informado, ou campos fora das regras de validação.
401 NAO_AUTORIZADO	O :id da URL não corresponde à empresa do usuário, ou usuário não é DONO.

DELETE/empresas/:id

Token JWT Requerido (cargo DONO)

Remove a própria empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)	ID da empresa.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Empresa removida com sucesso.",
  "data": { "id": "uuid", "nome": "string", "nome_fantasia": "string", "razao_social": "string", "cnpj": "string" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	O :id da URL não corresponde à empresa do usuário, ou usuário não é DONO.

Funcionários

Cadastro completo (RH) dos funcionários da empresa do usuário autenticado, incluindo dados salariais, configuração de folha e fechamento mensal de folha de pagamento.

POST/funcionarios

Token JWT Requerido (cargo DONO)

Cria o cadastro de RH de um funcionário (salário, dia de pagamento, configuração de descontos/benefícios da folha). Distinto de POST /auth/registrar-usuario, que cria as credenciais de login.

Body (JSON)

Campo	Tipo	Descrição
nome*	string	Mínimo 2 caracteres.
email*	string	E-mail válido.
cargo*	string
cpf_cnpj*	string	Mínimo 11 caracteres.
salario*	number	Não pode ser negativo.
dia_pagamento	number	1 a 31. Padrão 5.
data_admissao*	string (data)	Data parseável pelo JS.
config_folha	object	Configuração de descontos (INSS, FGTS, IRRF) e benefícios (vale transporte, vale refeição, plano de saúde).
foto_url	string (URL)

Exemplo

request.json

{
  "nome": "Maria Caixa",
  "email": "maria@acmecorp.com",
  "cargo": "CAIXA",
  "cpf_cnpj": "12345678900",
  "salario": 2500.0,
  "data_admissao": "2026-01-10"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "data": {
    "id": "uuid", "empresa_id": "uuid", "nome": "string", "cargo": "string", "email": "string",
    "cpf_cnpj": "string", "salario": 2500.0, "dia_pagamento": 5, "data_admissao": "string",
    "config_folha": "object | undefined", "foto_url": "string | undefined"
  }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Campos ausentes ou fora das regras do schema Zod, ou usuário sem empresa vinculada.
403 NAO_AUTORIZADO	Usuário autenticado não é DONO.

GET/funcionarios

Token JWT Requerido

Lista os funcionários da empresa do usuário autenticado.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    {
      "id": "uuid", "nome": "string", "email": "string",
      "empresa_id": "uuid", "cargo": "GERENTE | CAIXA | DONO",
      "cpf": "string | undefined", "data_nascimento": "string | undefined",
      "foto_url": "string | undefined"
    }
  ]
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário autenticado não possui empresa vinculada.

POST/funcionarios/folha/fechar

Token JWT Requerido (cargo DONO)

Fecha a folha de pagamento do mês/ano informado: gera holerites e as respectivas contas a pagar (salário líquido, FGTS, INSS) para todos os funcionários elegíveis da empresa. Idempotente por funcionário/mês/ano — pula quem já tem holerite gerado.

Body (JSON)

Campo	Tipo	Descrição
mes*	number	1 a 12.
ano*	number	Mínimo 2000.

Exemplo

request.json

{
  "mes": 6,
  "ano": 2026
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "success": true, "count": 3, "message": "Folha fechada com sucesso. 3 holerites gerados." }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Mês fora do intervalo 1-12, ou usuário sem empresa vinculada.
403 NAO_AUTORIZADO	Usuário autenticado não é DONO.

Atenção

Cria automaticamente, se ainda não existirem, as contas contábeis 5.1.04 (Despesas com Salários) e 5.1.05 (Impostos s/ Folha).

GET/funcionarios/folha/holerites

Token JWT Requerido

Lista os holerites gerados para a empresa em um mês/ano específico.

Query Params

Campo	Tipo	Descrição
mes*	number	1 a 12.
ano*	number

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    { "id": "uuid", "empresa_id": "uuid", "funcionario_id": "uuid", "mes_referencia": 6, "ano_referencia": 2026, "salario_bruto": 2500.0, "total_descontos": 300.0, "total_acrescimos": 0, "salario_liquido": 2200.0, "detalhes": "object" }
  ]
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Mês ou ano ausentes na query, ou usuário sem empresa vinculada.

GET/funcionarios/:id

Token JWT Requerido

Busca um funcionário por ID, restrito à empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "nome": "string", "cargo": "string", "email": "string", "cpf_cnpj": "string", "salario": 2500.0, "dia_pagamento": 5, "data_admissao": "string" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário sem empresa vinculada.
404	Funcionário não encontrado ou pertence a outra empresa.

PUT/funcionarios/:id

Token JWT Requerido (cargo DONO)

Atualiza o cadastro de RH do funcionário. Aceita atualização parcial.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
nome	string	Mínimo 2 caracteres.
cargo	string
cpf_cnpj	string
salario	number
dia_pagamento	number	1 a 31.
data_admissao	string (data)
config_folha	object
foto_url	string (URL)

Exemplo

request.json

{
  "salario": 2700.0
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "nome": "string", "cargo": "string", "salario": 2700.0 }
}

Possíveis Erros

Status / Código	Quando ocorre
403 NAO_AUTORIZADO	Usuário autenticado não é DONO.
404	Funcionário não encontrado ou pertence a outra empresa.

DELETE/funcionarios/:id

Token JWT Requerido (cargo DONO)

Remove o cadastro de RH do funcionário. Opcionalmente exclui também as contas a pagar de salário associadas.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Query Params

Campo	Tipo	Descrição
excluirContas	boolean ('true'\|'false')	Se 'true', apaga também as contas a pagar geradas para este funcionário.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Funcionário removido com sucesso.",
  "data": { "id": "uuid", "nome": "string" }
}

Possíveis Erros

Status / Código	Quando ocorre
403 NAO_AUTORIZADO	Usuário autenticado não é DONO.
404	Funcionário não encontrado ou pertence a outra empresa.

Plano de Contas

CRUD do plano de contas contábil (Ativo, Passivo, PL, Receita, Despesa, Custo) usado nos lançamentos e relatórios.

POST/plano-contas

Token JWT Requerido (cargo DONO)

Cria uma nova conta contábil na empresa do usuário autenticado.

Body (JSON)

Campo	Tipo	Descrição
codigo*	string	Código da conta (ex.: '1.1.02').
nome*	string	Mínimo 3 caracteres.
tipo*	'ATIVO'\|'PASSIVO'\|'PL'\|'RECEITA'\|'DESPESA'\|'CUSTO'

Exemplo

request.json

{
  "codigo": "1.1.02",
  "nome": "Bancos",
  "tipo": "ATIVO"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "message": "Conta contabil criada com sucesso.",
  "data": { "id": "uuid", "empresa_id": "uuid", "codigo": "string", "nome": "string", "tipo": "ATIVO" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Campos ausentes ou inválidos no schema Zod.
401 NAO_AUTORIZADO	Usuário sem empresa vinculada.

GET/plano-contas

Token JWT Requerido

Lista as contas contábeis da empresa do usuário autenticado. Não é possível listar contas de outras empresas.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [ { "id": "uuid", "empresa_id": "uuid", "codigo": "string", "nome": "string", "tipo": "ATIVO" } ]
}

GET/plano-contas/:id

Token JWT Requerido

Busca uma conta contábil por ID, restrita à empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "codigo": "string", "nome": "string", "tipo": "ATIVO" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Conta pertence a outra empresa, ou usuário sem empresa vinculada.

PUT/plano-contas/:id

Token JWT Requerido (cargo DONO)

Atualiza uma conta contábil. Aceita atualização parcial (ao menos um campo).

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
codigo	string
nome	string
tipo	'ATIVO'\|'PASSIVO'\|'PL'\|'RECEITA'\|'DESPESA'\|'CUSTO'

Exemplo

request.json

{
  "nome": "Bancos Conta Movimento"
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "codigo": "string", "nome": "string", "tipo": "ATIVO" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Nenhum campo informado.
401 NAO_AUTORIZADO	Conta pertence a outra empresa.

DELETE/plano-contas/:id

Token JWT Requerido (cargo DONO)

Remove uma conta contábil da empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Conta contabil removida com sucesso.",
  "data": { "id": "uuid", "empresa_id": "uuid", "codigo": "string", "nome": "string", "tipo": "ATIVO" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Conta pertence a outra empresa.

Lançamentos Contábeis

Registro de lançamentos em partida dobrada.

POST/lancamentos/lancamento

Token JWT Requerido

Cria um lançamento contábil completo de partida dobrada, com múltiplas partidas de débito/crédito.

Body (JSON)

Campo	Tipo	Descrição
empresa_id*	string (UUID)	Exigido pelo schema, porém ignorado pelo controller.
data_lancamento*	string/Date	Qualquer formato de data parseável pelo JS.
descricao*	string	Mínimo 5 caracteres.
tipoTransacao*	'DEBITO'\|'CREDITO'	Validado no schema, mas não influencia a lógica deste use case.
partidas*	array (mín. 2 itens)	Lista de partidas D/C. Cada item: conta_id (UUID), tipo ('D'\|'C'), valor (number positivo).

Exemplo

request.json

{
  "empresa_id": "uuid",
  "data_lancamento": "2026-06-23",
  "descricao": "Pagamento de aluguel",
  "tipoTransacao": "DEBITO",
  "partidas": [
    { "conta_id": "uuid-conta-despesa", "tipo": "D", "valor": 800.0 },
    { "conta_id": "uuid-conta-caixa", "tipo": "C", "valor": 800.0 }
  ]
}

Resposta (201 Created)

201 Created response.json

{
  "message": "Lançamento criado com sucesso!",
  "dados": { "...": "eco do payload validado enviado no body" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Usuário autenticado não possui empresa vinculada.
400 DESEQUILIBRIO_CONTABIL	Soma dos débitos é diferente da soma dos créditos.

GET/lancamentos/lancamentos

Token JWT Requerido

Lista todos os lançamentos (com suas partidas) da empresa do usuário autenticado.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

[
  {
    "id": "uuid",
    "empresaId": "uuid",
    "dataLancamento": "2026-06-01T00:00:00.000Z",
    "descricao": "string",
    "partidas": [ { "contaId": "uuid", "tipo": "D", "valor": 100.0 } ]
  }
]

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Usuário sem empresa vinculada.

POST/lancamentos/lancamento/simplificado

Token JWT Requerido

Cria um lançamento simplificado de receita ou despesa (o backend monta as partidas D/C automaticamente usando as contas padrão Caixa/Receita/Despesa da empresa, sem exigir conta_id do cliente).

Body (JSON)

Campo	Tipo	Descrição
descricao*	string	Mínimo 3 caracteres.
valor*	number	Positivo.
tipoTransacao*	'DEBITO'\|'CREDITO'	DEBITO gera uma DESPESA, CREDITO gera uma RECEITA.
data_lancamento*	string/Date	Qualquer formato de data parseável pelo JS.

Exemplo

request.json

{
  "descricao": "Venda balcão",
  "valor": 250.0,
  "tipoTransacao": "CREDITO",
  "data_lancamento": "2026-06-23"
}

Resposta (201 Created)

201 Created response.json

{
  "message": "Lançamento simplificado criado com sucesso!",
  "dados": { "...": "eco do payload validado enviado no body" }
}

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Usuário sem empresa vinculada.

Contas a Receber

Controle de valores a receber, sempre escopado à empresa do usuário autenticado.

POST/contas-receber

Token JWT Requerido

Cria uma conta a receber (nasce sempre como 'recebido: false').

Body (JSON)

Campo	Tipo	Descrição
origem*	string	Nome do cliente/origem. Mínimo 2 caracteres.
valor*	number	Positivo.
tipo*	string
data_previsao*	string (data)	Formato YYYY-MM-DD.

Exemplo

request.json

{
  "origem": "Cliente XPTO",
  "valor": 500.0,
  "tipo": "VENDA",
  "data_previsao": "2026-07-01"
}

Resposta (201 Created)

201 Created response.json

{
  "id": "uuid", "empresa_id": "uuid", "origem": "string", "valor": 500.0, "tipo": "string", "data_previsao": "2026-07-01", "recebido": false, "data_recebimento": null
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.

GET/contas-receber

Token JWT Requerido

Lista as contas a receber da empresa.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [
    { "id": "uuid", "empresa_id": "uuid", "origem": "string", "valor": 500.0, "data_previsao": "2026-07-01", "recebido": false }
  ]
}

PATCH/contas-receber/:id

Token JWT Requerido

Recebe/baixa a conta: marca como recebida e gera automaticamente o lançamento contábil de partida dobrada correspondente.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
valor_pago	number	Valor efetivamente recebido, se diferente do valor previsto.

Exemplo

request.json

{
  "valor_pago": 500.0
}

Resposta (200 OK)

200 OK response.json

{
  "message": "Conta recebida e lançamento contábil gerado com sucesso!",
  "dados": { "...": "conta a receber atualizada" }
}

Possíveis Erros

Status / Código	Quando ocorre
400	ID da conta ausente na URL.
403	Usuário sem empresa vinculada.

PUT/contas-receber/:id

Token JWT Requerido

Atualiza dados de uma conta a receber ainda não recebida. Não é possível editar uma conta já recebida.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
origem	string
valor	number
tipo	string
data_previsao	string (data)

Exemplo

request.json

{
  "valor": 550.0
}

Resposta (200 OK)

200 OK response.json

{
  "id": "uuid", "empresa_id": "uuid", "origem": "string", "valor": 550.0, "recebido": false
}

Possíveis Erros

Status / Código	Quando ocorre
400	ID ausente, conta não encontrada, ou conta já recebida.
401 NAO_AUTORIZADO	Conta pertence a outra empresa.
403	Usuário sem empresa vinculada.

Contas a Pagar

Controle de valores a pagar, sempre escopado à empresa do usuário autenticado. Estrutura análoga a Contas a Receber.

POST/contas-pagar

Token JWT Requerido

Cria uma conta a pagar (nasce sempre como 'pago: false').

Body (JSON)

Campo	Tipo	Descrição
descricao*	string	Mínimo 2 caracteres.
valor*	number	Positivo.
tipo*	string
data_vencimento*	string (data)	Formato YYYY-MM-DD.

Exemplo

request.json

{
  "descricao": "Aluguel escritório",
  "valor": 800.0,
  "tipo": "DESPESA_FIXA",
  "data_vencimento": "2026-07-05"
}

Resposta (201 Created)

201 Created response.json

{
  "id": "uuid", "empresa_id": "uuid", "descricao": "string", "valor": 800.0, "tipo": "string", "data_vencimento": "2026-07-05", "pago": false, "data_pagamento": null
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.

GET/contas-pagar

Token JWT Requerido

Lista as contas a pagar da empresa.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

[
  { "id": "uuid", "empresa_id": "uuid", "descricao": "string", "valor": 800.0, "data_vencimento": "2026-07-05", "pago": false }
]

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.

PATCH/contas-pagar/:id/pagar

Token JWT Requerido

Paga/baixa a conta: marca como paga e gera automaticamente o lançamento contábil de partida dobrada correspondente.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
valor_pago	number	Valor efetivamente pago, se diferente do valor previsto.

Exemplo

request.json

{
  "valor_pago": 800.0
}

Resposta (200 OK)

200 OK response.json

{
  "message": "Conta paga e lançamento contábil gerado!",
  "dados": { "...": "conta a pagar atualizada" }
}

Possíveis Erros

Status / Código	Quando ocorre
400	ID da conta ausente na URL.
403	Usuário sem empresa vinculada.

PUT/contas-pagar/:id

Token JWT Requerido

Atualiza dados de uma conta a pagar ainda não paga. Não é possível editar uma conta já paga.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
descricao	string
valor	number
tipo	string
data_vencimento	string (data)

Exemplo

request.json

{
  "valor": 850.0
}

Resposta (200 OK)

200 OK response.json

{
  "id": "uuid", "empresa_id": "uuid", "descricao": "string", "valor": 850.0, "pago": false
}

Possíveis Erros

Status / Código	Quando ocorre
400	ID ausente, conta não encontrada, ou conta já paga.
401 NAO_AUTORIZADO	Conta pertence a outra empresa.
403	Usuário sem empresa vinculada.

Relatórios

Relatórios contábeis gerados a partir dos lançamentos e plano de contas: DRE e Balanço Patrimonial.

GET/relatorios/dre

Token JWT Requerido

Gera a Demonstração do Resultado do Exercício (DRE): receitas e despesas agregadas por conta dentro de um período.

Query Params

Campo	Tipo	Descrição
dataInicio*	string	Formato YYYY-MM-DD.
dataFim*	string	Formato YYYY-MM-DD.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": {
    "empresaId": "uuid",
    "dataInicio": "2026-06-01T00:00:00.000Z",
    "dataFim": "2026-06-23T00:00:00.000Z",
    "receitas": [ { "codigo": "4.1.01", "nome": "Vendas", "saldo": 1500.0 } ],
    "despesas": [ { "codigo": "5.1.01", "nome": "Aluguel", "saldo": 800.0 } ],
    "totalReceitas": 1500.0,
    "totalDespesas": 800.0,
    "resultadoLiquido": 700.0
  }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário sem empresa vinculada, ou datas ausentes/inválidas.

GET/relatorios/balanco-patrimonial

Token JWT Requerido

Gera o Balanço Patrimonial na data base informada: saldos de Ativo, Passivo e Patrimônio Líquido (incluindo o Lucro/Prejuízo Acumulado do período), com auditoria de que Ativo = Passivo + PL.

Query Params

Campo	Tipo	Descrição
dataBase*	string	Formato YYYY-MM-DD.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": {
    "empresaId": "uuid",
    "dataBase": "2026-06-23T23:59:59.999Z",
    "ativos": [ { "codigo": "1.1.01", "nome": "Caixa", "saldo": 3000.0 } ],
    "passivos": [ { "codigo": "2.1.01", "nome": "Fornecedores", "saldo": 500.0 } ],
    "patrimonioLiquido": [ { "codigo": "3.9.99", "nome": "Lucro/Prejuízo Acumulado", "saldo": 700.0 } ],
    "totalAtivo": 3000.0,
    "totalPassivo": 500.0,
    "totalPL": 700.0,
    "equacaoValida": false
  }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário sem empresa vinculada, ou dataBase ausente/inválida.

Atenção

'equacaoValida' compara totalAtivo com (totalPassivo + totalPL) usando igualdade estrita — diferenças de arredondamento podem retornar false mesmo com contabilidade correta.

Dashboard

Indicadores agregados para a tela inicial do sistema: resumo financeiro, desempenho mensal, categorias de receita, movimentações recentes, pendências e fluxo de caixa.

GET/dashboard/resumo

Token JWT Requerido

Retorna um panorama consolidado da empresa no período: resumo financeiro, desempenho mensal anual, receita por categoria, movimentações recentes (últimas 10) e pendências operacionais.

Query Params

Campo	Tipo	Descrição
data_inicio	string (data)	Formato YYYY-MM-DD. Padrão: 30 dias atrás.
data_fim	string (data)	Formato YYYY-MM-DD. Padrão: hoje.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": {
    "resumo": "IResumoDashboard",
    "desempenhoAnual": "IDesempenhoMensal[]",
    "receitaPorCategoria": "IReceitaCategoria[]",
    "movimentacoesRecentes": "IMovimentacaoRecente[]",
    "pendenciasOperacionais": "IPendenciaOperacional[]"
  }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário sem empresa vinculada, ou datas em formato inválido.

GET/dashboard/fluxo-caixa

Token JWT Requerido

Retorna a série de fluxo de caixa (entradas/saídas) da empresa no período.

Query Params

Campo	Tipo	Descrição
data_inicio	string (data)	Formato YYYY-MM-DD. Padrão: 30 dias atrás.
data_fim	string (data)	Formato YYYY-MM-DD. Padrão: hoje.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [ { "data": "2026-06-01", "entradas": 1500.0, "saidas": 800.0 } ]
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Usuário sem empresa vinculada, ou datas em formato inválido.

Notas Fiscais

Anexo e consulta de notas fiscais/comprovantes vinculados a uma conta a pagar ou a receber, sempre escopados à empresa do usuário autenticado.

POST/notas-fiscais

Token JWT Requerido

Anexa uma nota fiscal a uma conta a pagar ou a receber. Rejeita nome de arquivo ou número de nota duplicados na mesma empresa.

Body (JSON)

Campo	Tipo	Descrição
tipo_referencia*	'conta_pagar'\|'conta_receber'
referencia_id*	string (UUID)	ID da conta a pagar/receber referenciada.
arquivo_url*	string (URL)
arquivo_nome*	string	Deve ser único na empresa.
numero_nota	string	Se informado, deve ser único na empresa.
emitida_em	string (data)

Exemplo

request.json

{
  "tipo_referencia": "conta_pagar",
  "referencia_id": "uuid",
  "arquivo_url": "https://.../nota.pdf",
  "arquivo_nome": "nota-123.pdf",
  "numero_nota": "123"
}

Resposta (201 Created)

201 Created response.json

{
  "id": "uuid", "empresa_id": "uuid", "tipo_referencia": "conta_pagar", "referencia_id": "uuid",
  "numero_nota": "string | null", "arquivo_url": "string", "arquivo_nome": "string", "emitida_em": "string | null"
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	arquivo_url/arquivo_nome ausentes, tipo_referencia inválido, ou nome/número de nota já cadastrado.

GET/notas-fiscais

Token JWT Requerido

Lista todas as notas fiscais da empresa do usuário autenticado.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

[
  { "id": "uuid", "empresa_id": "uuid", "tipo_referencia": "conta_pagar", "referencia_id": "uuid", "arquivo_url": "string", "arquivo_nome": "string" }
]

GET/notas-fiscais/referencia/:referencia_id

Token JWT Requerido

Lista as notas fiscais anexadas a uma conta a pagar/receber específica.

Parâmetros de Rota

Campo	Tipo	Descrição
referencia_id*	string (UUID)	ID da conta a pagar/receber.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

[
  { "id": "uuid", "empresa_id": "uuid", "tipo_referencia": "conta_receber", "referencia_id": "uuid", "arquivo_url": "string", "arquivo_nome": "string" }
]

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Alguma nota encontrada pertence a outra empresa (checagem de segurança contra referencia_id de outro tenant).

DELETE/notas-fiscais/:id

Token JWT Requerido

Remove uma nota fiscal da empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (204 No Content)

204 No Content response.json

(corpo vazio)

Possíveis Erros

Status / Código	Quando ocorre
401 NAO_AUTORIZADO	Nota pertence a outra empresa.
404	Nota fiscal não encontrada.

Cargos

Cadastro de cargos personalizados usados pela empresa (distintos do cargo de sistema DONO/CAIXA/GERENTE do usuário).

POST/cargos

Token JWT Requerido (cargo DONO)

Cria um novo cargo para a empresa do usuário autenticado.

Body (JSON)

Campo	Tipo	Descrição
nome*	string	Mínimo 2 caracteres.
descricao	string

Exemplo

request.json

{
  "nome": "Supervisor de Caixa",
  "descricao": "Responsável por conferir fechamentos de caixa"
}

Resposta (201 Created)

201 Created response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "nome": "string", "descricao": "string | undefined" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Nome ausente ou com menos de 2 caracteres.
403	Usuário sem empresa vinculada.

GET/cargos

Token JWT Requerido

Lista os cargos cadastrados na empresa do usuário autenticado.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": [ { "id": "uuid", "empresa_id": "uuid", "nome": "string", "descricao": "string | undefined" } ]
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.

PUT/cargos/:id

Token JWT Requerido (cargo DONO)

Atualiza nome e/ou descrição de um cargo da empresa.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Campo	Tipo	Descrição
nome	string	Mínimo 2 caracteres.
descricao	string

Exemplo

request.json

{
  "nome": "Supervisor Sênior"
}

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "data": { "id": "uuid", "empresa_id": "uuid", "nome": "string", "descricao": "string | undefined" }
}

Possíveis Erros

Status / Código	Quando ocorre
400 ENTRADA_INVALIDA	Nome informado com menos de 2 caracteres.
403	Usuário sem empresa vinculada.
404 NAO_ENCONTRADO	Cargo não encontrado.
401 NAO_AUTORIZADO	Cargo pertence a outra empresa.

DELETE/cargos/:id

Token JWT Requerido (cargo DONO)

Remove um cargo da empresa do usuário autenticado.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "status": "success",
  "message": "Cargo deletado com sucesso."
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.
404 NAO_ENCONTRADO	Cargo não encontrado.
401 NAO_AUTORIZADO	Cargo pertence a outra empresa.

Notificações

Notificações internas do sistema para a empresa do usuário autenticado.

GET/notificacoes

Token JWT Requerido

Lista as notificações da empresa e a contagem de não lidas.

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "notificacoes": [
    { "id": "uuid", "titulo": "string", "mensagem": "string", "lida": false, "data_criacao": "string" }
  ],
  "naoLidas": 3
}

Possíveis Erros

Status / Código	Quando ocorre
403	Usuário sem empresa vinculada.

PATCH/notificacoes/:id/lida

Token JWT Requerido

Marca uma notificação da empresa como lida.

Parâmetros de Rota

Campo	Tipo	Descrição
id*	string (UUID)

Body (JSON)

Sem corpo de requisição.

Resposta (200 OK)

200 OK response.json

{
  "id": "uuid",
  "titulo": "string",
  "lida": true
}

Possíveis Erros

Status / Código	Quando ocorre
400	Notificação não encontrada (ou pertence a outra empresa).
403	Usuário sem empresa vinculada.