Pular para conteúdo

SPARTS — Integração Legada Itaú/Regente

Visão geral

O namespace SPARTS (/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/sparts
Autenticação: JWT Bearer (Authorization: Bearer <token>)

Endpoint Procedure legada Descrição
GET /saldos/mensal — Saldos analíticos do mês, no formato de integração
GET /saldos/diario — Saldos analíticos do dia, no formato de integraçã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 → /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: consulta-contabil e lancamentos-contabeis usam o padrão SQL legado (snake_case), ex.: data_contabil, lancto_id, banco_dados. As linhas de saldos/mensal e saldos/diario usam idEmpresa, idFilial, contaId, cdConta, cdReduzido, saldoInicial, movimentoDebito, movimentoCredito e saldoFinal. A paginação permanece em snake_case.

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


GET /saldos/mensal e GET /saldos/diario

Consulta de integração. Devolve só conta analítica (nrfilhos = 0) do plano da filial, com posição ou movimento diferente de zero. Conta sem saldo gravado e sem saldo anterior não aparece. O período precisa ter sido consolidado no Moviments.

saldoInicial é o saldoacumulado do mês anterior (no diário, do dia anterior com saldo). No mês-base da filial, se não houver período anterior, usa ct_plsaldos.saldoinicial. saldoFinal é o saldoacumulado gravado. Não é recalculado como inicial + débito − crédito: a consolidação acumula crédito − débito.

Cada linha traz idEmpresa, idFilial, ano, mes e, no diário, dia. Depois vêm contaId (id interno de ct_plano), cdConta (cdcontabil), cdReduzido e descricao. movimentoDebito é movdeb e movimentoCredito é movcred.

Parâmetro Obrigatório Descrição
empresa Sim Código da empresa. 1 também localiza 000000001
filial Sim Código da filial
ano Sim Ano, de 1900 a 9999
mes Sim Mês, de 1 a 12
dia Só no diário Dia válido do mês
pagina Não Página, começando em 0. Padrão 0
tamanho Não Itens por página, de 1 a 500. Padrão 100
curl -G "http://localhost/ecosif-querys/sparts/saldos/mensal" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "empresa=000000001" \
  --data-urlencode "filial=000000001" \
  --data-urlencode "ano=2025" \
  --data-urlencode "mes=12"

Cada item de elemento.linhas no mensal: idEmpresa, idFilial, ano, mes, contaId, cdConta, cdReduzido, descricao, saldoInicial, movimentoDebito, movimentoCredito, saldoFinal.

No diário, dia entra depois de mes. O restante da linha é o mesmo.

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

  • Join: CT_Plano, CT_Plano_Saldo ou CT_Plano_Saldo_Dia, CT_Calendario
  • Para cada conta: saldo na maior data ≤ dataFim dentro do intervalo [dataInicio, dataFim]
  • Plano filtrado por tipoPlano de CT_Controle da empresa/filial

Exemplo

curl -G "http://localhost/ecosif-querys/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)

  • Join: ct_lote → ct_documentos → ct_lancamento → ct_plano (conta + contrapartida), gr_empresa, gr_user
  • Filtros: diareferencia IS NOT NULL, data válida, intervalo BETWEEN
  • usuario: SUBSTRING(COALESCE(usuario, username), 1, 7)
  • docto_id: truncado em 5 caracteres
  • data_contabil: ano.mes.diareferencia (ex.: 2025.01.15)
  • status: 1 se data válida, 0 caso contrário
  • encerramento: 1 se indicador = '2', senão 0

Exemplo

curl -G "http://localhost/ecosif-querys/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.