Pular para conteúdo

📡 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: 
    {
  "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 
    [
  {
    "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: 
    {
  "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 
    [
  {
    "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 
    [
  {
    "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

  1. Formato de Data: Períodos devem estar no formato MM/YYYY (ex: "01/2025")

  2. Saldo Inicial:

  3. O saldo inicial é calculado automaticamente baseado no baseYearMonth da empresa
  4. Se o período inicial é o mesmo que o baseYearMonth, usa saldo inicial de Accountbalance

  5. Caso contrário, busca saldo acumulado do mês anterior

  6. Ordenação de Contas:

  7. Plano de contas é ordenado numericamente usando ChartOfAccountsComparator

  8. Garante ordenação correta hierárquica (1.1 < 1.10)

  9. Performance:

  10. Endpoints otimizados para grandes volumes de dados
  11. Queries utilizam índices apropriados
  12. Resultados pagináveis para grandes datasets

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