📡 Lista Completa de Endpoints - ecosif-querys

📋 Visão Geral

Este documento lista todos os endpoints REST disponíveis no serviço ecosif-querys, especializado em consultas contábeis otimizadas.

Base URL: http://localhost:8081
Autenticação: JWT Bearer Token (obtido via ecosif-auth)

🏷️ Tags

Os endpoints estão organizados nas seguintes categorias:

SPARTS - Integração legada Itaú/Regente (procedures SQL Server)
Consultas de Saldo - Consultas de saldos de contas contábeis
Razão Geral - Consultas de razão geral (diário)
Plano de Contas - Consultas do plano de contas

Documentação SPARTS: integradores/sparts.md

🔌 SPARTS (Integração Legada)

Consulta Contábil — `spavs_ld_Consulta_Contabil`

Método: GET
URL: /api/v1/sparts/consulta-contabil
Parâmetros: empresa, filial, dataInicio, dataFim, tipoSaldo (M/0 ou D/1), pagina, tamanho
Response: RetornoGenerico com campos JSON em snake_case legado

Lançamentos Contábeis — `CT_P_LancamentosContabeis`

Método: GET
URL: /api/v1/sparts/lancamentos-contabeis
Parâmetros: dataInicio, dataFim, empresa (opc.), filial (opc.), pagina, tamanho
Response: RetornoGenerico — data_contabil formato YYYY.MM.DD, status 0/1

Redirect legado

Método: GET
URL: /api/v1/consulta-contabil → 301 → /api/v1/sparts/consulta-contabil

💰 Consultas de Saldo

Consultar Detalhes de Saldo

Método: POST
URL: /balanceInquiryDetails
Descrição: Retorna os detalhes de saldo de uma conta contábil para um período específico, incluindo movimentações de débito, crédito e saldos acumulados.
Autenticação: Obrigatória
Validação de Acesso: Verifica se usuário tem acesso à empresa/filial
Request Body: json { "contaId": 100, "empresa": "00001", "filial": "00001", "anomesini": "01/2025", "anomesfim": "11/2025", "comboType": "ALL" }
Validações:
contaId: Obrigatório (Long)
empresa: Obrigatório (String)
filial: Obrigatório (String)
anomesini: Obrigatório, formato MM/YYYY (ex: "01/2025")
anomesfim: Obrigatório, formato MM/YYYY (ex: "11/2025")
anomesini não pode ser maior que anomesfim
Response: 200 OK json [ { "year": "2025", "month": "01", "movdeb": 10000.00, "movcred": 5000.00, "movenc": 0.0, "accumulatedBalance": 15000.00, "openingBalance": 0.0 }, { "year": "2025", "month": "02", "movdeb": 5000.00, "movcred": 3000.00, "accumulatedBalance": 17000.00, "openingBalance": 0.0 } ]
Cálculo de Saldo Inicial:
Se anomesini é igual ao baseYearMonth da empresa: usa saldo inicial de Accountbalance
Caso contrário: usa saldo acumulado do mês anterior em MonthlyAccountBalance
Erros:
400 Bad Request - Dados inválidos, formato de data incorreto, range inválido
401 Unauthorized - Token ausente/inválido
403 Forbidden - Usuário não tem acesso à empresa/filial
404 Not Found - Empresa, filial ou conta não encontrada
500 Internal Server Error - Erro interno

📋 Razão Geral (Diário)

Consultar Razão Geral

