openapi: 3.1.0
info:
  title: Bolsa Luís Andrade Barreira (BolsaLAB) Open Data API
  version: 1.0.0
  description: >
    Official, public-facing REST API for BolsaLAB — an independent cancer research fellowship
    fund hosted at i3S (Instituto de Investigação e Inovação em Saúde, University of Porto, NIPC: 501413197, ROR: https://ror.org/0352ybe83).
    Guarantees 100% direct-to-bench allocation with 0% administrative overhead, governed under Article 62-A of the Portuguese Estatuto dos Benefícios Fiscais (EBF).
  contact:
    name: BolsaLAB Governance & Engineering
    email: privacidade@bolsalab.org
    url: https://bolsalab.org/transparencia
  license:
    name: Creative Commons Attribution 4.0 International (CC BY 4.0)
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://bolsalab.org
    description: Production Server

paths:
  /api/stats:
    get:
      summary: Get Live Fellowship Statistics
      description: Returns real-time aggregate totals for raised funds, active donors, and laboratory bench hours funded.
      operationId: getLiveStats
      responses:
        '200':
          description: Successful response with real-time aggregated metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStats'

  /api/donors:
    get:
      summary: Get Public Donor Registry
      description: Returns the list of public donors who explicitly opted in to have their name listed in the solidarity registry.
      operationId: getPublicDonors
      responses:
        '200':
          description: List of public donors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  doadores:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublicDonor'

  /api/ledger:
    get:
      summary: Get Public General Ledger (Razão de Contas Aberto)
      description: >
        Exports itemized semi-annual general ledger transactions of the fellowship fund.
        Supports both JSON and CSV output. All records strictly comply with GDPR pseudonymization protocols.
      operationId: getPublicLedger
      parameters:
        - name: format
          in: query
          required: false
          description: Output format (json or csv). Defaults to json.
          schema:
            type: string
            enum: [json, csv]
            default: json
      responses:
        '200':
          description: Public ledger records in JSON or CSV format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  periodo:
                    type: string
                    example: "2026-S1"
                  total_entradas:
                    type: number
                    example: 24500.00
                  total_saidas:
                    type: number
                    example: 22050.00
                  saldo_caucionado:
                    type: number
                    example: 2450.00
                  transacoes:
                    type: array
                    items:
                      $ref: '#/components/schemas/LedgerEntry'
            text/csv:
              schema:
                type: string
                description: Comma-separated CSV ledger entries.

components:
  schemas:
    LiveStats:
      type: object
      properties:
        total_angariado:
          type: number
          description: Total euros raised in the fund.
          example: 24500.00
        horas_financiadas:
          type: number
          description: Total laboratory bench hours generated at ~10€ per bench hour (0.1h/€/year).
          example: 2450
        doadores_ativos:
          type: integer
          description: Total count of unique active donors.
          example: 182
        bolsas_atribuidas:
          type: integer
          description: Number of research fellowships awarded.
          example: 0
        proxima_bolsa_meta:
          type: number
          description: Funding goal for the next full annual research grant.
          example: 30000.00

    PublicDonor:
      type: object
      properties:
        nome:
          type: string
          example: "Maria S."
        data:
          type: string
          format: date-time
          example: "2026-10-29T10:00:00Z"
        escalao:
          type: string
          example: "Aliado da Bancada"

    LedgerEntry:
      type: object
      properties:
        id:
          type: string
          example: "TX-2026-001"
        data:
          type: string
          format: date
          example: "2026-10-29"
        tipo:
          type: string
          enum: [entrada, saida]
          example: "entrada"
        descricao:
          type: string
          example: "Donativo Regular de Mecenato"
        montante:
          type: number
          example: 120.00
        horas_equivalentes:
          type: number
          example: 108.0
        entidade:
          type: string
          example: "i3S – Conta Caucionada (NIPC: 501413197)"
        rubrica:
          type: string
          example: "Bolsa de Investigação em Oncologia"