Pular para conteúdo

📖 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

  1. Contador faz requisição via POST /balanceInquiryDetails
  2. Sistema valida token JWT
  3. Sistema valida acesso à empresa/filial
  4. Sistema consulta saldos mensais no banco
  5. Sistema calcula saldo inicial baseado no período
  6. Sistema retorna lista com saldos mensais

Fluxo Alternativo: Sem Acesso

  1. Sistema detecta falta de permissão
  2. 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

  1. Analista faz requisição via POST /generalLedgerQuery
  2. Sistema valida token e acesso
  3. Sistema executa query com JOINs otimizados
  4. Sistema filtra por intervalo de dias (se informado)
  5. 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

  1. Usuário faz requisição via GET /allChartOfAccount/{company}/{branch}
  2. Sistema valida token e acesso
  3. Sistema busca plano de contas no banco
  4. Sistema ordena numericamente usando comparator
  5. 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

  1. Integrador chama GET /sparts/saldos/mensal ou GET /sparts/saldos/diario
  2. Sistema valida competência, acesso e plano da filial
  3. Sistema lista só contas analíticas com movimento ou posição diferente de zero
  4. Sistema devolve saldoInicial, movimentos e saldoFinal gravado

Fluxo Alternativo: Competência inválida

  1. Ano, mês, dia ou tamanho de página estão fora da faixa
  2. Sistema responde HTTP 400

Última Atualização: 2026-10-08