📖 Casos de Uso - ecosif-querys¶
📋 Visão Geral¶
Este documento descreve os principais casos de uso do serviço ecosif-querys.
📦 Caso de Uso 1: Consultar Saldo de Conta¶
Descrição¶
Contador consulta o saldo de uma conta contábil para um período específico.
Atores¶
- Contador: Usuário que consulta saldos
- Sistema: Processa consulta e retorna dados
Pré-condições¶
- Usuário autenticado
- Usuário tem acesso à empresa/filial
- Período válido
Fluxo Principal¶
- Contador faz requisição via
POST /balanceInquiryDetails - Sistema valida token JWT
- Sistema valida acesso à empresa/filial
- Sistema consulta saldos mensais no banco
- Sistema calcula saldo inicial baseado no período
- Sistema retorna lista com saldos mensais
Fluxo Alternativo: Sem Acesso¶
- Sistema detecta falta de permissão
- Sistema retorna erro 403 Forbidden
📥 Caso de Uso 2: Consultar Razão Geral¶
Descrição¶
Analista consulta a razão geral (diário) de uma conta para análise.
Atores¶
- Analista: Usuário que consulta razão geral
- Sistema: Processa consulta e retorna dados
Pré-condições¶
- Usuário autenticado
- Usuário tem acesso à empresa/filial
- Conta existe
Fluxo Principal¶
- Analista faz requisição via
POST /generalLedgerQuery - Sistema valida token e acesso
- Sistema executa query com JOINs otimizados
- Sistema filtra por intervalo de dias (se informado)
- Sistema retorna lista de lançamentos ordenados
📊 Caso de Uso 3: Listar Plano de Contas¶
Descrição¶
Usuário visualiza o plano de contas completo de uma empresa/filial.
Atores¶
- Usuário: Qualquer usuário autenticado
- Sistema: Processa consulta e retorna dados
Pré-condições¶
- Usuário autenticado
- Usuário tem acesso à empresa/filial
- Plano de contas configurado
Fluxo Principal¶
- Usuário faz requisição via
GET /allChartOfAccount/{company}/{branch} - Sistema valida token e acesso
- Sistema busca plano de contas no banco
- Sistema ordena numericamente usando comparator
- Sistema retorna lista ordenada
🔌 Caso de Uso 4: Saldos da filial para integração¶
Descrição¶
Sistema externo consulta, de uma vez, o saldo analítico de todas as contas da filial em um mês ou em um dia. O período precisa estar consolidado no Moviments.
Atores¶
- Integrador: Sistema que consome a API com token JWT
- Sistema: Lê saldos já gravados e devolve o envelope SPARTS
Pré-condições¶
- Usuário autenticado com acesso à empresa/filial
- Plano de contas configurado na filial
- Consolidação do período já executada
Fluxo Principal¶
- Integrador chama
GET /sparts/saldos/mensalouGET /sparts/saldos/diario - Sistema valida competência, acesso e plano da filial
- Sistema lista só contas analíticas com movimento ou posição diferente de zero
- Sistema devolve
saldoInicial, movimentos esaldoFinalgravado
Fluxo Alternativo: Competência inválida¶
- Ano, mês, dia ou tamanho de página estão fora da faixa
- Sistema responde HTTP 400
Última Atualização: 2026-10-08