openapi: 3.0.3
info:
  title: norma.ai Firm Suite API
  version: 1.0.0
  description: API for programmatic integration with norma.ai Firm Suite — Brazilian capital markets document generation and regulatory intelligence.
  contact:
    email: mayara@norma.ai

servers:
  - url: https://usenorma.ai/api/firm/v1
    description: Production

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key token (prefix nrmk_). Generated in Settings > API Keys.

  schemas:
    Deal:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        product_type: { type: string, enum: [FIDC, FIAGRO, CRI, CRA, Debênture, FII, FIP, Outro] }
        status: { type: string, enum: [active, completed, archived] }
        owner_user_id: { type: string, format: uuid }
        updated_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    GeneratedDocument:
      type: object
      properties:
        id: { type: string, format: uuid }
        template_id: { type: string, format: uuid }
        storage_path: { type: string }
        version: { type: integer }
        review_status: { type: string, enum: [draft, reviewed, approved] }
        created_at: { type: string, format: date-time }

    Template:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        document_type: { type: string }
        calibration_status: { type: string, enum: [pending, calibrating, active, needs_review] }
        slot_schema: { type: array, items: { type: object } }
        formatting_schema: { type: object }
        version: { type: integer }

    AuditLogEntry:
      type: object
      properties:
        id: { type: string, format: uuid }
        user_id: { type: string, format: uuid }
        action: { type: string }
        resource_type: { type: string }
        resource_id: { type: string, format: uuid }
        decision: { type: string, enum: [approved, flagged, blocked, logged] }
        content_hash: { type: string }
        created_at: { type: string, format: date-time }

    Error:
      type: object
      properties:
        error: { type: string }

paths:
  /deals:
    get:
      summary: List deals
      tags: [Deals]
      responses:
        '200':
          description: List of deals
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Deal' } }
    post:
      summary: Create a new deal
      tags: [Deals]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, product_type]
              properties:
                name: { type: string }
                product_type: { type: string }
      responses:
        '201':
          description: Deal created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Deal' }

  /deals/{id}/generate:
    post:
      summary: Generate document for a deal
      tags: [Documents]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                template_id: { type: string, format: uuid }
                deal_inputs: { type: object }
      responses:
        '202':
          description: Generation accepted

  /deals/{id}/documents:
    get:
      summary: List generated documents for a deal
      tags: [Documents]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: List of generated documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/GeneratedDocument' } }

  /documents/{id}/download:
    get:
      summary: Download a generated DOCX document
      tags: [Documents]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: DOCX file
          content:
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema: { type: string, format: binary }

  /templates/{id}:
    get:
      summary: Get template schema and metadata
      tags: [Templates]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Template with slot and formatting schemas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Template' }

  /templates/{id}/analyze:
    post:
      summary: Trigger template analysis
      tags: [Templates]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '202':
          description: Analysis started

  /audit-log:
    get:
      summary: Paginated audit log
      tags: [Audit]
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: action
          in: query
          schema: { type: string }
        - name: decision
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Paginated audit log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/AuditLogEntry' } }
                  pagination:
                    type: object
                    properties:
                      page: { type: integer }
                      limit: { type: integer }
                      total: { type: integer }
                      pages: { type: integer }