openapi: 3.1.0
info:
  title: Trygva Public API
  description: |
    REST-API fuer Hausverwaltungssoftware, Treuhaender, Steuerberater-
    Tools und ERP-Systeme. Multi-Tenant ueber PostgreSQL Row-Level Security.
  version: '1.0.0-beta.1'
  contact:
    name: Trygva Partners
    email: partners@trygva.ch
    url: https://trygva.ch/api-docs
  license:
    name: Trygva API Terms
    url: https://trygva.ch/legal/terms
servers:
  - url: https://api.trygva.ch/v1
    description: Production
  - url: https://api-staging.trygva.ch/v1
    description: Staging
security:
  - bearerAuth: []
paths:
  /terminations:
    post:
      summary: Neuen Kuendigungsfall starten
      tags: [Terminations]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTerminationRequest'
      responses:
        '201':
          description: Termination erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Termination'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /terminations/{id}:
    get:
      summary: Status eines Kuendigungsfalls abrufen
      tags: [Terminations]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            example: term_abc123
      responses:
        '200':
          description: Termination Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Termination'
        '404':
          $ref: '#/components/responses/NotFound'
  /textguard/scan:
    post:
      summary: Text auf rechtliche Schwachstellen scannen (NLP)
      tags: [TextGuard]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text, country]
              properties:
                text:
                  type: string
                  description: Frei-Text (z.B. Kuendigungs-Schreiben oder Mietvertrags-Klausel)
                  example: 'Wir kuendigen Ihnen wegen Eigenbedarf...'
                country:
                  type: string
                  enum: [CH, DE, AT]
      responses:
        '200':
          description: Scan-Ergebnis mit Flag-Liste
          content:
            application/json:
              schema:
                type: object
                properties:
                  riskLevel:
                    type: string
                    enum: [GREEN, YELLOW, RED]
                  flags:
                    type: array
                    items:
                      $ref: '#/components/schemas/TextGuardFlag'
  /calculators/raeumungsklage-kosten:
    post:
      summary: Verfahrenskosten-Schaetzung Raeumungsklage (public, kein Auth)
      tags: [Calculators]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [country, monthlyRent]
              properties:
                country:
                  type: string
                  enum: [CH, DE, AT]
                monthlyRent:
                  type: number
                  minimum: 1
      responses:
        '200':
          description: Kostenschaetzung
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostBreakdown'
  /calculators/mahnzinsen:
    post:
      summary: Verzugszinsen-Berechnung
      tags: [Calculators]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [country, debtorType, principal, dueDate]
              properties:
                country:
                  type: string
                  enum: [CH, DE, AT]
                debtorType:
                  type: string
                  enum: [consumer, business]
                principal:
                  type: number
                  minimum: 1
                dueDate:
                  type: string
                  format: date
      responses:
        '200':
          description: Mahnzinsen-Resultat
          content:
            application/json:
              schema:
                type: object
                properties:
                  daysOverdue:
                    type: integer
                  effectiveRate:
                    type: number
                  interest:
                    type: number
                  total:
                    type: number
                  legalBasis:
                    type: string
                  currency:
                    type: string
  /webhooks:
    post:
      summary: Webhook-Subscription anlegen
      tags: [Webhooks]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - termination.created
                      - termination.status_changed
                      - document.signed
                      - mautic.contact.synced
                      - payment.succeeded
                secret:
                  type: string
                  description: Shared Secret fuer Payload-Signatur (HMAC-SHA256)
      responses:
        '201':
          description: Webhook angelegt
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CreateTerminationRequest:
      type: object
      required: [tenantId, country, reason]
      properties:
        tenantId:
          type: string
          example: ten_abc123
        country:
          type: string
          enum: [CH, DE, AT]
        reason:
          type: string
          enum: [EIGENBEDARF, ZAHLUNGSVERZUG, VERTRAGSWIDRIG, SONSTIGES]
        tenantRecordId:
          type: string
    Termination:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - DRAFT
            - REVIEW
            - SENT
            - ACCEPTED
            - DISPUTED
            - WITHDRAWN
            - CLOSED
        riskLevel:
          type: string
          enum: [GREEN, YELLOW, RED]
        riskFactors:
          type: array
          items:
            type: object
            properties:
              factor:
                type: string
              severity:
                type: string
                enum: [LOW, MEDIUM, HIGH]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TextGuardFlag:
      type: object
      properties:
        type:
          type: string
        severity:
          type: string
          enum: [LOW, MEDIUM, HIGH]
        message:
          type: string
        startOffset:
          type: integer
        endOffset:
          type: integer
        suggestedFix:
          type: string
    CostBreakdown:
      type: object
      properties:
        streitwert:
          type: number
        gerichtskosten:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
        anwaltskosten:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
        vollstreckung:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
        total:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
        legalBasis:
          type: string
        currency:
          type: string
          enum: [CHF, EUR]
        warnings:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Token fehlt oder ist ungueltig
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: unauthorized
    NotFound:
      description: Ressource nicht gefunden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: not-found
    ValidationError:
      description: Validierungs-Fehler
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: validation-error
              details:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    message:
                      type: string
tags:
  - name: Terminations
    description: Kuendigungs-Workflow (5-Phasen-Wizard)
  - name: TextGuard
    description: NLP-Klausel-Scanner
  - name: Calculators
    description: Public Calculators (kein Auth erforderlich)
  - name: Webhooks
    description: Event-driven Notifications
externalDocs:
  description: Vollstaendige API-Dokumentation
  url: https://docs.trygva.ch
