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¶
- Obter token:
POST /ecosif-auth/api/auth/signin - 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_SaldoouCT_Plano_Saldo_Dia,CT_Calendario - Para cada conta: saldo na maior data ≤ dataFim dentro do intervalo
[dataInicio, dataFim] - Plano filtrado por
tipoPlanodeCT_Controleda 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 caracteresdata_contabil:ano.mes.diareferencia(ex.:2025.01.15)status:1se data válida,0caso contrárioencerramento:1seindicador = '2', senão0
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.