Método: POST
URL: /generalLedgerQuery
Descrição: Retorna a razão geral (diário) de uma conta contábil para um período específico, com detalhamento dia a dia ou por intervalo de dias.
Autenticação: Obrigatória
Validação de Acesso: Verifica se usuário tem acesso à empresa/filial
Request Body: json { "contaId": 100, "empresa": "00001", "filial": "00001", "year": 2025, "month": 11, "dayStart": 1, "dayEnd": 30 }
Validações:
contaId: Obrigatório (Long)
empresa: Obrigatório (String)
filial: Obrigatório (String)
year: Obrigatório, entre 2000 e 9999 (int)
month: Obrigatório, entre 1 e 12 (int)
dayStart: Opcional, entre 1 e 31 (int)
dayEnd: Opcional, entre 1 e 31 (int)
Se dayStart e dayEnd forem informados, dayStart não pode ser maior que dayEnd
Response: 200 OK json [ { "lote": "001", "documento": "000001", "entry": "001", "debCre": "D", "day": "15", "history": "Lançamento teste", "value": "1000.00", "cdContabil": "1.1.01" }, { "lote": "001", "documento": "000001", "entry": "002", "debCre": "C", "day": "15", "history": "Contrapartida", "value": "1000.00", "cdContabil": "1.2.01" } ]
Campos da Resposta:
lote: Número do lote
documento: Número do documento
entry: Número do lançamento
debCre: Débito (D) ou Crédito (C)
day: Dia do lançamento
history: Histórico do lançamento
value: Valor do lançamento
cdContabil: Código contábil da conta
Filtros:
Se dayStart e dayEnd não forem informados (0), retorna todos os dias do mês
Se informados, filtra apenas lançamentos no intervalo de dias especificado
Erros:
400 Bad Request - Dados inválidos, range de dias inválido
401 Unauthorized - Token ausente/inválido
403 Forbidden - Usuário não tem acesso à empresa/filial
404 Not Found - Empresa, filial ou conta não encontrada
500 Internal Server Error - Erro interno

📊 Plano de Contas

Listar Plano de Contas

Método: GET
URL: /allChartOfAccount/{company}/{branch}
Descrição: Retorna o plano de contas completo para uma empresa/filial, ordenado numericamente de forma hierárquica.
Autenticação: Obrigatória
Validação de Acesso: Verifica se usuário tem acesso à empresa/filial
Parâmetros de Path:
company (String, obrigatório) - Código da empresa (ex: "00001")
branch (String, obrigatório) - Código da filial (ex: "00001")
Response: 200 OK json [ { "id": 1, "cdAccounting": "1", "cdReduced": "1" }, { "id": 2, "cdAccounting": "1.1", "cdReduced": "1.1" }, { "id": 3, "cdAccounting": "1.1.01", "cdReduced": "1.1.01" }, { "id": 4, "cdAccounting": "1.2", "cdReduced": "1.2" } ]
Ordenação:
Utiliza ChartOfAccountsComparator da biblioteca ecosif-database
Ordenação numérica (não alfabética)
Exemplo: "1.1" < "1.2" < "1.10" (não "1.10" < "1.2")
Validações:
Empresa e filial devem existir
Plano de contas deve estar configurado em CompanyOptions
Erros:
400 Bad Request - Códigos de empresa/filial inválidos, plano não configurado
401 Unauthorized - Token ausente/inválido
403 Forbidden - Usuário não tem acesso à empresa/filial
404 Not Found - Empresa ou filial não encontrada
500 Internal Server Error - Erro interno

🔐 Autenticação

Todos os endpoints requerem autenticação JWT.

Header necessário:

Authorization: Bearer <token>

Obter token: 1. Fazer login em ecosif-auth: POST /api/auth/signin 2. Copiar accessToken da resposta 3. Usar no header Authorization

🔒 Validação de Acesso

Todos os endpoints validam se o usuário autenticado tem permissão para acessar a empresa/filial solicitada através de:

Verificação em UserCompanyBranch (permissões diretas)
Verificação em grupos do usuário (permissões herdadas)

Erro 403 Forbidden: - Retornado quando usuário não tem acesso à empresa/filial - Mensagem: "Acesso negado - usuário não tem permissão para acessar esta empresa/filial"

📊 Códigos de Status HTTP

Código	Descrição
`200`	OK - Requisição bem-sucedida
`400`	Bad Request - Dados inválidos ou erro de validação
`401`	Unauthorized - Token ausente/inválido
`403`	Forbidden - Acesso negado (sem permissão para empresa/filial)
`404`	Not Found - Recurso não encontrado
`500`	Internal Server Error - Erro interno

📝 Notas Importantes

Formato de Data: Períodos devem estar no formato MM/YYYY (ex: "01/2025")
Saldo Inicial: - O saldo inicial é calculado automaticamente baseado no baseYearMonth da empresa - Se o período inicial é o mesmo que o baseYearMonth, usa saldo inicial de Accountbalance - Caso contrário, busca saldo acumulado do mês anterior
Ordenação de Contas: - Plano de contas é ordenado numericamente usando ChartOfAccountsComparator - Garante ordenação correta hierárquica (1.1 < 1.10)
Performance: - Endpoints otimizados para grandes volumes de dados - Queries utilizam índices apropriados - Resultados pagináveis para grandes datasets

Última Atualização: 2025-11-27