{
  "openapi": "3.0.0",
  "info": {
    "title": "Public StBVV Tax Calculator API",
    "description": "Exposes statutory German tax advisor fee calculations (Steuerberatervergütungsverordnung - StBVV, status ab 01.07.2025) for German GmbHs, trading corporations, and wealth management vehicles. Supports Simple AI Mode (prompting with balance sheet sum and turnover) and Expert Mode (precision parameter overriding).",
    "version": "1.0.0",
    "contact": {
      "name": "Elegant Systems GmbH",
      "url": "https://elegant-systems.de"
    }
  },
  "servers": [
    {
      "url": "https://api.elegant-systems.de",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:4321",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/public/v1/calculate-stbvv": {
      "post": {
        "summary": "Calculate StBVV German tax advisor fees",
        "description": "Computes statutory tax advisor fees for a German GmbH under StBVV tables A, B, and C (effective July 1st, 2025). Can be queried in Simple Mode (AI-friendly) or Expert Mode.",
        "operationId": "calculateStbvv",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful fee calculation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/instruments/classify/{isin}": {
      "get": {
        "summary": "Classify Security / ETF and get InvStG Tax Exemption Rates",
        "description": "Returns verified legal asset classification (ETF, Mutual Fund, Fund of Funds, ETC) and German Investment Tax Act (§ 20 InvStG) Teilfreistellungsquoten for Private, Partnership, and Corporate tax regimes.",
        "operationId": "classifyInstrument",
        "parameters": [
          {
            "name": "isin",
            "in": "path",
            "required": true,
            "description": "12-character International Securities Identification Number (e.g. IE00B4L5Y983 or DE000A0S9GB0)",
            "schema": {
              "type": "string",
              "example": "IE00B4L5Y983"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful classification response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstrumentClassificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ISIN format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "ISIN not found in registry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CalculationRequest": {
        "type": "object",
        "description": "Provide either Simple Mode inputs (bilanzsumme, umsatz, mitarbeiterAnzahl) OR full Expert Mode precision inputs.",
        "properties": {
          "bilanzsumme": {
            "type": "number",
            "description": "Simple Mode: Total balance sheet assets/sum of the company (Bilanzsumme in EUR).",
            "example": 500000
          },
          "umsatz": {
            "type": "number",
            "description": "Simple Mode: Annual company revenues/turnover (Jahresumsatz in EUR).",
            "example": 1200000
          },
          "mitarbeiterAnzahl": {
            "type": "integer",
            "description": "Simple Mode: Average headcount of employees during the fiscal year (Anzahl Mitarbeiter).",
            "example": 3
          },
          "bilanzGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for balance sheet creation (defaults to bilanzsumme if Simple Mode).",
            "example": 500000
          },
          "bilanzZehntel": {
            "type": "integer",
            "description": "Expert Mode: Deciles/Tenths fee rate according to Table B (typically 10 for Mittelgebühr). Range 1-10.",
            "example": 10
          },
          "anhangGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for the notes/annex creation.",
            "example": 500000
          },
          "anhangZehntel": {
            "type": "integer",
            "description": "Expert Mode: Tenths fee rate according to Table B (typically 12 for Mittelgebühr). Range 1-12.",
            "example": 12
          },
          "kStGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for Corporate Income Tax declaration (Körperschaftsteuer - min EUR 16,000).",
            "example": 1200000
          },
          "kStZehntel": {
            "type": "integer",
            "description": "Expert Mode: Tenths fee rate for KSt declaration (typically 10 for Mittelgebühr).",
            "example": 10
          },
          "gewStGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for Trade Tax declaration (Gewerbesteuer - min EUR 16,000).",
            "example": 1200000
          },
          "gewStZehntel": {
            "type": "integer",
            "description": "Expert Mode: Tenths fee rate for GewSt declaration (typically 10 for Mittelgebühr).",
            "example": 10
          },
          "uStGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for annual Value Added Tax declaration (Umsatzsteuer).",
            "example": 1200000
          },
          "uStZehntel": {
            "type": "integer",
            "description": "Expert Mode: Tenths fee rate for USt declaration (typically 10 for Mittelgebühr).",
            "example": 10
          },
          "buchenGegenstandswert": {
            "type": "number",
            "description": "Expert Mode: Specific Gegenstandswert for annual bookkeeping ledger entries.",
            "example": 1200000
          },
          "buchenZehntel": {
            "type": "integer",
            "description": "Expert Mode: Tenths fee rate for bookkeeping entries (typically 10 for Mittelgebühr).",
            "example": 10
          },
          "lohnGebuehrProMitarbeiter": {
            "type": "number",
            "description": "Expert Mode: Fee charged per employee payslip per month in EUR (typically 15).",
            "example": 15
          },
          "pruefungBescheideAnzahl": {
            "type": "integer",
            "description": "Expert Mode: Number of tax assessment notices to inspect (Prüfung von Steuerbescheiden).",
            "example": 3
          },
          "pruefungGebuehrProBescheid": {
            "type": "number",
            "description": "Expert Mode: Specific fee charged per notice inspection in EUR (typically 10).",
            "example": 10
          },
          "activeItems": {
            "type": "object",
            "description": "Expert Mode: Toggles which cost components are active in the fee computation.",
            "properties": {
              "bilanz": { "type": "boolean", "default": true },
              "anhang": { "type": "boolean", "default": true },
              "kSt": { "type": "boolean", "default": true },
              "gewSt": { "type": "boolean", "default": true },
              "uSt": { "type": "boolean", "default": true },
              "buchen": { "type": "boolean", "default": true },
              "lohn": { "type": "boolean", "default": true },
              "pruefung": { "type": "boolean", "default": true },
              "auslagen": { "type": "boolean", "default": true }
            }
          }
        }
      },
      "CalculationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "currency": {
            "type": "string",
            "example": "EUR"
          },
          "meta": {
            "type": "object",
            "properties": {
              "legal_basis": { "type": "string", "example": "Steuerberatervergütungsverordnung (StBVV)" },
              "last_updated": { "type": "string", "example": "01.07.2025" },
              "note": { "type": "string", "example": "Alle Berechnungen sind unverbindliche Schätzungen nach gesetzlichen Mittelsätzen." }
            }
          },
          "results": {
            "type": "object",
            "properties": {
              "annual_total": { "type": "number", "example": 4567.89 },
              "annual_subtotal": { "type": "number", "example": 3838.56 },
              "annual_tax_19": { "type": "number", "example": 729.33 },
              "monthly_average": { "type": "number", "example": 380.66 }
            }
          },
          "breakdown": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "example": "bilanz" },
                "name": { "type": "string", "example": "Erstellung Bilanz (StBVV § 35)" },
                "cost_annual": { "type": "number", "example": 1200 },
                "cost_monthly": { "type": "number", "example": 100 }
              }
            }
          }
        }
      },
      "InstrumentClassificationResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "meta": {
            "type": "object",
            "properties": {
              "legalBasis": { "type": "string", "example": "Deutsches Investmentsteuergesetz (InvStG) & Einkommensteuergesetz (§ 23 EStG)" },
              "source": { "type": "string", "example": "VICTAR Tax Registry & Accounting Engine" },
              "timestamp": { "type": "string", "format": "date-time" }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "isin": { "type": "string", "example": "IE00B4L5Y983" },
              "symbol": { "type": "string", "example": "IWDA" },
              "name": { "type": "string", "example": "iShares Core MSCI World UCITS ETF" },
              "currency": { "type": "string", "example": "USD" },
              "instrumentType": { "type": "string", "enum": ["ETF", "MUTUAL_FUND", "FUND_OF_FUNDS", "ETC", "ETN", "EQUITY", "BOND", "OTHER"], "example": "ETF" },
              "invstgTaxStatus": { "type": "string", "enum": ["EQUITY_FUND_51", "MIXED_FUND_25", "REAL_ESTATE_FUND_50", "FOREIGN_REAL_ESTATE_FUND_50", "OTHER_FUND_0", "NOT_APPLICABLE"], "example": "EQUITY_FUND_51" },
              "isPhysicalGold": { "type": "boolean", "example": false },
              "isPhysicalBacked": { "type": "boolean", "example": false },
              "taxExemptionRates": {
                "type": "object",
                "properties": {
                  "privateInvestor": { "type": "number", "example": 0.30 },
                  "partnership": { "type": "number", "example": 0.60 },
                  "corporation": { "type": "number", "example": 0.80 },
                  "legalReference": { "type": "string", "example": "§ 20 Abs. 1 InvStG (Aktienfonds, Mindestquote 51%)" }
                }
              },
              "reviewStatus": { "type": "string", "example": "reviewed" },
              "verified": { "type": "boolean", "example": true }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "Please provide positive numbers for bilanzsumme and umsatz."
          }
        }
      }
    }
  }
}