openapi: 3.1.0
info:
  title: InvestMoz API
  version: 1.0.0
  summary: Contrato consolidado da API do InvestMoz
  description: |
    Contrato consolidado para catálogos, oportunidades, manifestações de interesse,
    simulações, legislação, jobs, relatórios e administração. Valores de taxas,
    reduções e parâmetros de simulação são fornecidos pelo utilizador; não são
    taxas oficiais nem decisões de elegibilidade.
  contact:
    name: Equipa InvestMoz
  license:
    name: MIT
    identifier: MIT
servers:
  - url: /
    description: Mesmo host da aplicação
security:
  - sessionCookie: []
tags:
  - name: Catálogos
    description: Referências versionadas, estáveis e localizadas em pt-MZ.
  - name: Oportunidades
    description: Consulta pública de oportunidades de investimento.
  - name: Manifestações
    description: Submissão de interesse em oportunidades.
  - name: Simulações
    description: Execuções indicativas com snapshots e controlo de concorrência.
  - name: Jobs
    description: Estado dos trabalhos assíncronos associados a uma simulação.
  - name: Relatórios
    description: Leitura de snapshots imutáveis de relatórios.
  - name: Legislação
    description: Fontes legais publicadas e versionadas.
  - name: Administração
    description: Operações administrativas protegidas por sessão e autorização.
