eCosif — Consultas

SPARTS — Integração Legada Itaú/Regente

Visão geral

O namespace SPARTS (/api/v1/sparts/**) expõe endpoints REST equivalentes às stored procedures do Regente/SQL Server usadas na integração com sistemas legados (Itaú).

Base URL: {host}/ecosif-querys/api/v1/sparts
Autenticação: JWT Bearer (Authorization: Bearer <token>)

Endpoint Procedure legada Descrição
GET /consulta-contabil spavs_ld_Consulta_Contabil Saldos das contas na maior data ≤ dataFim
GET /lancamentos-contabeis CT_P_LancamentosContabeis Lançamentos contábeis por período

Rota legada (redirect)

GET /api/v1/consulta-contabil → 301 → /api/v1/sparts/consulta-contabil (mesmos query params).

O endpoint GET /ecosif-reports/api/v1/lancamentos-contabeis está deprecated; use o SPARTS no ecosif-querys.

Autenticação

  1. Obter token: POST /ecosif-auth/api/auth/signin
  2. Enviar em todas as requisições:
Authorization: Bearer <accessToken>

O usuário JWT deve ter acesso à empresa/filial solicitada (gr_filial_usuario / grupos).

Formato de resposta

Todos os endpoints retornam:

{
  "status": 200,
  "mensagem": "",
  "elemento": {
    "linhas": [ ... ],
    "total_elementos": 100,
    "total_paginas": 10,
    "pagina_atual": 0,
    "tamanho_pagina": 10
  }
}

Nomenclatura JSON: campos no padrão SQL legado (snake_case), ex.: data_contabil, lancto_id, banco_dados.

Empresa/filial na saída: sempre 9 caracteres com zero à esquerda (000000001).

GET /consulta-contabil

Equivalente a spavs_ld_Consulta_Contabil.

Parâmetros

Parâmetro Obrigatório Procedure Descrição
empresa Sim @EMPRESA Código da empresa
filial Sim @Filial Código da filial
dataInicio Sim @DataI YYYY-MM-DD ou YYYYMMDD
dataFim Sim @DataF YYYY-MM-DD ou YYYYMMDD
tipoSaldo Sim @tiposald M ou 0 = mensal (CT_Plano_Saldo); D ou 1 = diário (CT_Plano_Saldo_Dia)
usuario Não @Usuario Auditoria; deve coincidir com o JWT
pagina Não — Página (default 0)
tamanho Não — Registros por página (default 100)
ordenarPor Não — cdcontabil, conta_id, saldoacumulado, etc.
direcao Não — ASC ou DESC

Lógica

Exemplo

curl -G "http://localhost/ecosif-querys/api/v1/sparts/consulta-contabil" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "empresa=1" \
  --data-urlencode "filial=1" \
  --data-urlencode "dataInicio=2025-01-01" \
  --data-urlencode "dataFim=2025-12-31" \
  --data-urlencode "tipoSaldo=M" \
  --data-urlencode "pagina=0" \
  --data-urlencode "tamanho=100"

Campos de linhas[]

Campo JSON Origem
conta_id CT_Plano.conta_id
tipo CT_Plano.tipo
cdreduzido CT_Plano.cdreduzido
cdcontabil CT_Plano.cdcontabil
descricao CT_Plano.descricao
nivel CT_Plano.nivel
indnatureza CT_Plano.indnatureza
empresa, filial 9 chars, padded
ano, mes, dia Período do saldo (dia null no mensal)
movdeb, movcred, movenc Movimentos
saldoacumulado, saldo06meses, saldo12meses Saldos

elemento.tipo_saldo: M ou D (tipo aplicado na consulta).

GET /lancamentos-contabeis

Equivalente a CT_P_LancamentosContabeis.

Parâmetros

Parâmetro Obrigatório Procedure Descrição
dataInicio Sim @DtInicio YYYY-MM-DD ou YYYYMMDD
dataFim Sim @DtFim YYYY-MM-DD ou YYYYMMDD
empresa Não @Empresa Filtra empresa (COALESCE)
filial Não @Filial Filtra filial (COALESCE)
usuario Não — Auditoria
pagina Não — Default 0
tamanho Não — Default 100
ordenarPor Não — data_contabil, valor, conta, lancto_id
direcao Não — ASC / DESC

Se empresa e filial forem informados, valida acesso do usuário.

Lógica (fiel à procedure)

Exemplo

curl -G "http://localhost/ecosif-querys/api/v1/sparts/lancamentos-contabeis" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "dataInicio=2025-01-01" \
  --data-urlencode "dataFim=2025-12-31" \
  --data-urlencode "empresa=1" \
  --data-urlencode "filial=1" \
  --data-urlencode "pagina=0" \
  --data-urlencode "tamanho=100"

Campos de linhas[]

Campo JSON Procedure original
empresa emp.empresa (9 chars)
fantasia LEFT(fantasia, 15)
cgc emp.cgc
cdhistorico lan.CdHistorico
lancto_id lan.Lancto_Id
debcre lan.DebCre
usuario LEFT(usu.usuario, 7)
docto_id LEFT(docto_id, 5)
status ISDATE(...) → 0/1
data_contabil ano.mes.diareferencia
valor lan.valor
banco_dados DB_NAME() → current_database()
conta pla.CdReduzido
contrapartida pla2.CdReduzido
historico lan.Historico
filial lote.filial (9 chars)
encerramento CASE indicador WHEN 2 THEN 1 ELSE 0

Códigos HTTP

Código Situação
200 Sucesso
301 Redirect rota legada consulta-contabil
400 Parâmetro inválido
401 Token ausente/inválido
403 Sem acesso à empresa/filial
404 Empresa/filial não encontrada
500 Erro interno

Testes

cd ecosif-querys
AUTH_URL=http://localhost:8080 QUERYS_URL=http://localhost:8081 ./scripts/test-login-and-api.sh

Swagger: {host}/ecosif-querys/swagger-ui.html → tag SPARTS.