openapi: 3.0.3
info:
  title: eCosif Querys API
  description: |
    API para consultas otimizadas de dados contábeis do sistema eCosif.
    
    Este serviço especializado fornece:
    - **Consultas de Saldo**: Detalhes de saldos de contas contábeis por período
    - **Razão Geral (Diário)**: Consulta detalhada de movimentações dia a dia
    - **Plano de Contas**: Listagem hierárquica do plano de contas
    
    ## 🔐 Autenticação
    
    **IMPORTANTE**: Este serviço requer autenticação JWT.
    
    ### Como obter o token:
    1. Faça login no **ecosif-auth** (porta 8080): `POST /api/auth/signin`
    2. Copie o `accessToken` retornado
    3. Clique no botão **'Authorize'** 🔒 no topo desta página
    4. Digite: `Bearer <seu-token>`
    5. Clique em **'Authorize'**
    6. Agora você pode testar todos os endpoints
    
    ## 🔒 Validação de Acesso
    
    Todos os endpoints validam se o usuário autenticado tem **permissão para acessar** a empresa/filial solicitada através de:
    - Permissões diretas em `UserCompanyBranch`
    - Permissões herdadas de grupos do usuário
    
  version: 0.7.05.202606173
  contact:
    name: eCosif Team
    email: support@ecosif.net.br
    url: https://www.ecosif.net.br
  license:
    name: Commercial License
    url: https://www.ecosif.net.br/licenses/

servers:
  - url: http://localhost:8081
    description: Servidor de Desenvolvimento
  - url: https://api.ecosig.com.br/querys
    description: Servidor de Produção

tags:
  - name: Consultas de Saldo
    description: Consultas de saldos de contas contábeis
  - name: Razão Geral
    description: Consultas de razão geral (diário)
  - name: Plano de Contas
    description: Consultas do plano de contas

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtido através do ecosif-auth (porta 8080). Formato: Bearer <token>

  schemas:
    BalanceInquiryRequestDTO:
      type: object
      required:
        - contaId
        - empresa
        - filial
        - anomesini
        - anomesfim
      properties:
        contaId:
          type: integer
          format: int64
          description: ID da conta contábil
          example: 100
        empresa:
          type: string
          description: Código da empresa
          example: "00001"
        filial:
          type: string
          description: Código da filial
          example: "00001"
        anomesini:
          type: string
          pattern: "^(0[1-9]|1[0-2])/[0-9]{4}$"
          description: Ano/mês inicial no formato MM/YYYY
          example: "01/2025"
        anomesfim:
          type: string
          pattern: "^(0[1-9]|1[0-2])/[0-9]{4}$"
          description: Ano/mês final no formato MM/YYYY
          example: "11/2025"
        comboType:
          type: string
          description: Tipo de combinação
          example: "ALL"
    
    BalanceInquiryResponseDTO:
      type: object
      properties:
        year:
          type: string
          example: "2025"
        month:
          type: string
          example: "01"
        movdeb:
          type: number
          format: double
          description: Total de movimentações de débito
          example: 10000.00
        movcred:
          type: number
          format: double
          description: Total de movimentações de crédito
          example: 5000.00
        movenc:
          type: number
          format: double
          description: Movimentações de encerramento
          example: 0.0
        accumulatedBalance:
          type: number
          format: double
          description: Saldo acumulado
          example: 15000.00
        openingBalance:
          type: number
          format: double
          description: Saldo de abertura
          example: 0.0
    
    GeneralLedgerQueryRequestDTO:
      type: object
      required:
        - contaId
        - empresa
        - filial
        - year
        - month
      properties:
        contaId:
          type: integer
          format: int64
          description: ID da conta contábil
          example: 100
        empresa:
          type: string
          description: Código da empresa
          example: "00001"
        filial:
          type: string
          description: Código da filial
          example: "00001"
        year:
          type: integer
          minimum: 2000
          maximum: 9999
          description: Ano da consulta
          example: 2025
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: Mês da consulta (1-12)
          example: 11
        dayStart:
          type: integer
          minimum: 1
          maximum: 31
          description: Dia inicial da consulta (1-31), opcional
          example: 1
        dayEnd:
          type: integer
          minimum: 1
          maximum: 31
          description: Dia final da consulta (1-31), opcional
          example: 30
    
    GeneralLedgerQueryResponseDTO:
      type: object
      properties:
        lote:
          type: string
          example: "001"
        documento:
          type: string
          example: "000001"
        entry:
          type: string
          example: "001"
        debCre:
          type: string
          enum: [D, C]
          example: "D"
        day:
          type: string
          example: "15"
        history:
          type: string
          example: "Lançamento teste"
        value:
          type: string
          example: "1000.00"
        cdContabil:
          type: string
          example: "1.1.01"
    
    ChartOfAccountsDTO:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        cdAccounting:
          type: string
          description: Código contábil completo
          example: "1.1.01"
        cdReduced:
          type: string
          description: Código reduzido
          example: "1.1.01"
    
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
        error:
          type: string