paths:
  /api/v1/catalogs/{catalog}:
    get:
      tags: [Catálogos]
      operationId: listReferenceCatalog
      summary: Consultar catálogo versionado
      security: []
      parameters:
        - $ref: '#/components/parameters/CatalogName'
        - $ref: '#/components/parameters/Version'
        - $ref: '#/components/parameters/CatalogType'
        - $ref: '#/components/parameters/ParentId'
        - $ref: '#/components/parameters/JurisdictionId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Página do catálogo na versão solicitada
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CatalogPage'}
        '404': {$ref: '#/components/responses/NotFound'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/questionnaires/{code}:
    get:
      tags: [Simulações]
      operationId: getPublishedQuestionnaire
      summary: Consultar questionário publicado e versão imutável
      security: []
      parameters:
        - $ref: '#/components/parameters/QuestionnaireCode'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Questionário publicado em pt-MZ
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/QuestionnaireResponse'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/simulations:
    post:
      tags: [Simulações]
      operationId: createSimulation
      summary: Criar simulação rastreável
      description: Requer Idempotency-Key. Acesso anónimo requer token opaco gerado pelo cliente.
      x-implementation-status: implemented
      security:
        - sessionCookie: []
        - {}
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/SimulationToken'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SimulationInput'}
            examples:
              BoundaryValues:
                summary: Exemplo técnico nos limites mínimos
                description: Valores mínimos para demonstrar a forma do payload; não são valores fiscais recomendados.
                value: {base: 0, rate: 0, reduction: 0}
      responses:
        '202':
          description: Simulação aceite para processamento
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            Location: {$ref: '#/components/headers/Location'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SimulationAccepted'}
        '200':
          description: Repetição idempotente da resposta original
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SimulationAccepted'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/Conflict'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '428': {$ref: '#/components/responses/PreconditionRequired'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/simulations/{id}:
    get:
      tags: [Simulações]
      operationId: getSimulation
      summary: Consultar simulação, cenários e estado de execução
      x-implementation-status: implemented
      security:
        - sessionCookie: []
        - {}
      parameters:
        - $ref: '#/components/parameters/SimulationId'
        - $ref: '#/components/parameters/SimulationToken'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Simulação dentro do âmbito autorizado
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SimulationResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/simulations/{id}/scenarios/{scenarioId}:
    patch:
      tags: [Simulações]
      operationId: updateSimulationScenario
      summary: Actualizar cenário com controlo optimista de concorrência
      x-implementation-status: implemented
      security:
        - sessionCookie: []
        - {}
      parameters:
        - $ref: '#/components/parameters/SimulationId'
        - $ref: '#/components/parameters/ScenarioId'
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/SimulationToken'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UpdateScenarioInput'}
      responses:
        '202':
          description: Alteração aceite e reexecução colocada em fila
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Scenario'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '412': {$ref: '#/components/responses/PreconditionFailed'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '428': {$ref: '#/components/responses/PreconditionRequired'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/simulations/{id}/jobs:
    get:
      tags: [Jobs]
      operationId: listSimulationJobs
      summary: Consultar jobs de execução e geração de relatórios
      description: Contrato reservado para consulta dos jobs associados à simulação.
      x-implementation-status: contract-only
      security:
        - sessionCookie: []
        - {}
      parameters:
        - $ref: '#/components/parameters/SimulationId'
        - $ref: '#/components/parameters/SimulationToken'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Jobs visíveis no âmbito autorizado
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/JobCollection'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/simulations/{id}/reports/{reportId}:
    get:
      tags: [Relatórios]
      operationId: getSimulationReport
      summary: Obter snapshot imutável de relatório
      x-implementation-status: implemented
      security:
        - sessionCookie: []
        - {}
      parameters:
        - $ref: '#/components/parameters/SimulationId'
        - $ref: '#/components/parameters/ReportId'
        - $ref: '#/components/parameters/SimulationToken'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Snapshot e hash do relatório
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/legislation/sources:
    get:
      tags: [Legislação]
      operationId: listLegislationSources
      summary: Consultar fontes legais publicadas e versionadas
      description: Contrato reservado para catálogo público de fontes; administração usa a API v2 existente.
      x-implementation-status: contract-only
      security: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Fontes legais publicadas
          headers:
            ETag: {$ref: '#/components/headers/ETag'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/LegislationPage'}
        '404': {$ref: '#/components/responses/NotFound'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v2/investment/admin/legal-sources:
    get:
      tags: [Administração, Legislação]
      operationId: adminListLegalSources
      summary: Listar fontes legais para administração
      x-implementation-status: implemented
      security: [{sessionCookie: []}]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Lista de fontes legais
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AdminLegalSourcePage'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
    post:
      tags: [Administração, Legislação]
      operationId: adminCreateLegalSource
      summary: Registar fonte legal para validação
      x-implementation-status: implemented
      security: [{sessionCookie: []}]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LegalSourceInput'}
      responses:
        '201':
          description: Fonte legal registada
          headers:
            Location: {$ref: '#/components/headers/Location'}
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/LegalSource'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/Conflict'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v2/investment/admin/legal-sources/{id}/{action}:
    post:
      tags: [Administração, Legislação]
      operationId: adminTransitionLegalSource
      summary: Validar ou revogar uma fonte legal
      x-implementation-status: implemented
      security: [{sessionCookie: []}]
      parameters:
        - $ref: '#/components/parameters/SourceId'
        - name: action
          in: path
          required: true
          schema: {type: string, enum: [validate, revoke]}
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LegalSourceTransitionInput'}
      responses:
        '200':
          description: Estado actualizado
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/LegalSource'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '409': {$ref: '#/components/responses/Conflict'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/interest-requests:
    post:
      tags: [Manifestações]
      operationId: submitInterestRequest
      summary: Submeter manifestação de interesse
      x-implementation-status: implemented
      security: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyOptional'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/InterestRequestInput'}
      responses:
        '201':
          description: Manifestação submetida
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/InterestRequestResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/Conflict'}
        '422': {$ref: '#/components/responses/ValidationError'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/opportunities/{slug}:
    get:
      tags: [Oportunidades]
      operationId: getOpportunity
      summary: Consultar oportunidade publicada
      x-implementation-status: implemented
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          schema: {type: string, minLength: 1, maxLength: 180}
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Oportunidade publicada
          headers:
            X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OpportunityResponse'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/ServerError'}
components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: laravel-session
      description: Sessão Laravel; o nome pode ser substituído por SESSION_COOKIE. Rotas públicas e simulações anónimas substituem explicitamente este requisito.
  parameters:
    CatalogName:
      name: catalog
      in: path
      required: true
      schema: {type: string, enum: [authorities, jurisdictions, economic-activities]}
    Version:
      name: version
      in: query
      required: false
      description: Versão estável publicada do catálogo
      schema: {type: integer, minimum: 1}
    CatalogType:
      name: type
      in: query
      required: false
      description: Obrigatório para jurisdictions.
      schema: {type: string, enum: [country, province, district, admin_post, locality]}
    ParentId:
      name: parent_id
      in: query
      schema: {type: string, format: uuid}
    JurisdictionId:
      name: jurisdiction_id
      in: query
      schema: {type: string, format: uuid}
    Page:
      name: page
      in: query
      schema: {type: integer, minimum: 1, default: 1}
    PerPage:
      name: per_page
      in: query
      schema: {type: integer, minimum: 1, maximum: 100, default: 20}
    Search:
      name: q
      in: query
      schema: {type: string, maxLength: 100}
    QuestionnaireCode:
      name: code
      in: path
      required: true
      schema: {type: string, pattern: '^[a-z0-9][a-z0-9-]{0,79}$'}
    SimulationId:
      name: id
      in: path
      required: true
      schema: {type: string, format: uuid}
    ScenarioId:
      name: scenarioId
      in: path
      required: true
      schema: {type: string, format: uuid}
    ReportId:
      name: reportId
      in: path
      required: true
      schema: {type: string, format: uuid}
    SourceId:
      name: id
      in: path
      required: true
      schema: {type: string, format: uuid}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Repetições com a mesma chave e payload devolvem a resposta original; payload diferente produz conflito.
      schema: {type: string, minLength: 16, maxLength: 128}
    IdempotencyKeyOptional:
      name: Idempotency-Key
      in: header
      required: false
      description: Se fornecida, deve ser UUID; uma chave repetida com outro payload produz conflito.
      schema: {type: string, format: uuid}
    SimulationToken:
      name: X-Simulation-Token
      in: header
      required: false
      description: Obrigatório para acesso anónimo; token opaco do cliente, guardado apenas como hash.
      schema: {type: string, minLength: 32, maxLength: 256}
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: ETag forte da representação lida previamente.
      schema: {type: string, minLength: 1, maxLength: 128}
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      description: UUID opcional propagado pela aplicação; quando ausente, a aplicação cria um identificador.
      schema: {type: string, format: uuid}
  headers:
    ETag:
      description: Validador da representação; usado com If-Match em alterações concorrentes.
      schema: {type: string}
    Location:
      description: URI relativa do recurso criado ou aceite.
      schema: {type: string, format: uri-reference}
    RetryAfter:
      description: Segundos até à próxima tentativa.
      schema: {type: integer, minimum: 0}
    CorrelationId:
      description: Identificador de correlação da operação.
      schema: {type: string, format: uuid}
  responses:
    Unauthorized:
      description: Autenticação necessária ou sessão inválida
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
    Forbidden:
      description: Actor autenticado sem autorização para a operação
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
    NotFound:
      description: Recurso inexistente ou fora do âmbito visível
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
    Conflict:
      description: Conflito de estado, versão ou chave idempotente
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Problem'}
          example: {message: A chave foi reutilizada com conteúdo diferente., code: idempotency_conflict}
    PreconditionFailed:
      description: If-Match não corresponde ao ETag actual
      headers:
        ETag: {$ref: '#/components/headers/ETag'}
        X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Problem'}
          example: {message: A representação mudou; volte a consultar o recurso., code: stale_etag}
    ValidationError:
      description: Dados inválidos
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/ValidationProblem'}}}
    RateLimited:
      description: Limite de pedidos excedido
      headers:
        Retry-After: {$ref: '#/components/headers/RetryAfter'}
        X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
    ServerError:
      description: Erro interno; resposta não contém detalhes sensíveis
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
    PreconditionRequired:
      description: Header obrigatório em falta, como If-Match ou Idempotency-Key
      headers: {X-Correlation-ID: {$ref: '#/components/headers/CorrelationId'}}
      content: {application/json: {schema: {$ref: '#/components/schemas/Problem'}}}
  schemas:
    Problem:
      type: object
      required: [message]
      properties:
        message: {type: string}
        code: {type: string}
        correlation_id: {type: string, format: uuid}
      additionalProperties: true
    ValidationProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            errors:
              type: object
              additionalProperties:
                type: array
                items: {type: string}
    CatalogItem:
      type: object
      required: [id, value, code, name, label, locale, version_no]
      properties:
        id: {type: string, format: uuid}
        value: {type: string}
        code: {type: string}
        name: {type: string, description: Rótulo apresentado em português de Moçambique.}
        label: {type: string}
        locale: {type: string, const: pt-MZ}
        parent_id: {type: [string, 'null']}
        type: {type: [string, 'null'], enum: [country, province, district, admin_post, locality, 'null']}
        authority_type: {type: [string, 'null']}
        organization_id: {type: [string, 'null'], format: uuid}
        jurisdiction_id: {type: [string, 'null'], format: uuid}
        jurisdiction_name: {type: [string, 'null']}
        source_code: {type: [string, 'null']}
        sector_id: {type: [string, 'null']}
        version_no: {type: integer}
    CatalogPage:
      type: object
      required: [data, meta]
      properties:
        data: {type: array, items: {$ref: '#/components/schemas/CatalogItem'}}
        links:
          type: object
          properties:
            next: {type: [string, 'null'], format: uri-reference}
            previous: {type: [string, 'null'], format: uri-reference}
        next_page_url: {type: [string, 'null'], format: uri-reference}
        prev_page_url: {type: [string, 'null'], format: uri-reference}
        current_page: {type: integer}
        per_page: {type: integer}
        total: {type: integer}
        last_page: {type: integer}
        meta:
          allOf:
            - $ref: '#/components/schemas/Pagination'
            - type: object
              properties:
                catalog: {type: string}
                version: {type: [integer, 'null']}
                locale: {type: string, const: pt-MZ}
                source_version: {type: [string, 'null']}
                status: {type: string, enum: [published, not_published]}
    Pagination:
      type: object
      required: [current_page, per_page, total]
      properties:
        current_page: {type: integer, minimum: 1}
        per_page: {type: integer, minimum: 1}
        total: {type: integer, minimum: 0}
        version: {type: string}
    QuestionnaireResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [id, code, version_no, locale, schema_snapshot, status]
          properties:
            id: {type: string, format: uuid}
            code: {type: string}
            version_no: {type: integer, minimum: 1}
            locale: {type: string, const: pt-MZ}
            schema_snapshot: {type: object, additionalProperties: true}
            status: {type: string, const: published}
            valid_from: {type: [string, 'null'], format: date}
            valid_to: {type: [string, 'null'], format: date}
    SimulationInput:
      type: object
      required: [base, rate]
      properties:
        base: {type: number, minimum: 0, description: Valor de entrada sem moeda inferida.}
        rate: {type: number, minimum: 0, maximum: 100, description: Parâmetro fornecido pelo utilizador; não representa taxa oficial.}
        reduction: {type: number, minimum: 0, maximum: 100, default: 0}
        organization_id: {type: [string, 'null'], format: uuid}
      additionalProperties: false
    UpdateScenarioInput:
      type: object
      required: [label, base, rate]
      properties:
        label: {type: string, minLength: 1, maxLength: 100}
        base: {type: number, minimum: 0}
        rate: {type: number, minimum: 0, maximum: 100}
        reduction: {type: number, minimum: 0, maximum: 100, default: 0}
      additionalProperties: false
    SimulationAccepted:
      type: object
      required: [data, replayed]
      properties:
        data: {$ref: '#/components/schemas/Simulation'}
        replayed: {type: boolean}
        access_token: {type: string, minLength: 32, maxLength: 256, description: Devolvido apenas para execução anónima.}
    SimulationResponse:
      type: object
      required: [data]
      properties:
        data: {$ref: '#/components/schemas/Simulation'}
    Simulation:
      type: object
      required: [id, status, version_no, created_at, updated_at]
      properties:
        id: {type: string, format: uuid}
        questionnaire_version_id: {type: [string, 'null'], format: uuid}
        organization_id: {type: [string, 'null'], format: uuid}
        version_no: {type: integer, minimum: 1}
        status: {type: string, enum: [queued, running, completed, failed, cancelled]}
        input_snapshot: {type: object, additionalProperties: true}
        result_snapshot: {type: [object, 'null'], additionalProperties: true}
        calculation_snapshot: {type: [object, 'null'], additionalProperties: true}
        scenarios: {type: array, items: {$ref: '#/components/schemas/Scenario'}}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
    Scenario:
      type: object
      required: [id, code, label, version_no, parameters]
      properties:
        id: {type: string, format: uuid}
        code: {type: string}
        label: {type: string}
        version_no: {type: integer, minimum: 1}
        parameters: {type: object, additionalProperties: true}
    JobCollection:
      type: object
      required: [data]
      properties:
        data: {type: array, items: {$ref: '#/components/schemas/SimulationJob'}}
    SimulationJob:
      type: object
      required: [id, simulation_id, job_type, status, attempts, available_at]
      properties:
        id: {type: string, format: uuid}
        simulation_id: {type: string, format: uuid}
        job_type: {type: string, enum: [execute, report]}
        status: {type: string, enum: [pending, running, succeeded, failed]}
        attempts: {type: integer, minimum: 0, maximum: 3}
        available_at: {type: string, format: date-time}
        started_at: {type: [string, 'null'], format: date-time}
        finished_at: {type: [string, 'null'], format: date-time}
        error_code: {type: [string, 'null']}
    ReportResponse:
      type: object
      required: [data]
      properties:
        data: {$ref: '#/components/schemas/SimulationReport'}
    SimulationReport:
      type: object
      required: [id, simulation_id, version_no, status]
      properties:
        id: {type: string, format: uuid}
        simulation_id: {type: string, format: uuid}
        version_no: {type: integer, minimum: 1}
        status: {type: string, enum: [queued, ready, failed]}
        report_snapshot: {type: [object, 'null'], additionalProperties: true}
        report_sha256: {type: [string, 'null'], pattern: '^[0-9a-f]{64}$'}
    LegislationPage:
      type: object
      required: [data, meta]
      properties:
        data: {type: array, items: {$ref: '#/components/schemas/LegalSource'}}
        meta: {$ref: '#/components/schemas/Pagination'}
    AdminLegalSourcePage:
      type: object
      required: [data]
      properties:
        data: {type: array, items: {$ref: '#/components/schemas/LegalSource'}}
        current_page: {type: integer}
        per_page: {type: integer}
        total: {type: integer}
        last_page: {type: integer}
        first_page_url: {type: [string, 'null'], format: uri-reference}
        last_page_url: {type: [string, 'null'], format: uri-reference}
        next_page_url: {type: [string, 'null'], format: uri-reference}
        prev_page_url: {type: [string, 'null'], format: uri-reference}
    LegalSourceInput:
      type: object
      required: [title, url, diploma, article, competent_entity, valid_from]
      properties:
        title: {type: string, minLength: 1, maxLength: 255}
        url: {type: string, format: uri, pattern: '^https://', maxLength: 2000}
        diploma: {type: string, maxLength: 255}
        article: {type: string, maxLength: 255}
        competent_entity: {type: string, maxLength: 255}
        valid_from: {type: string, format: date}
        valid_until: {type: [string, 'null'], format: date}
      additionalProperties: false
    LegalSourceTransitionInput:
      type: object
      required: [version_no]
      properties:
        version_no: {type: integer, minimum: 1}
      additionalProperties: false
    LegalSource:
      type: object
      properties:
        id: {type: string, format: uuid}
        title: {type: string}
        url: {type: string, format: uri}
        diploma: {type: string}
        article: {type: string}
        competent_entity: {type: string}
        validation_status: {type: string, enum: [pending, validated, revoked]}
        version_no: {type: integer}
        valid_until: {type: [string, 'null'], format: date}
        validator_id: {type: [integer, 'null']}
        validated_at: {type: [string, 'null'], format: date-time}
        valid_from: {type: [string, 'null'], format: date}
    InterestRequestInput:
      type: object
      required: [fullName, email, investorType, country, sectorInterest, message, privacyConsent]
      properties:
        fullName: {type: string, minLength: 3, maxLength: 150, writeOnly: true}
        email: {type: string, format: email, maxLength: 150, writeOnly: true}
        phone: {type: [string, 'null'], maxLength: 30, writeOnly: true}
        investorType: {type: string, enum: [individual, empresa, fundo, entidade_publica, outro]}
        country: {type: string, maxLength: 100}
        sectorInterest: {type: string, maxLength: 150}
        opportunityReference: {type: [string, 'null'], maxLength: 80}
        existingBusinessId: {type: [string, 'null'], format: uuid}
        modality: {type: [string, 'null'], maxLength: 50}
        investmentRange: {type: [string, 'null'], maxLength: 80}
        message: {type: string, minLength: 20, maxLength: 2000, writeOnly: true}
        privacyConsent: {type: boolean, const: true}
        shareWithProponent: {type: boolean, default: false}
      additionalProperties: false
      not:
        allOf:
          - required: [opportunityReference]
            properties:
              opportunityReference: {type: string, minLength: 1}
          - required: [existingBusinessId]
            properties:
              existingBusinessId: {type: string, format: uuid}
      allOf:
        - if:
            required: [existingBusinessId]
            properties:
              existingBusinessId: {type: string}
          then:
            required: [modality]
            properties:
              modality: {type: string, minLength: 1, maxLength: 50}
    InterestRequestResponse:
      type: object
      required: [success, message, data]
      properties:
        success: {type: boolean, const: true}
        message: {type: string}
        data:
          type: object
          required: [reference, status]
          properties:
            reference: {type: string}
            status: {type: string, const: received}
    OpportunityResponse:
      type: object
      required: [success, data]
      properties:
        success: {type: boolean, const: true}
        data:
          type: object
          required: [id, slug, title]
          properties:
            id: {type: [string, integer]}
            slug: {type: string}
            title: {type: string}
            summary: {type: [string, 'null']}
            status: {type: string}