security:
  - bearerAuth: []

paths:
  /balanceInquiryDetails:
    post:
      tags:
        - Consultas de Saldo
      summary: Consultar detalhes de saldo
      description: |
        Retorna os detalhes de saldo de uma conta contábil para um período específico.
        
        Inclui:
        - Movimentações de débito e crédito por mês
        - Saldo acumulado
        - Saldo de abertura (calculado automaticamente)
        
        O saldo inicial é calculado baseado no `baseYearMonth` da empresa:
        - Se `anomesini` = `baseYearMonth`: usa saldo inicial de `Accountbalance`
        - Caso contrário: usa saldo acumulado do mês anterior em `MonthlyAccountBalance`
      operationId: getBalanceInquiryDetails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceInquiryRequestDTO'
      responses:
        '200':
          description: Consulta realizada com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BalanceInquiryResponseDTO'
        '400':
          description: Dados inválidos ou erro de validação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Não autenticado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Acesso negado - usuário não tem permissão para acessar esta empresa/filial
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Empresa, filial ou conta não encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erro interno do servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /generalLedgerQuery:
    post:
      tags:
        - Razão Geral
      summary: Consultar razão geral (diário)
      description: |
        Retorna a razão geral (diário) de uma conta contábil para um período específico.
        
        Permite filtrar por intervalo de dias:
        - Se `dayStart` e `dayEnd` não forem informados (0): retorna todos os dias do mês
        - Se informados: filtra apenas lançamentos no intervalo especificado
        
        Retorna detalhamento de:
        - Lote, documento e lançamento
        - Tipo (débito/crédito)
        - Dia, histórico e valor
        - Código contábil
      operationId: getGeneralLedgerQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneralLedgerQueryRequestDTO'
      responses:
        '200':
          description: Consulta realizada com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeneralLedgerQueryResponseDTO'
        '400':
          description: Dados inválidos ou erro de validação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Não autenticado
        '403':
          description: Acesso negado - usuário não tem permissão para acessar esta empresa/filial
        '404':
          description: Empresa, filial ou conta não encontrada

  /allChartOfAccount/{company}/{branch}:
    get:
      tags:
        - Plano de Contas
      summary: Listar plano de contas
      description: |
        Retorna o plano de contas completo para uma empresa/filial.
        
        Características:
        - Ordenação numérica hierárquica (não alfabética)
        - Utiliza `ChartOfAccountsComparator` para garantir ordenação correta
        - Exemplo: "1.1" < "1.2" < "1.10" (não "1.10" < "1.2")
        
        O plano de contas deve estar configurado em `CompanyOptions`.
      operationId: getAllChartOfAccount
      parameters:
        - name: company
          in: path
          required: true
          schema:
            type: string
          description: Código da empresa
          example: "00001"
        - name: branch
          in: path
          required: true
          schema:
            type: string
          description: Código da filial
          example: "00001"
      responses:
        '200':
          description: Lista retornada com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChartOfAccountsDTO'
        '400':
          description: Códigos inválidos ou plano não configurado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Não autenticado
        '403':
          description: Acesso negado - usuário não tem permissão para acessar esta empresa/filial
        '404':
          description: Empresa ou filial não encontrada