{
  "openapi": "3.1.0",
  "info": {
    "title": "Business OS API",
    "description": "API für Business OS – Zugang zu DATEV und Banking Enterprise-Schnittstellen. Alle Endpoints erfordern einen API Key im `x-api-key` Header. Credits werden pro API-Call abgezogen.",
    "version": "2.0.0",
    "contact": {
      "name": "Business OS Support",
      "email": "impressum@business-os.de",
      "url": "https://business-os.de/kontakt"
    }
  },
  "servers": [
    {
      "url": "https://api.business-os.de",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Dein Business OS API Key. Erstelle einen unter [app.business-os.de](https://app.business-os.de/) → API Keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Fehlermeldung",
            "example": "Missing required parameter: connection_id"
          }
        }
      },
      "DatevError": {
        "type": "object",
        "description": "JSON-Fehlerantwort. Bei Fehlern der DATEV-Schnittstelle kann zusätzlich `details` gesetzt sein. Bei bekannten Fehlerkategorien ist ein stabiler `code` gesetzt, anhand dessen Automatisierungen reagieren können.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Fehlermeldung"
          },
          "message": {
            "type": "string",
            "description": "Zusätzliche Erläuterung; wenn der Header `x-api-key` fehlt: Hinweis zur erforderlichen Header-Zeile."
          },
          "code": {
            "type": "string",
            "description": "Stabiler, maschinenlesbarer Fehlercode für bekannte Fehlerkategorien. Wird nur gesetzt, wenn die Ursache eindeutig erkannt wurde.\n\n- `datev_connection_invalid`: Account-Key ist abgelaufen oder widerrufen — Reconnect über das Dashboard nötig. Begleitet von `reconnectUrl`.\n- `datev_export_service_missing`: Mandant hat keine relevante DATEV-Subscription gebucht (z. B. Belegbilderservice, Rechnungsdatenservice, Datenservice Export Rechnungswesen-Familie). Begleitet von `activeSubscriptions` mit der Liste der tatsächlich aktiven Services.\n- `datev_endpoint_not_authorized`: Subscription am Mandanten ist vorhanden und der Token gilt, aber das DATEV-RVO-Schreib-/Leserecht für den konkreten Endpoint fehlt für den authentifizierten Nutzer. Reconnect hilft hier nicht — der Steuerberater/Mandant-Inhaber muss in DATEV RVO das entsprechende Teilrecht freischalten.",
            "enum": [
              "datev_connection_invalid",
              "datev_export_service_missing",
              "datev_endpoint_not_authorized"
            ]
          },
          "reconnectUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL zum Business OS Dashboard, über die der Nutzer die DATEV-Verbindung erneuern kann. Gesetzt bei `code = datev_connection_invalid`."
          },
          "activeSubscriptions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Liste der aktuell aktiven DATEV-Service-Subscriptions des Mandanten (z. B. Belegbilderservice, Rechnungsdatenservice 1.0). Gesetzt bei `code = datev_export_service_missing`, damit Automationen erkennen, welche Services bereits gebucht sind."
          },
          "details": {
            "type": "object",
            "description": "Strukturierte Zusatzinformationen bei Antworten der DATEV-Schnittstelle.",
            "additionalProperties": true
          }
        }
      },
      "RvoCheck": {
        "type": "object",
        "description": "Ein einzelner RVO-Teilrecht-Probe-Eintrag (siehe `/v2/datev-rewe-read/permissions`). `status` ist die normalisierte Klassifikation der DATEV-Antwort; `httpStatus` und `message` geben die rohen Werte für Debug-Zwecke.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "permission",
              "expired",
              "error",
              "unknown"
            ],
            "description": "- `ok`: DATEV hat den Probe-Call mit 200 beantwortet → RVO-Recht freigeschaltet.\n- `permission`: DATEV antwortet mit 403 → das RVO-Recht für diesen Bereich fehlt. Steuerberater/Mandant-Inhaber muss es in DATEV RVO aktivieren.\n- `expired`: DATEV antwortet mit 401 → Account-Key (Token) ist abgelaufen, Reconnect nötig.\n- `error`: anderer Fehler (5xx, Netzfehler, …).\n- `unknown`: konnte nicht geprüft werden (z. B. weil der Stammdaten-Probe vorher gescheitert ist und das `fiscalYearStartDate` für die abhängigen Probes fehlte)."
          },
          "httpStatus": {
            "type": "integer",
            "nullable": true,
            "description": "Roher HTTP-Status der DATEV-Antwort.",
            "example": 403
          },
          "maesnType": {
            "type": "string",
            "nullable": true,
            "description": "Fehler-Typ der DATEV-Schnittstelle (z. B. `not_authorized`).",
            "example": "not_authorized"
          },
          "message": {
            "type": "string",
            "nullable": true,
            "description": "Roh-Fehler-Message der DATEV-Antwort.",
            "example": "Access to the requested resource is forbidden."
          }
        },
        "required": [
          "status"
        ]
      },
      "PeriodeRead": {
        "type": "object",
        "description": "Skonto-Zeitraum innerhalb von perioden (faelligkeitsart ALS_ZEITRAUM).",
        "properties": {
          "rechnungsbereich": {
            "type": "string",
            "description": "Zeitraum für Rechnungsstellung",
            "example": "Rechnungsstellung bis Tag 10 des Monats"
          },
          "skontoFrist1": {
            "type": "string",
            "description": "Frist für Skonto 1",
            "example": "Tag 20 des laufenden Monats"
          },
          "skontoFrist2": {
            "type": "string",
            "description": "Frist für Skonto 2",
            "nullable": true,
            "example": null
          },
          "nettoFrist": {
            "type": "string",
            "description": "Zahlungsziel (Nettofrist)",
            "example": "Tag 31 des laufenden Monats"
          }
        }
      },
      "ZahlungsbedingungRead": {
        "type": "object",
        "description": "Eine Zahlungsbedingung (Felder deutsch)",
        "properties": {
          "id": {
            "type": "string",
            "description": "Eindeutige ID der Zahlungsbedingung",
            "example": "10"
          },
          "bezeichnung": {
            "type": "string",
            "description": "Vollständige Bezeichnung",
            "example": "30 Tage 2,0%; 60 Tage netto"
          },
          "skontoFrist1": {
            "type": "number",
            "description": "Tage bis Skonto 1 (bei `faelligkeitsart` `NACH_TAGE`)",
            "nullable": true,
            "example": 30
          },
          "skontoSatz1": {
            "type": "number",
            "description": "Skontosatz 1 in Prozent",
            "example": 2
          },
          "skontoFrist2": {
            "type": "number",
            "description": "Tage bis Skonto 2",
            "nullable": true,
            "example": 0
          },
          "skontoSatz2": {
            "type": "number",
            "description": "Skontosatz 2 in Prozent",
            "example": 0
          },
          "nettoFrist": {
            "type": "number",
            "description": "Zahlungsziel in Tagen (Nettofrist)",
            "nullable": true,
            "example": 60
          },
          "faelligkeitsart": {
            "type": "string",
            "enum": [
              "NACH_TAGE",
              "ALS_ZEITRAUM"
            ],
            "description": "NACH_TAGE = Frist in Tagen, ALS_ZEITRAUM = Periodenlogik",
            "example": "NACH_TAGE"
          },
          "perioden": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PeriodeRead"
            }
          }
        }
      },
      "KontoRead": {
        "type": "object",
        "description": "Kontozeile (Sach- oder Personenkonto; nur ausgewählte Felder, deutsch)",
        "properties": {
          "kontobeschriftung": {
            "type": "string",
            "description": "Offizielle DATEV-Kontobeschriftung"
          },
          "kontonummer": {
            "type": "string",
            "description": "Kontonummer"
          }
        }
      },
      "SaldoRead": {
        "type": "object",
        "description": "Betrag mit Soll/Haben-Kennzeichen",
        "properties": {
          "betrag": {
            "type": "number",
            "example": 1000
          },
          "sollHabenKennzeichen": {
            "type": "string",
            "enum": [
              "SOLL",
              "HABEN"
            ]
          }
        }
      },
      "PeriodenwertRead": {
        "type": "object",
        "description": "Saldo einer Buchungsperiode",
        "properties": {
          "periode": {
            "type": "integer",
            "minimum": 1,
            "maximum": 14,
            "description": "Buchungsperiode (1–14, inkl. Sonderperioden)"
          },
          "saldo": {
            "$ref": "#/components/schemas/SaldoRead"
          }
        }
      },
      "SummenSaldenZeileRead": {
        "type": "object",
        "description": "Eine Zeile der Summen- und Saldenliste",
        "properties": {
          "kontobeschriftung": {
            "type": "string",
            "description": "Offizielle DATEV-Kontobeschriftung",
            "example": "EDV-Software, entgeltl. erworben"
          },
          "kontonummer": {
            "type": "string",
            "description": "Kontonummer",
            "example": "270000"
          },
          "saldo": {
            "$ref": "#/components/schemas/SaldoRead"
          },
          "periodenwerte": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PeriodenwertRead"
            }
          },
          "ebWert": {
            "$ref": "#/components/schemas/SaldoRead",
            "description": "Eröffnungsbilanzwert (EB-Wert) zum Jahresstart",
            "nullable": true
          },
          "umsatzHaben": {
            "type": "number",
            "description": "Haben-Umsatz des Geschäftsjahrs",
            "example": 343.53
          },
          "umsatzSoll": {
            "type": "number",
            "description": "Soll-Umsatz des Geschäftsjahrs",
            "example": 2926.53
          }
        }
      },
      "KostenstellenRead": {
        "type": "object",
        "description": "DATEV-Kostenstellenfelder",
        "properties": {
          "kost1": {
            "type": "string",
            "nullable": true
          },
          "kost2": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "BuchungszeileRead": {
        "type": "object",
        "description": "Einzelne Zeile einer Buchung",
        "properties": {
          "kontonummer": {
            "type": "string",
            "description": "Sachkontonummer"
          },
          "kostenstellen": {
            "$ref": "#/components/schemas/KostenstellenRead"
          },
          "buSchluessel": {
            "type": "string",
            "nullable": true,
            "description": "Buchungsschlüssel (DATEV-Steuerschlüssel-Code)"
          },
          "umsatz": {
            "type": "number",
            "description": "Bruttobetrag der Buchungszeile"
          },
          "belegfeld1": {
            "type": "string",
            "description": "Belegnummer"
          },
          "belegdatum": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339)."
          }
        }
      },
      "BuchungsdatumRead": {
        "type": "object",
        "description": "Buchungsdatensatz mit Buchungszeilen",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "ID der Buchung"
          },
          "waehrung": {
            "type": "string",
            "description": "Währungscode (ISO 4217)"
          },
          "sollHabenKennzeichen": {
            "type": "string",
            "enum": [
              "SOLL",
              "HABEN"
            ]
          },
          "buchungstext": {
            "type": "string"
          },
          "buchungszeilen": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BuchungszeileRead"
            }
          }
        }
      },
      "DatevAntwortInformation": {
        "type": "object",
        "description": "Ein Eintrag in der Informationsliste der DATEV-Antwort.",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Dateiname"
          },
          "message": {
            "type": "string",
            "description": "Nachricht"
          },
          "timestamp": {
            "type": "string",
            "description": "Zeitstempel",
            "format": "date-time"
          },
          "type": {
            "type": "string",
            "description": "Typ"
          }
        },
        "additionalProperties": true
      },
      "DatevAntwort": {
        "type": "object",
        "description": "DATEV-Antwort: Ergebnis des asynchronen DATEV-Tasks nach Abschluss. Kann zusätzliche Felder enthalten.",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status"
          },
          "information": {
            "type": "array",
            "description": "Informationen",
            "items": {
              "$ref": "#/components/schemas/DatevAntwortInformation"
            }
          }
        },
        "additionalProperties": true
      },
      "DatevAntwortMeldung": {
        "type": "object",
        "description": "Ein Eintrag in der Meldungsliste der DATEV-Antwort (öffentliche Felder).",
        "properties": {
          "dateiname": {
            "type": "string",
            "description": "Dateiname"
          },
          "nachricht": {
            "type": "string",
            "description": "Nachricht"
          },
          "zeitstempel": {
            "type": "string",
            "format": "date-time",
            "description": "Zeitstempel"
          },
          "typ": {
            "type": "string",
            "description": "Typ (z. B. INFO)"
          }
        },
        "additionalProperties": true
      },
      "DatevAntwortKassenbuch": {
        "type": "object",
        "description": "Ergebnis des asynchronen DATEV-Tasks (Kassenbuch einfach): `meldungen` statt `information`.",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status"
          },
          "meldungen": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatevAntwortMeldung"
            }
          }
        },
        "additionalProperties": true
      },
      "Connection": {
        "type": "object",
        "description": "Eine Bank-Verbindung über die Banking-Schnittstelle",
        "properties": {
          "id": {
            "type": "string",
            "description": "Eindeutige Connection-ID",
            "example": "9182736450918273645"
          },
          "provider_name": {
            "type": "string",
            "description": "Name der Bank",
            "example": "Musterbank"
          },
          "provider_code": {
            "type": "string",
            "description": "Technischer Provider-Code",
            "example": "musterbank_oauth_client_de"
          },
          "country_code": {
            "type": "string",
            "description": "Ländercode (ISO 3166-1 alpha-2)",
            "example": "DE"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "disabled",
              "pending",
              "pending_connect"
            ],
            "description": "Aktueller Verbindungsstatus. `pending_connect` ist ein kurzlebiger Zustand: er erscheint direkt nach `POST /v2/banking/connect` (Pre-Insert-Row mit reserviertem pending_token) und wird ersetzt, sobald der erste Banking-Webhook eintrifft. Wird ein begonnener Connect-Flow nicht abgeschlossen, räumt ein Cron-Job die Row nach 15 Minuten auf.",
            "example": "active"
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "User-ID des Connection-Owners — desjenigen Nutzers, dessen Bank-Credentials hinter der Verbindung stehen. Banking-Customer-Identität ist email-bound, daher gehört eine Connection konzeptionell dem authentifizierenden Nutzer (nicht der Organisation). Bei Account-Delete kaskadieren alle vom User erstellten Connections. Legacy-Connections vor 2026-05-26 können null sein und werden beim nächsten Reconnect lazy-gefüllt.",
            "example": "d90f20ae-f6c1-46da-a080-3d4c86329bf6"
          },
          "automatic_refresh": {
            "type": "boolean",
            "description": "Ob automatische Aktualisierung aktiviert ist",
            "example": true
          },
          "next_refresh_possible_at": {
            "type": "string",
            "format": "date-time",
            "description": "Frühester Zeitpunkt für nächste Aktualisierung",
            "example": "2026-03-24T14:34:54+00:00"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Erstellungszeitpunkt",
            "example": "2026-03-24T13:50:58+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Letzter Aktualisierungszeitpunkt",
            "example": "2026-03-24T14:19:54+00:00"
          },
          "display_name": {
            "type": "string",
            "nullable": true,
            "description": "Benutzerdefinierter Anzeigename",
            "example": null
          },
          "logo_url": {
            "type": "string",
            "format": "uri",
            "description": "URL zum Bank-Logo",
            "example": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/de/spk_aschaffenburg_de.svg"
          },
          "consent_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Ablaufzeitpunkt der PSD2-Einwilligung",
            "example": "2026-09-20T14:19:16+00:00"
          },
          "error_class": {
            "type": "string",
            "nullable": true,
            "description": "Fehlerklasse (null wenn kein Fehler)",
            "example": null
          },
          "error_message": {
            "type": "string",
            "nullable": true,
            "description": "Fehlermeldung (null wenn kein Fehler)",
            "example": null
          }
        }
      },
      "Account": {
        "type": "object",
        "description": "Ein Bankkonto einer Verbindung",
        "properties": {
          "can_hide": {
            "type": "boolean",
            "description": "Ob das Konto im Dashboard ausgeblendet werden kann.",
            "example": true
          },
          "id": {
            "type": "string",
            "description": "Eindeutige Account-ID",
            "example": "8273645091827364509"
          },
          "name": {
            "type": "string",
            "description": "Kontoname (oft die IBAN)",
            "example": "DE89370400440532013000"
          },
          "nature": {
            "type": "string",
            "enum": [
              "account",
              "card",
              "debit_card",
              "credit_card",
              "saving",
              "loan"
            ],
            "description": "Kontotyp",
            "example": "account"
          },
          "balance": {
            "type": "number",
            "description": "Aktueller Kontostand",
            "example": -5978.36
          },
          "currency_code": {
            "type": "string",
            "description": "Währungscode (ISO 4217)",
            "example": "EUR"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Erstellungszeitpunkt",
            "example": "2026-03-24T13:51:32+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Letzter Aktualisierungszeitpunkt",
            "example": "2026-03-24T14:19:54+00:00"
          },
          "extra": {
            "type": "object",
            "description": "Zusätzliche Kontoinformationen",
            "properties": {
              "iban": {
                "type": "string",
                "description": "IBAN des Kontos",
                "example": "DE89370400440532013000"
              },
              "holder_name": {
                "type": "string",
                "description": "Kontoinhaber",
                "example": "Mustermann GmbH"
              },
              "transactions_count": {
                "type": "object",
                "description": "Anzahl der Transaktionen nach Status",
                "properties": {
                  "posted": {
                    "type": "integer",
                    "description": "Anzahl gebuchter Transaktionen",
                    "example": 418
                  },
                  "pending": {
                    "type": "integer",
                    "description": "Anzahl ausstehender Transaktionen",
                    "example": 1
                  }
                }
              }
            }
          }
        }
      },
      "Transaction": {
        "type": "object",
        "description": "Eine Kontotransaktion",
        "properties": {
          "id": {
            "type": "string",
            "description": "Eindeutige Transaktions-ID",
            "example": "6450918273645091827"
          },
          "account_id": {
            "type": "string",
            "description": "ID des zugehörigen Kontos",
            "example": "8273645091827364509"
          },
          "payment_id": {
            "type": "string",
            "nullable": true,
            "description": "ID der zugehörigen Zahlung, sofern diese Transaktion über `POST /v2/banking/payments` initiiert wurde (Match über die server-generierte `end_to_end_id`). Sonst `null`.",
            "example": "4509182736450918273"
          },
          "duplicated": {
            "type": "boolean",
            "description": "Ob die Transaktion als Duplikat erkannt wurde",
            "example": false
          },
          "mode": {
            "type": "string",
            "description": "Modus der Transaktion",
            "example": "normal"
          },
          "status": {
            "type": "string",
            "enum": [
              "posted",
              "pending"
            ],
            "description": "Buchungsstatus",
            "example": "posted"
          },
          "made_on": {
            "type": "string",
            "format": "date",
            "description": "Datum der Transaktion",
            "example": "2026-01-23"
          },
          "amount": {
            "type": "number",
            "description": "Betrag (negativ = Abbuchung, positiv = Gutschrift)",
            "example": -2000
          },
          "currency_code": {
            "type": "string",
            "description": "Währungscode (ISO 4217)",
            "example": "EUR"
          },
          "description": {
            "type": "string",
            "description": "Buchungstext",
            "example": "FOLGELASTSCHRIFT"
          },
          "description_parsed": {
            "type": "object",
            "description": "Aus dem `description`-Verwendungszweck geparste, standardisierte SEPA-Felder (DK-/DFÜ-Konvention). Alle Felder sind immer vorhanden, `null` wenn nicht im Text gefunden. EREF, Gegen-IBAN und Gegenpartei-Name sind hier bewusst ausgelassen — die liefert das `extra`-Objekt bereits strukturiert (`extra.end_to_end_id`, `extra.payee`/`extra.payer`, `extra.payee_information`/`extra.payer_information`). Erkennt sowohl Kurz-Codes (`CRED:`/`MREF:` …) als auch deutsche Langformen (`Glaeubiger-ID:`/`Mandatsreferenz:` …); Kurz-Codes haben Vorrang.",
            "properties": {
              "cred": {
                "type": "string",
                "nullable": true,
                "description": "Gläubiger-ID (SEPA Creditor Identifier, CRED)",
                "example": "DE98ZZZ09999999999"
              },
              "mref": {
                "type": "string",
                "nullable": true,
                "description": "Mandatsreferenz (MREF)",
                "example": "M-2026-0042"
              },
              "kref": {
                "type": "string",
                "nullable": true,
                "description": "Kundenreferenz (KREF)",
                "example": null
              },
              "debt": {
                "type": "string",
                "nullable": true,
                "description": "Debtor Identifier (DEBT)",
                "example": null
              },
              "svwz": {
                "type": "string",
                "nullable": true,
                "description": "SEPA-Verwendungszweck (SVWZ)",
                "example": null
              },
              "abwa": {
                "type": "string",
                "nullable": true,
                "description": "Abweichender Auftraggeber / Ultimate Debtor (ABWA)",
                "example": null
              },
              "abwe": {
                "type": "string",
                "nullable": true,
                "description": "Abweichender Empfänger / Ultimate Creditor (ABWE)",
                "example": null
              },
              "bic": {
                "type": "string",
                "nullable": true,
                "description": "BIC der Gegenpartei",
                "example": "COBADEFF"
              },
              "oamt": {
                "type": "string",
                "nullable": true,
                "description": "Ursprungsbetrag (Original Amount, OAMT)",
                "example": null
              },
              "coam": {
                "type": "string",
                "nullable": true,
                "description": "Zinskompensationsbetrag (Compensation Amount, COAM)",
                "example": null
              },
              "purp": {
                "type": "string",
                "nullable": true,
                "description": "SEPA-Zweckcode (Purpose Code, PURP)",
                "example": null
              }
            }
          },
          "category": {
            "type": "string",
            "description": "Automatisch erkannte Kategorie",
            "example": "service_fee"
          },
          "extra": {
            "type": "object",
            "description": "Zusätzliche Transaktionsdetails",
            "properties": {
              "time": {
                "type": "string",
                "description": "Uhrzeit der Buchung",
                "example": "00:07:13"
              },
              "payee": {
                "type": "string",
                "description": "IBAN des Empfängers",
                "example": "DE02100100100006820101"
              },
              "payer": {
                "type": "string",
                "description": "IBAN des Absenders",
                "example": "DE89370400440532013000"
              },
              "additional": {
                "type": "string",
                "description": "Zusätzlicher Buchungstext",
                "example": "FOLGELASTSCHRIFT"
              },
              "merchant_id": {
                "type": "string",
                "nullable": true,
                "description": "Händler-ID (sofern von der Bank geliefert, sonst null).",
                "example": null
              },
              "posting_date": {
                "type": "string",
                "format": "date",
                "description": "Buchungsdatum",
                "example": "2026-01-23"
              },
              "end_to_end_id": {
                "type": "string",
                "description": "Ende-zu-Ende-Referenz",
                "example": "RE-2026-0042"
              },
              "payee_information": {
                "type": "string",
                "description": "Name des Empfängers",
                "example": "Beispiel Handels GmbH"
              },
              "payer_information": {
                "type": "string",
                "description": "Name des Absenders",
                "example": "MUSTERMANN GMBH"
              },
              "account_balance_snapshot": {
                "type": "number",
                "description": "Kontostand nach der Transaktion",
                "example": 12450.75
              },
              "categorization_confidence": {
                "type": "number",
                "description": "Konfidenz der automatischen Kategorisierung (0-1)",
                "example": 1
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Erstellungszeitpunkt",
            "example": "2026-03-24T13:51:32Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Letzter Aktualisierungszeitpunkt",
            "example": "2026-03-24T13:51:39Z"
          }
        }
      },
      "PaymentRecord": {
        "type": "object",
        "description": "Eine Zahlung aus den Business-OS-Datensätzen (`banking_payments`) — flach und filterbar. Anders als die Salt-Edge-Form (`Payment`) liegen die Details direkt auf oberster Ebene (kein `payment_attributes`).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment-ID",
            "example": "7364509182736450918"
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "Organisation, der die Zahlung zugeordnet ist.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "status": {
            "type": "string",
            "description": "Zahlungsstatus (per Webhook gepflegt).",
            "example": "settled"
          },
          "raw_provider_status": {
            "type": "string",
            "nullable": true,
            "description": "Roher Statuscode der Bank.",
            "example": "ACCC"
          },
          "connection_id": {
            "type": "string",
            "nullable": true,
            "description": "Salt-Edge-Connection-ID (sofern erfasst).",
            "example": "9182736450918273645"
          },
          "account_id": {
            "type": "string",
            "nullable": true,
            "description": "Konto-ID, von dem die Zahlung ausging.",
            "example": "8273645091827364509"
          },
          "provider_code": {
            "type": "string",
            "example": "musterbank_oauth_client_de"
          },
          "provider_name": {
            "type": "string",
            "example": "Musterbank"
          },
          "template_identifier": {
            "type": "string",
            "example": "SEPA"
          },
          "amount": {
            "type": "number",
            "description": "Betrag (numerisch).",
            "example": 1
          },
          "currency_code": {
            "type": "string",
            "example": "EUR"
          },
          "creditor_name": {
            "type": "string",
            "example": "Mustermann GmbH"
          },
          "creditor_iban": {
            "type": "string",
            "example": "DE27100777770209299700"
          },
          "debtor_iban": {
            "type": "string",
            "nullable": true,
            "example": "DE89370400440532013000"
          },
          "end_to_end_id": {
            "type": "string",
            "description": "Auto-generiert (`BOS-…`) für Payment-↔-Transaction-Matching.",
            "example": "BOS-1730000000000-a1b2c3d4"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Verwendungszweck.",
            "example": "Rechnung RE-2026-001"
          },
          "reference": {
            "type": "string",
            "nullable": true,
            "description": "Lokales Label (z.B. eigene Rechnungsnummer) — kein Feld der Bank.",
            "example": "RG-2026-03024"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-24T12:26:30Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-24T12:27:10Z"
          }
        }
      },
      "Payment": {
        "type": "object",
        "description": "Eine initiierte Zahlung",
        "properties": {
          "id": {
            "type": "string",
            "description": "Eindeutige Payment-ID",
            "example": "7364509182736450918"
          },
          "reference": {
            "type": "string",
            "nullable": true,
            "description": "Lokales Label, das beim Erstellen über das Feld `reference` mitgegeben wurde (z.B. die eigene Rechnungsnummer). Von Business OS gespeichert und hier zur Identifikation zurückgegeben — kein Feld der Bank.",
            "example": "RG-2026-03024"
          },
          "provider_code": {
            "type": "string",
            "description": "Technischer Provider-Code",
            "example": "musterbank_oauth_client_de"
          },
          "provider_name": {
            "type": "string",
            "description": "Name der Bank",
            "example": "Musterbank"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Erstellungszeitpunkt",
            "example": "2026-03-24T12:26:30Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Letzter Aktualisierungszeitpunkt",
            "example": "2026-03-24T12:27:10Z"
          },
          "refresh_interval": {
            "type": "integer",
            "description": "Aktualisierungsintervall in Sekunden",
            "example": 3600
          },
          "refresh_timeout": {
            "type": "integer",
            "description": "Timeout für Aktualisierung in Sekunden",
            "example": 172800
          },
          "status": {
            "type": "string",
            "enum": [
              "initiated",
              "initiated_info_required",
              "authorizing",
              "authorized",
              "processing",
              "executed",
              "settled",
              "failed",
              "rejected"
            ],
            "description": "Zahlungsstatus des Payment-Objekts. `executed` = Auftrag von der Bank ausgeführt (Settlement noch nicht bestätigt), `settled` = Settlement vollständig abgeschlossen (finaler Erfolg). Hinweis: Der Zwischenstatus `initiated_info_required` wird per Webhook bewusst nicht ausgeliefert (siehe PIS-Webhook).",
            "example": "settled"
          },
          "raw_provider_status": {
            "type": "string",
            "nullable": true,
            "description": "Roher Statuscode der Bank (z.B. ACCC, ACSC)",
            "example": "ACCC"
          },
          "template_identifier": {
            "type": "string",
            "enum": [
              "SEPA",
              "SEPA_INSTANT"
            ],
            "description": "Zahlungsart",
            "example": "SEPA"
          },
          "payment_attributes": {
            "type": "object",
            "description": "Zahlungsdetails",
            "properties": {
              "amount": {
                "type": "string",
                "description": "Betrag als String",
                "example": "1.00"
              },
              "debtor_iban": {
                "type": "string",
                "description": "IBAN des Absenders",
                "example": "DE89370400440532013000"
              },
              "description": {
                "type": "string",
                "description": "Verwendungszweck",
                "example": "Rechnung RE-2026-001"
              },
              "creditor_iban": {
                "type": "string",
                "description": "IBAN des Empfängers",
                "example": "DE27100777770209299700"
              },
              "creditor_name": {
                "type": "string",
                "description": "Name des Empfängers",
                "example": "Mustermann GmbH"
              },
              "creditor_bic": {
                "type": "string",
                "description": "BIC des Empfängers (optional, abhängig vom Provider)",
                "example": "TRISDE55XXX"
              },
              "currency_code": {
                "type": "string",
                "description": "Währungscode",
                "example": "EUR"
              },
              "end_to_end_id": {
                "type": "string",
                "description": "Ende-zu-Ende-Referenz",
                "example": "RE-2026-001"
              },
              "customer_ip_address": {
                "type": "string",
                "description": "IP-Adresse des Kunden (automatisch gesetzt)",
                "example": "203.0.113.42"
              }
            }
          },
          "last_attempt": {
            "type": "object",
            "description": "Details zum letzten Zahlungsversuch",
            "properties": {
              "id": {
                "type": "string",
                "description": "Attempt-ID",
                "example": "5091827364509182736"
              },
              "custom_fields": {
                "type": "object",
                "description": "Benutzerdefinierte Felder",
                "example": {}
              }
            }
          }
        }
      },
      "ConnectSessionResponse": {
        "type": "object",
        "description": "Antwort beim Erstellen einer Connect-Session",
        "properties": {
          "connect_url": {
            "type": "string",
            "format": "uri",
            "description": "URL zum Connect-Widget",
            "example": "https://psd2.business-os.de/connect?token=xxx"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Ablaufzeitpunkt der Session",
            "example": "2026-03-24T12:44:03Z"
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid",
            "description": "User-ID, die als Connection-Owner persistiert wird (Dashboard-Flow: der authentifizierte Nutzer; API-Key-Flow: der erste Owner-Member der Ziel-Org). Identisch mit dem `owner_user_id`-Feld der späteren `BankingConnection`-Row.",
            "example": "d90f20ae-f6c1-46da-a080-3d4c86329bf6"
          },
          "pending_token": {
            "type": "string",
            "format": "uuid",
            "description": "Opaque Korrelations-Token. Wird in den Banking-`custom_fields` mitgegeben und kommt mit jedem Connection-Webhook zurück — Server-seitig matched darüber die Pre-Insert-Row mit dem eingehenden Banking-Connection-Event (Round-Trip-Key, garantiert dass die neue Connection auf der richtigen Org landet).",
            "example": "8c4a8b18-9b7c-4f9d-9a3e-1a2b3c4d5e6f"
          }
        }
      },
      "PaymentCreateRequest": {
        "type": "object",
        "description": "Request-Body zum Initiieren einer Zahlung. Felder werden flach übergeben — `provider_code`, `debtor_iban` und die Banking-API werden automatisch aus der Account-ID aufgelöst. `end_to_end_id` wird **immer server-seitig generiert** (`BOS-{timestamp}-{hex}`) für das Payment-↔-Transaction-Matching. Ein vom Client übergebener Wert wird ignoriert.",
        "required": [
          "account_id",
          "amount"
        ],
        "properties": {
          "account_id": {
            "type": "string",
            "description": "ID des eigenen Bankkontos (`Account.id`). Daraus werden Provider, Debitor-IBAN und Banking-API automatisch aufgelöst.",
            "example": "8273645091827364509"
          },
          "amount": {
            "type": "string",
            "description": "Betrag als String (z.B. \"1.00\" für 1,00 €).",
            "example": "1.00"
          },
          "currency_code": {
            "type": "string",
            "description": "Währungscode (ISO 4217). Default `EUR`.",
            "default": "EUR",
            "example": "EUR"
          },
          "template_identifier": {
            "type": "string",
            "enum": [
              "AUTO",
              "SEPA",
              "SEPA_INSTANT"
            ],
            "description": "Zahlungsart. Default `AUTO`: wählt automatisch `SEPA_INSTANT`, wenn die Bank Instant anbietet, sonst `SEPA` (bei Terminüberweisung via `date` immer `SEPA`); lehnt die Bank den automatisch gewählten Instant-Auftrag ab, wird einmalig als `SEPA` ausgeführt (Response-Feld `template_fallback`). Explizit gesetztes `SEPA`/`SEPA_INSTANT` wird unverändert verwendet.",
            "default": "AUTO",
            "example": "AUTO"
          },
          "creditor_name": {
            "type": "string",
            "description": "Name des Empfängers.",
            "example": "Mustermann GmbH"
          },
          "creditor_iban": {
            "type": "string",
            "description": "IBAN des Empfängers.",
            "example": "DE27100777770209299700"
          },
          "description": {
            "type": "string",
            "description": "Verwendungszweck.",
            "example": "Rechnung G-RE-2026-03024"
          },
          "reference": {
            "type": "string",
            "description": "Lokales Label (optional) — z.B. die eigene Rechnungsnummer. Wird gespeichert und bei `GET /v2/banking/payments/{id}` sowie `GET /v2/banking/payments` wieder zurückgegeben, **nicht** an die Bank übermittelt (SEPA kennt kein solches Feld).",
            "example": "RG-2026-03024"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Ausführungsdatum (`YYYY-MM-DD`) für eine geplante Zahlung (Terminüberweisung). Nur wirksam, wenn das Payment-Template der Bank `date` unterstützt — die je Template verfügbaren Zusatzfelder liefert `GET /v2/banking/payment-templates`.",
            "example": "2026-07-01"
          },
          "creditor_country_code": {
            "type": "string",
            "description": "ISO-3166-1-alpha-2 Country-Code des Empfängers. Wenn weggelassen, wird er automatisch aus den ersten 2 Zeichen der `creditor_iban` abgeleitet.",
            "example": "DE"
          },
          "creditor_address": {
            "type": "string",
            "description": "Adresse des Empfängers (optional, bankabhängig).",
            "example": "Musterstr. 1, 10115 Berlin"
          },
          "creditor_agent": {
            "type": "string",
            "description": "BIC der Empfängerbank (optional).",
            "example": "MUSTBE22"
          },
          "creditor_agent_name": {
            "type": "string",
            "description": "Name der Empfängerbank (optional).",
            "example": "Musterbank AG"
          },
          "debtor_bic": {
            "type": "string",
            "description": "BIC der eigenen Bank (optional, wird i.d.R. aus der `debtor_iban` aufgelöst).",
            "example": "DEUTDEFFXXX"
          },
          "mode": {
            "type": "string",
            "description": "bankspezifischer Modus (optional, bankabhängig).",
            "example": "embedded"
          },
          "return_to": {
            "type": "string",
            "format": "uri",
            "description": "Redirect-URL nach Zahlungsbestätigung im Browser. Default `https://app.business-os.de/close`.",
            "default": "https://app.business-os.de/close",
            "example": "https://app.business-os.de/close"
          },
          "custom_fields": {
            "type": "object",
            "description": "Benutzerdefinierte Felder (werden im Callback zurückgegeben).",
            "example": {
              "invoice_id": "G-RE-2026-03024"
            }
          }
        }
      },
      "PaymentCreateResponse": {
        "type": "object",
        "description": "Antwort beim Initiieren einer Zahlung. Banking-Response (`data`) wird durchgereicht, plus der server-seitig generierte `end_to_end_id` als zusätzliches Top-Level-Field unter `data`.",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "payment_id": {
                "type": "string",
                "description": "Banking-Payment-ID — wird für Status-Abfragen und Transaction-Matching benötigt.",
                "example": "4509182736450918273"
              },
              "payment_url": {
                "type": "string",
                "format": "uri",
                "description": "URL zur Zahlungsbestätigung im Browser (Endkunde authentifiziert hier per OAuth/Decoupled).",
                "example": "https://psd2.business-os.de/payments/connect?token=xxx"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "Ablaufzeitpunkt der Zahlungs-Session.",
                "example": "2026-03-24T12:44:03Z"
              },
              "end_to_end_id": {
                "type": "string",
                "description": "Server-seitig generierter Eindeutigkeits-Identifier im Format `BOS-{timestamp}-{hex}`. Erscheint später in der zugehörigen `Transaction` und ermöglicht das Payment-↔-Transaction-Matching.",
                "example": "BOS-1716480000000-a1b2c3d4"
              }
            }
          }
        }
      },
      "RefreshResponse": {
        "type": "object",
        "description": "Antwort beim Refresh einer Verbindung. Wenn der serverseitige Refresh sofort durchläuft (keine erneute User-Autorisierung nötig), wird `refreshed: true` zurückgegeben. Andernfalls kommt eine Connect-URL für die erneute Autorisierung.",
        "properties": {
          "refreshed": {
            "type": "boolean",
            "description": "`true` wenn der Refresh server-seitig sofort abgeschlossen wurde. Wenn nicht gesetzt, muss der User über `connect_url` erneut autorisieren.",
            "example": true
          },
          "connect_url": {
            "type": "string",
            "format": "uri",
            "description": "URL zum Connect Widget (nur wenn erneute Autorisierung nötig)",
            "example": "https://psd2.business-os.de/connect?token=xxx"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Ablaufzeitpunkt der Session",
            "example": "2026-03-24T04:26:21Z"
          }
        }
      },
      "WebhookUrlResponse": {
        "type": "object",
        "properties": {
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Konfigurierte Webhook-URL oder null",
            "example": "https://hook.eu1.make.com/abc123"
          }
        }
      },
      "DailyBalance": {
        "type": "object",
        "description": "Täglicher Saldo. Das Feld `transactions[]` wird nur zurückgegeben, wenn der Listing-Endpoint mit `include_transactions=true` aufgerufen wurde.",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Datum (YYYY-MM-DD)",
            "example": "2026-04-25"
          },
          "sod": {
            "type": "number",
            "description": "Start of Day Balance (Eröffnungssaldo)",
            "example": 10000
          },
          "eod": {
            "type": "number",
            "description": "End of Day Balance (Schlusssaldo)",
            "example": 10500
          },
          "cash_in": {
            "type": "number",
            "description": "Summe aller Geldeingänge an diesem Tag",
            "example": 1500
          },
          "cash_out": {
            "type": "number",
            "description": "Summe aller Geldausgänge an diesem Tag",
            "example": 1000
          },
          "delta": {
            "type": "number",
            "description": "Nettoveränderung (cash_in - cash_out)",
            "example": 500
          },
          "transactions": {
            "type": "array",
            "description": "Vollständige Transaktionsdaten für diesen Tag. Nur gesetzt wenn `include_transactions=true` im Listing-Call.",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          }
        },
        "required": [
          "date",
          "sod",
          "eod",
          "cash_in",
          "cash_out",
          "delta"
        ]
      }
    },
    "parameters": {
      "ToolParam": {
        "name": "tool",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "DATEV Unternehmen Online",
            "DATEV Rechnungswesen - Read",
            "DATEV Rechnungswesen - Write"
          ]
        },
        "description": "DATEV Tool-Typ"
      },
      "ApiParam": {
        "name": "api",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "partner",
            "openbanking"
          ],
          "default": "partner"
        },
        "description": "Banking-API: `partner` (regulierte Banken) oder `openbanking` (unregulierte wie AMEX, Revolut)"
      },
      "CreditQuelleParam": {
        "name": "quelle",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "API",
          "example": "Make"
        },
        "description": "Kennzeichnung der Aufrufquelle für die Nutzungsanalyse. Standard bei Weglassen: `API` (direkter API-Aufruf). Für Automationen aus Make z. B. `Make` angeben."
      },
      "ConnectionIdParam": {
        "name": "connectionId",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145"
        },
        "description": "UUID der DATEV-Verbindung. Abrufbar über den `/connections`-Endpunkt des jeweiligen Moduls (z. B. `GET /v2/datev-duo/connections`)."
      },
      "CompanyIdParam": {
        "name": "companyId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "example": "386587-29183"
        },
        "description": "Mandanten-ID im Format `<Beraternummer>-<Mandantennummer>`. Nur nötig wenn die Connection mehrere Mandanten umfasst (Steuerberater-Account) und nicht der Default-Mandant gemeint ist. Ohne diesen Parameter nutzt DATEV den beim OAuth gewählten Default-Mandanten — der hat aber je nach Setup keine Export-Subscription, dann kommt 403 zurück."
      }
    },
    "responses": {
      "DatevUnauthorized": {
        "description": "API-Key fehlt, ist ungültig, widerrufen oder abgelaufen. Fehlt der Header `x-api-key`, enthält die Antwort zusätzlich `message`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "examples": {
              "ungueltigerKey": {
                "summary": "Ungültiger oder unbekannter Key",
                "value": {
                  "error": "Ungültiger API-Key"
                }
              },
              "fehlenderHeader": {
                "summary": "Fehlender x-api-key Header",
                "value": {
                  "error": "Fehlende Header",
                  "message": "x-api-key Header ist erforderlich."
                }
              }
            }
          }
        }
      },
      "DatevPaymentRequired": {
        "description": "Nicht genügend Credits für diesen Aufruf.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "Nicht genügend Credits"
            }
          }
        }
      },
      "DatevNoConnection404": {
        "description": "Es ist keine gespeicherte DATEV-Verbindung für die Organisation vorhanden. Der Text in `error` nennt das gewählte DATEV-Produkt (z. B. DATEV Unternehmen Online).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "Keine Verbindung gefunden für DATEV Unternehmen Online"
            }
          }
        }
      },
      "DatevNoConnection404Rewe": {
        "description": "Es ist keine gespeicherte DATEV-Verbindung für das gewählte DATEV Rechnungswesen-Produkt (Read oder Write) vorhanden.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "Keine Verbindung gefunden für DATEV Rechnungswesen - Write"
            }
          }
        }
      },
      "DatevBadGateway502": {
        "description": "Die DATEV-Schnittstelle war kurzzeitig nicht erreichbar (Netzwerk- oder Verbindungsfehler).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "Die DATEV-Schnittstelle ist vorübergehend nicht erreichbar."
            }
          }
        }
      },
      "DatevAsyncTimeout504": {
        "description": "Der asynchrone DATEV-Task wurde nicht innerhalb des Zeitlimits abgeschlossen (max. ca. 40 Sekunden).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "Async-Task-Timeout: Task wurde nicht rechtzeitig abgeschlossen."
            }
          }
        }
      },
      "DatevInternal500": {
        "description": "Unerwarteter Serverfehler oder fehlende Serverkonfiguration für den DATEV-Dienst.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "example": {
              "error": "API-Dienst nicht konfiguriert."
            }
          }
        }
      },
      "DatevServiceError": {
        "description": "Fehlerantwort der DATEV-Schnittstelle (HTTP-Status entspricht der DATEV-Antwort). Der Body enthält `error` und optional `details` mit Zusatzinformationen. Bei 403 wegen fehlendem DATEV Rechnungswesen-Exportservice ist zusätzlich `code = datev_export_service_missing` und `activeSubscriptions` gesetzt.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DatevError"
            },
            "examples": {
              "mitDetails": {
                "summary": "Beispiel mit details",
                "value": {
                  "error": "Validierung fehlgeschlagen",
                  "details": {
                    "message": "…"
                  }
                }
              },
              "exportserviceFehlt": {
                "summary": "403 – DATEV Rechnungswesen-Exportservice nicht abonniert",
                "value": {
                  "error": "DATEV Rechnungswesen-Exportservice ist für diesen Mandanten nicht abonniert. Aktive Services: Belegbilderservice, Rechnungsdatenservice 1.0. Bitte den Service über DATEV beim Mandant aktivieren.",
                  "code": "datev_export_service_missing",
                  "activeSubscriptions": [
                    "Belegbilderservice",
                    "Rechnungsdatenservice 1.0"
                  ],
                  "details": {
                    "errors": [
                      {
                        "message": "RVO-Recht fehlt: Stammdaten"
                      }
                    ]
                  }
                }
              },
              "verbindungUngueltig": {
                "summary": "401 – DATEV-Verbindung ungültig (zur Referenz)",
                "value": {
                  "error": "Die DATEV-Verbindung ist ungültig oder abgelaufen. Bitte im Business OS Dashboard die Verbindung erneuern.",
                  "code": "datev_connection_invalid",
                  "reconnectUrl": "https://app.business-os.de/"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "DATEV Allgemein",
      "description": "Modulübergreifende DATEV-Endpunkte (z. B. Abo-/Service-Diagnose für Mandanten)"
    },
    {
      "name": "DATEV DUO",
      "description": "DATEV Unternehmen Online — Kassenbuch, Belegbilder und Buchungsvorschläge"
    },
    {
      "name": "DATEV ReWe - Write",
      "description": "DATEV Rechnungswesen — Write: Buchungen, Kontakte, Belegtypen, Steuersätze"
    },
    {
      "name": "DATEV ReWe - Read",
      "description": "DATEV Rechnungswesen — Read (Export): Geschäftsjahre und weitere Lesemodule"
    },
    {
      "name": "Banking AIS",
      "description": "Account Information Services — Verbindungen, Kontostände und Transaktionen verwalten"
    },
    {
      "name": "Banking PIS",
      "description": "Payment Initiation Services — Zahlungen ausführen und Status abrufen"
    },
    {
      "name": "Banking Webhooks",
      "description": "Webhook-Konfiguration für Echtzeit-Benachrichtigungen"
    }
  ],
  "paths": {
    "/v2/datev/companies": {
      "get": {
        "tags": [
          "DATEV Allgemein"
        ],
        "summary": "Mandanten und aktive DATEV-Services",
        "description": "Listet alle Mandanten (Companies), die unter der angegebenen DATEV-Verbindung verfügbar sind, samt der je Mandant aktiven Service-Subscriptions (z. B. *Belegbilderservice*, *Rechnungsdatenservice 1.0*, *DATEV Rechnungswesen-Exportservice*).\n\n**Kosten:** 1 Credit pro Aufruf",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Mandanten und deren Service-Subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Mandant-ID in der Form `<Berater-Nr>-<Mandanten-Nr>`",
                            "example": "122130-13170"
                          },
                          "name": {
                            "type": "string",
                            "description": "Name des Mandanten",
                            "example": "Mustermann GmbH"
                          },
                          "client_number": {
                            "type": "integer",
                            "description": "DATEV-Mandanten-Nummer",
                            "example": 13170
                          },
                          "consultant_number": {
                            "type": "integer",
                            "description": "DATEV-Berater-Nummer",
                            "example": 122130
                          },
                          "environmentId": {
                            "type": "string",
                            "nullable": true,
                            "description": "Umgebungs-ID (sofern von DATEV gesetzt)"
                          },
                          "subscription": {
                            "type": "array",
                            "description": "Pro Mandant gebuchte DATEV-Services.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Subscription-ID, falls von DATEV gesetzt"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "Originalname des Services (von DATEV unverändert übernommen)",
                                  "example": "Belegbilderservice"
                                },
                                "status": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Status-Code des Services, falls gesetzt"
                                },
                                "active": {
                                  "type": "boolean",
                                  "description": "True, wenn der Service aktiv abonniert ist"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "subscription": [
                        {
                          "id": null,
                          "name": "Belegbilderservice",
                          "status": null,
                          "active": true
                        },
                        {
                          "id": null,
                          "name": "Rechnungsdatenservice 1.0",
                          "status": null,
                          "active": true
                        }
                      ],
                      "id": "122130-13170",
                      "client_number": 13170,
                      "consultant_number": 122130,
                      "environmentId": null,
                      "name": "Mustermann GmbH"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Fehlender oder ungültiger Query-Parameter (z. B. `connectionId`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "connectionId query parameter ist erforderlich."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/belegtypen": {
      "get": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Belegtypen",
        "description": "Listet alle verfügbaren Belegtypen in DATEV Unternehmen Online.\n\n**Kosten:** 1 Credit pro Aufruf (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Belegtypen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "belegtyp": {
                            "type": "string",
                            "description": "Anzeigename des Belegtyps",
                            "example": "Rechnungseingang"
                          },
                          "belegkreis": {
                            "type": "string",
                            "description": "Maschinenlesbare Kategorie laut Schnittstelle",
                            "example": "invoices_received"
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "description": "Metadaten zur Credit-Abbuchung: verbleibendes Guthaben nach erfolgreicher Buchung",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "belegtyp": "ohne Belegtyp",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "Rechnungseingang",
                      "belegkreis": "invoices_received"
                    },
                    {
                      "belegtyp": "Rechnungsausgang",
                      "belegkreis": "outgoing_invoices"
                    },
                    {
                      "belegtyp": "Kasse",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "Sonstige",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "DATEV Lohn-Unterlagen",
                      "belegkreis": "personnel_documents"
                    },
                    {
                      "belegtyp": "DATEV Reisekosten-Belege",
                      "belegkreis": "travel_expense_documents"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 315
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/kassenbuecher": {
      "get": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Kassenbücher",
        "description": "Listet alle Kassenbücher des Accounts in DATEV Unternehmen Online.\n\n**Kosten:** 1 Credit pro Aufruf (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Kassenbücher",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "bezeichnung": {
                            "type": "string",
                            "nullable": true,
                            "description": "Name des Kassenbuchs",
                            "example": "Kasse"
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "description": "Metadaten zur Credit-Abbuchung: verbleibendes Guthaben nach erfolgreicher Buchung",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "bezeichnung": "Kasse"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/rechnungsordner": {
      "get": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Rechnungsordner",
        "description": "Listet alle Rechnungsordner des Accounts in DATEV Unternehmen Online.\n\n**Kosten:** 1 Credit pro Aufruf (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "name": "typ",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "EINGANGSRECHNUNG",
                "AUSGANGSRECHNUNG"
              ],
              "example": "EINGANGSRECHNUNG"
            },
            "description": "Filtert nach Kreditorenordnern (`EINGANGSRECHNUNG`) oder Debitorenordnern (`AUSGANGSRECHNUNG`)"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Rechnungsordner",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "bezeichnung": {
                            "type": "string",
                            "nullable": true,
                            "description": "Name des Rechnungsordners",
                            "example": "Eingangsrechnungen"
                          },
                          "ordnertyp": {
                            "type": "string",
                            "enum": [
                              "EINGANGSRECHNUNG",
                              "AUSGANGSRECHNUNG"
                            ],
                            "description": "`EINGANGSRECHNUNG` (Kreditorenordner) oder `AUSGANGSRECHNUNG` (Debitorenordner)",
                            "example": "EINGANGSRECHNUNG"
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "description": "Metadaten zur Credit-Abbuchung: verbleibendes Guthaben nach erfolgreicher Buchung",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "bezeichnung": "Eingangsrechnungen",
                      "ordnertyp": "EINGANGSRECHNUNG"
                    },
                    {
                      "bezeichnung": "Ausgangsrechnungen",
                      "ordnertyp": "AUSGANGSRECHNUNG"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "400": {
            "description": "Ungültiger typ-Filter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Ungültiger typ-Filter. Erlaubt: EINGANGSRECHNUNG, AUSGANGSRECHNUNG"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/beleg-bereitstellen": {
      "post": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Beleg bereitstellen",
        "description": "Stellt eine Belegdatei für DATEV Unternehmen Online bereit (Posteingang).\n\n**Kosten:** 1 Credit",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request POST \\\n  --url 'https://api.business-os.de/v2/datev-duo/beleg-bereitstellen?quelle=API' \\\n  --header 'Content-Type: application/json' \\\n  --header 'x-api-key: <api-key>' \\\n  --data '\n{\n  \"datei\": {\n    \"content\": \"JVBERi0xLjQK...\",\n    \"dateiname\": \"rechnung-2025-03.pdf\"\n  },\n  \"belegtyp\": \"Rechnungseingang\",\n  \"id\": \"b5e624e5-fb9e-4836-a443-87a3820f5b48\",\n  \"belegnotiz\": \"Bürobedarf März\"\n}\n'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "datei",
                  "belegtyp"
                ],
                "properties": {
                  "datei": {
                    "type": "object",
                    "required": [
                      "content",
                      "dateiname"
                    ],
                    "properties": {
                      "content": {
                        "type": "string",
                        "description": "Base64-kodierter Dateiinhalt",
                        "example": "JVBERi0xLjQK..."
                      },
                      "dateiname": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Dateiname inkl. Endung. Nur der Basisname, kein Verzeichnispfad; max. 255 Zeichen.",
                        "example": "rechnung-2025-03.pdf"
                      }
                    }
                  },
                  "belegtyp": {
                    "type": "string",
                    "description": "Belegtyp wie das Feld `belegtyp` aus `GET /v2/datev-duo/belegtypen`",
                    "example": "Rechnungseingang"
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optionale GUID zur eindeutigen Identifikation des Dokuments",
                    "example": "b5e624e5-fb9e-4836-a443-87a3820f5b48"
                  },
                  "belegnotiz": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "Optionale Notiz für den Steuerberater (max. 60 Zeichen)",
                    "example": "Bürobedarf März"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Datei erfolgreich hochgeladen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Datei-ID in DATEV",
                      "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    },
                    "dateiname": {
                      "type": "string",
                      "description": "Gespeicherter Dateiname",
                      "example": "rechnung-2025-03.pdf"
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validierungsfehler: fehlende Pflichtfelder (`datei` oder `belegtyp`), ungültiger Dateiname, ungültiges Base64 o. Ä.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "examples": {
                  "fehlendeDaten": {
                    "summary": "datei.content fehlt",
                    "value": {
                      "error": "datei.content ist erforderlich (base64-kodierte Datei)."
                    }
                  },
                  "fehlenderTyp": {
                    "summary": "belegtyp fehlt",
                    "value": {
                      "error": "belegtyp ist erforderlich."
                    }
                  },
                  "ungueltigesBase64": {
                    "summary": "Ungültiges Base64",
                    "value": {
                      "error": "datei.content ist kein gültiges base64."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/kassenbuch-einfach": {
      "post": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Kassenbucheintrag (einfach)",
        "description": "Erstellt einen einfachen Kassenbucheintrag in DATEV Unternehmen Online.\n\n**Kosten:** 1 Credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "waehrung",
                  "kassenname",
                  "belegtext",
                  "betrag",
                  "transaktionsdatum",
                  "belegnummer",
                  "steuersatz",
                  "bewegung"
                ],
                "properties": {
                  "waehrung": {
                    "type": "string",
                    "description": "Währungscode (ISO 4217)",
                    "example": "EUR"
                  },
                  "kassenname": {
                    "type": "string",
                    "description": "Name des Kassenbuchs. Kann aus `GET /v2/datev-duo/kassenbuecher` (Feld `bezeichnung`) ausgelesen werden.",
                    "example": "Kasse"
                  },
                  "belegtext": {
                    "type": "string",
                    "description": "Text zur Buchungsbewegung",
                    "example": "Büromaterial"
                  },
                  "betrag": {
                    "type": "number",
                    "description": "Absolutbetrag; Vorzeichen der Buchung ergibt sich aus `bewegung`.",
                    "example": 49.99
                  },
                  "transaktionsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-03-01T00:00:00Z"
                  },
                  "gegenkonto": {
                    "type": "string",
                    "description": "Sachkonto als Gegenkonto zur Kasse (z. B. Büromaterial).",
                    "example": "4930"
                  },
                  "belegnummer": {
                    "type": "string",
                    "description": "Eindeutige Transaktions-ID. Erlaubte Zeichen: `a-z A-Z 0-9 $ % & * + - /` (max. 36 Zeichen).",
                    "pattern": "^[a-zA-Z0-9$%&*+\\-/]{0,36}$",
                    "example": "TX-12345"
                  },
                  "steuersatz": {
                    "type": "number",
                    "description": "Steuersatz in Prozent",
                    "example": 19
                  },
                  "bewegung": {
                    "type": "string",
                    "description": "Nur exakt `EINNAHME` oder `AUSGABE` (Großschreibung).",
                    "enum": [
                      "EINNAHME",
                      "AUSGABE"
                    ],
                    "example": "AUSGABE"
                  },
                  "belegNummer": {
                    "type": "string",
                    "description": "Kann die Belegnummer enthalten.",
                    "example": "INV-123"
                  },
                  "belegbilder": {
                    "type": "array",
                    "description": "Optionale Belegbilder (Quittungen)",
                    "items": {
                      "type": "object",
                      "required": [
                        "content"
                      ],
                      "properties": {
                        "content": {
                          "type": "string",
                          "description": "Base64-kodierter Dateiinhalt"
                        },
                        "dateiname": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "Dateiname inkl. Endung",
                          "example": "quittung-buero.pdf"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Kassenbucheintrag erfolgreich erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "belegnummer": {
                      "type": "string",
                      "example": "TX-12345"
                    },
                    "kassenname": {
                      "type": "string",
                      "example": "Kasse"
                    },
                    "transaktionsdatum": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2025-03-01T00:00:00Z"
                    },
                    "bewegung": {
                      "type": "string",
                      "example": "AUSGABE"
                    },
                    "betrag": {
                      "type": "number",
                      "example": -49.99
                    },
                    "waehrung": {
                      "type": "string",
                      "example": "EUR"
                    },
                    "belegtext": {
                      "type": "string",
                      "example": "Büromaterial"
                    },
                    "gegenkonto": {
                      "type": "string",
                      "example": "4930"
                    },
                    "belegNummer": {
                      "type": "string",
                      "example": "INV-123"
                    },
                    "steuersatz": {
                      "type": "number",
                      "example": 19
                    },
                    "belegbilder": {
                      "type": "array",
                      "description": "Metadaten zu hochgeladenen Belegbildern (Form je nach Schnittstelle)",
                      "items": {
                        "type": "object",
                        "properties": {
                          "dateiname": {
                            "type": "string",
                            "description": "Dateiname des Belegbilds",
                            "example": "quittung-buero.pdf"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "datevAntwort": {
                      "description": "Ergebnis des DATEV-Async-Tasks. `null`, wenn kein Task gepollt wurde.",
                      "nullable": true,
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DatevAntwortKassenbuch"
                        }
                      ]
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "belegnummer": "TX-12345",
                  "kassenname": "Kasse",
                  "transaktionsdatum": "2025-03-01T00:00:00Z",
                  "bewegung": "AUSGABE",
                  "betrag": -49.99,
                  "waehrung": "EUR",
                  "belegtext": "Büromaterial",
                  "gegenkonto": "4930",
                  "belegNummer": "INV-123",
                  "steuersatz": 19,
                  "belegbilder": [
                    {
                      "dateiname": "quittung-buero.pdf"
                    }
                  ],
                  "datevAntwort": {
                    "status": "ERFOLGREICH",
                    "meldungen": [
                      {
                        "dateiname": "quittung-buero.pdf",
                        "nachricht": "Beleg erfolgreich an das Kassenbuch übergeben.",
                        "zeitstempel": "2023-11-07T05:31:56Z",
                        "typ": "INFO"
                      }
                    ]
                  },
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende oder ungültige Pflichtfelder im JSON-Body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Fehlende Pflichtfelder: waehrung, kassenname, belegtext, betrag, transaktionsdatum, belegnummer, steuersatz, bewegung"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "$ref": "#/components/responses/DatevAsyncTimeout504"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/kassenbuch-advanced": {
      "post": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Kassenbucheintrag (advanced)",
        "description": "Erstellt einen erweiterten Kassenbucheintrag mit strukturierten buchhalterischen Daten in DATEV Unternehmen Online.\n\n**Kosten:** 1 Credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "waehrung",
                  "kassenname",
                  "betrag",
                  "transaktionsdatum",
                  "belegzeilen"
                ],
                "properties": {
                  "waehrung": {
                    "type": "string",
                    "example": "EUR"
                  },
                  "kassenname": {
                    "type": "string",
                    "description": "Name des Kassenbuchs. Kann aus `GET /v2/datev-duo/kassenbuecher` (Feld `bezeichnung`) ausgelesen werden.",
                    "example": "Kasse"
                  },
                  "betrag": {
                    "type": "number",
                    "description": "Der Transaktionsbetrag. Muss gleich der Summe der einzelnen Belegzeilen entsprechen. Ein positiver Wert stellt eine Einnahme dar, ein negativer Wert eine Ausgabe.",
                    "example": 119
                  },
                  "transaktionsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-03-01T00:00:00Z"
                  },
                  "belegzeilen": {
                    "type": "array",
                    "description": "Liste der Belegzeilen. Für jede Belegzeile wird ein Kassenbucheintrag erstellt.",
                    "items": {
                      "type": "object",
                      "required": [
                        "belegtext"
                      ],
                      "properties": {
                        "gegenkonto": {
                          "type": "string",
                          "description": "Sachkonto als Gegenkonto zur Kasse",
                          "example": "4930"
                        },
                        "belegtext": {
                          "type": "string",
                          "description": "Buchungstext zur Position",
                          "example": "Büromaterial"
                        },
                        "belegNummer": {
                          "type": "string",
                          "description": "Optionale Beleg- bzw. Dokumentnummer für diese Belegzeile.",
                          "example": "INV-123"
                        },
                        "betrag": {
                          "type": "number",
                          "description": "Bruttobetrag der Belegzeile.",
                          "example": 119
                        },
                        "steuersatz": {
                          "type": "object",
                          "description": "Steuerangaben pro Zeile.",
                          "properties": {
                            "prozent": {
                              "type": "number",
                              "description": "Steuersatz in Prozent",
                              "example": 19
                            },
                            "buSchluessel": {
                              "type": "string",
                              "description": "DATEV-BU-Schlüssel",
                              "example": "3"
                            }
                          }
                        },
                        "kostenstelle1": {
                          "type": "string",
                          "description": "Kostenstelle 1"
                        },
                        "kostenstelle2": {
                          "type": "string",
                          "description": "Kostenstelle 2"
                        }
                      }
                    }
                  },
                  "belegbilder": {
                    "type": "array",
                    "description": "Optionale Belegbilder (Quittungen/Dokumente)",
                    "items": {
                      "type": "object",
                      "required": [
                        "content"
                      ],
                      "properties": {
                        "content": {
                          "type": "string",
                          "description": "Base64-kodierter Dateiinhalt"
                        },
                        "dateiname": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "Dateiname inkl. Endung. Nur der Basisname, kein Verzeichnispfad; max. 255 Zeichen.",
                          "example": "beleg.pdf"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Kassenbucheintrag (advanced) erfolgreich erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "erstellungsdatum": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "waehrung": {
                      "type": "string",
                      "example": "EUR"
                    },
                    "belegzeilen": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "gegenkonto": {
                            "type": "string"
                          },
                          "erstellungsdatum": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "waehrung": {
                            "type": "string"
                          },
                          "belegtext": {
                            "type": "string"
                          },
                          "belegnummer": {
                            "type": "string"
                          },
                          "betrag": {
                            "type": "number"
                          },
                          "steuersatz": {
                            "type": "object",
                            "properties": {
                              "prozent": {
                                "type": "number",
                                "description": "Steuersatz in Prozent"
                              },
                              "buSchluessel": {
                                "type": "string",
                                "description": "DATEV-BU-Schlüssel"
                              }
                            }
                          },
                          "kostenstellen": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "belegbilder": {
                      "type": "array",
                      "description": "Metadaten zu hochgeladenen Belegbildern",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "kassenname": {
                      "type": "string"
                    },
                    "betrag": {
                      "type": "number"
                    },
                    "transaktionsdatum": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "datevAntwort": {
                      "description": "Ergebnis des DATEV-Async-Tasks. `null`, wenn kein Task gepollt wurde.",
                      "nullable": true,
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DatevAntwortKassenbuch"
                        }
                      ]
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende oder ungültige Pflichtfelder im JSON-Body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Fehlende Pflichtfelder: waehrung, kassenname, betrag, transaktionsdatum, belegzeilen"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "$ref": "#/components/responses/DatevAsyncTimeout504"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/buchungsvorschlag": {
      "post": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Buchungsvorschlag",
        "description": "Erstellt einen Buchungsvorschlag über DATEV Unternehmen Online.\n\nDie strukturierten Daten werden direkt als Buchungsvorschlag angezeigt und können mit einem Klick verbucht werden.\n\n**Kosten:** 1 Credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "belegdatum",
                  "waehrung",
                  "rechnungsordner",
                  "belegnummer",
                  "betrag",
                  "positionen",
                  "belegtyp"
                ],
                "properties": {
                  "belegdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Belegdatum (z. B. Rechnungsdatum). ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-03-01T00:00:00Z"
                  },
                  "waehrung": {
                    "type": "string",
                    "description": "Währungscode nach ISO 4217.",
                    "example": "EUR"
                  },
                  "rechnungsordner": {
                    "type": "string",
                    "description": "Name des Rechnungsordners. Muss zum Buchungstyp passen: bei `EINGANGSRECHNUNG` ein Kreditorenordner, bei `AUSGANGSRECHNUNG` ein Debitorenordner. Kann aus `GET /v2/datev-duo/rechnungsordner` (Feld `bezeichnung`) ausgelesen werden.",
                    "example": "Eingangsrechnungen"
                  },
                  "belegnummer": {
                    "type": "string",
                    "description": "Belegnummer / Rechnungsnummer.",
                    "maxLength": 36,
                    "pattern": "^[a-zA-Z0-9$%&*+\\-/]{0,36}$",
                    "example": "RE-2025-001"
                  },
                  "betrag": {
                    "type": "number",
                    "description": "Gesamtbetrag brutto (wie bei anderen DUO-Belegen). Darf nicht 0 sein und muss der Summe der Positionsbeträge (`positionen[].betrag`) entsprechen. Max. 10 Vorkomma- und 2 Nachkommastellen.",
                    "example": 119
                  },
                  "positionen": {
                    "type": "array",
                    "description": "Belegpositionen — mindestens eine Position erforderlich.",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "betrag"
                      ],
                      "properties": {
                        "betrag": {
                          "type": "number",
                          "description": "Bruttobetrag dieser Position. Darf nicht 0 sein. Max. 10 Vorkomma- und 2 Nachkommastellen.",
                          "example": 119
                        },
                        "belegtext": {
                          "type": "string",
                          "description": "Positionstext, max. 60 Zeichen.",
                          "maxLength": 60,
                          "example": "Büromaterial"
                        },
                        "steuersatzProzent": {
                          "type": "number",
                          "description": "Steuersatz in Prozent (z. B. 19 für 19 %).",
                          "example": 19
                        },
                        "skontoBetrag": {
                          "type": "number",
                          "description": "Fester Skontobetrag (Skonto 1). Positiv, max. 8 Vorkomma- und 2 Nachkommastellen. Darf den Positionsbetrag nicht überschreiten. Erfordert `skontoZahlungsdatum` auf Belegebene."
                        },
                        "skontoProzent": {
                          "type": "number",
                          "description": "Skontosatz in Prozent (Skonto 1). Max. 2 Vorkomma- und 2 Nachkommastellen, max. 100 %. Erfordert `skontoZahlungsdatum` auf Belegebene."
                        },
                        "skontoBetrag2": {
                          "type": "number",
                          "description": "Fester Skontobetrag (Skonto 2). Darf `skontoBetrag` und den Positionsbetrag nicht überschreiten. Erfordert `skontoZahlungsdatum2` auf Belegebene."
                        },
                        "skontoProzent2": {
                          "type": "number",
                          "description": "Skontosatz in Prozent (Skonto 2). Muss kleiner als `skontoProzent` sein. Erfordert `skontoZahlungsdatum2` auf Belegebene."
                        },
                        "kontoname": {
                          "type": "string",
                          "description": "Name des Sachkontos, max. 40 Zeichen.",
                          "maxLength": 40
                        },
                        "kontonummer": {
                          "type": "number",
                          "description": "Sachkontonummer. Die Länge muss der konfigurierten Kontenlänge entsprechen."
                        },
                        "buSchluessel": {
                          "type": "string",
                          "description": "DATEV-Buchungsschlüssel (BU-Code). Max. 4 Zeichen, nur Ziffern.",
                          "maxLength": 4,
                          "pattern": "^[0-9]{0,4}$"
                        },
                        "kostenstelle1": {
                          "type": "string",
                          "description": "Kostenstelle 1 (KOST1), max. 36 Zeichen.",
                          "maxLength": 36,
                          "example": "Marketing"
                        },
                        "kostenstelle2": {
                          "type": "string",
                          "description": "Kostenstelle 2 (KOST2), max. 36 Zeichen.",
                          "maxLength": 36,
                          "example": "IT-Abteilung"
                        }
                      }
                    }
                  },
                  "belegtyp": {
                    "type": "string",
                    "enum": [
                      "EINGANGSRECHNUNG",
                      "AUSGANGSRECHNUNG"
                    ],
                    "description": "`EINGANGSRECHNUNG` = Eingangsrechnung (Kreditor), `AUSGANGSRECHNUNG` = Ausgangsrechnung (Debitor).",
                    "example": "EINGANGSRECHNUNG"
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optionale UUID zur Zuordnung von hochgeladenen Dateien zum Buchungsvorschlag. Muss eine gültige UUID sein, wird andernfalls ignoriert."
                  },
                  "adressen": {
                    "type": "array",
                    "description": "Optionale Adressen.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "stadt": {
                          "type": "string",
                          "description": "Ort, max. 30 Zeichen.",
                          "maxLength": 30
                        }
                      }
                    }
                  },
                  "bankkontonummer": {
                    "type": "number",
                    "description": "Bankkontonummer (1–10 Ziffern). Wenn angegeben, ist `bankleitzahl` erforderlich."
                  },
                  "bankleitzahl": {
                    "type": "string",
                    "description": "Bankleitzahl. Wenn angegeben, ist `bankkontonummer` erforderlich.",
                    "pattern": "^([1-9]|[0-9]{2,10})$"
                  },
                  "bic": {
                    "type": "string",
                    "description": "BIC-Code.",
                    "pattern": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{0,3}$",
                    "example": "DEUTDEFF"
                  },
                  "iban": {
                    "type": "string",
                    "description": "IBAN.",
                    "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
                    "example": "DE89370400440532013000"
                  },
                  "kontaktKontonummer": {
                    "type": "number",
                    "description": "Kreditoren- oder Debitorennummer des Geschäftspartners."
                  },
                  "kontaktName": {
                    "type": "string",
                    "description": "Name des Geschäftspartners, max. 50 Zeichen.",
                    "maxLength": 50
                  },
                  "lieferdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Liefer- bzw. Leistungsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339)."
                  },
                  "faelligkeitsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Fälligkeitsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss nach `belegdatum` liegen. Pflicht, wenn Skonto-Felder verwendet werden."
                  },
                  "skontoZahlungsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Zahlungsziel für Skonto 1. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss vor `faelligkeitsdatum` und nach `belegdatum` liegen. Erfordert `skontoBetrag` und `skontoProzent` in jeder Position."
                  },
                  "skontoZahlungsdatum2": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Zahlungsziel für Skonto 2. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Muss vor `faelligkeitsdatum` und nach `skontoZahlungsdatum` liegen. Erfordert zusätzlich `skontoBetrag2` und `skontoProzent2` in jeder Position."
                  },
                  "zahlungsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Zahlungsdatum — markiert den Beleg als bezahlt. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339)."
                  },
                  "istZahlungsauftrag": {
                    "type": "boolean",
                    "description": "Ob automatisch eine Zahlungsanweisung (Überweisung bei `EINGANGSRECHNUNG`, Lastschrift bei `AUSGANGSRECHNUNG`) erstellt werden soll. Muss `false` sein, wenn `zahlungsbedingungenId` = 9."
                  },
                  "notizen": {
                    "type": "string",
                    "description": "Zusätzliche Notizen zum Buchungsvorschlag, max. 120 Zeichen.",
                    "maxLength": 120
                  },
                  "bestellId": {
                    "type": "string",
                    "description": "Bestell- bzw. Auftrags-ID.",
                    "maxLength": 30,
                    "pattern": "^[a-zA-Z0-9$%&*+\\-./]{1,30}$"
                  },
                  "zahlungsbedingungenId": {
                    "type": "string",
                    "description": "Kennung der Zahlungsbedingungen (max. 3 Ziffern). Wenn gesetzt, dürfen keine Skonto-Felder verwendet werden.",
                    "maxLength": 3,
                    "pattern": "^[0-9]{1,3}$"
                  },
                  "ustId": {
                    "type": "string",
                    "description": "USt-IdNr. des Geschäftspartners.",
                    "maxLength": 15,
                    "pattern": "^[0-9a-zA-Z. _]{1,15}$"
                  },
                  "ordnerVerwaltung": {
                    "type": "object",
                    "description": "Optionale dreistufige Ordnerstruktur für die Belegablage. Ohne Angabe wird die Standardstruktur verwendet.",
                    "required": [
                      "kategorie",
                      "ordner",
                      "register"
                    ],
                    "properties": {
                      "kategorie": {
                        "type": "string",
                        "description": "Oberste Ebene der Ordnerstruktur."
                      },
                      "ordner": {
                        "type": "string",
                        "description": "Zweite Ebene der Ordnerstruktur."
                      },
                      "register": {
                        "type": "string",
                        "description": "Dritte Ebene der Ordnerstruktur."
                      }
                    }
                  },
                  "belegbilder": {
                    "type": "array",
                    "description": "Optionale Belegdateien (z. B. PDF-Rechnungen).",
                    "items": {
                      "type": "object",
                      "required": [
                        "content"
                      ],
                      "properties": {
                        "content": {
                          "type": "string",
                          "description": "Base64-kodierter Dateiinhalt."
                        },
                        "dateiname": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "Dateiname inkl. Endung (nur Basisname, max. 255 Zeichen).",
                          "example": "rechnung.pdf"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Buchungsvorschlag erfolgreich erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "nullable": true
                    },
                    "adressen": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "type": "object",
                        "properties": {
                          "stadt": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "belegdatum": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "belegtyp": {
                      "type": "string",
                      "enum": [
                        "EINGANGSRECHNUNG",
                        "AUSGANGSRECHNUNG"
                      ],
                      "example": "EINGANGSRECHNUNG",
                      "nullable": true
                    },
                    "kontaktKontonummer": {
                      "type": "number",
                      "nullable": true
                    },
                    "kontaktName": {
                      "type": "string",
                      "nullable": true
                    },
                    "erstellungsdatum": {
                      "type": "string",
                      "nullable": true
                    },
                    "waehrung": {
                      "type": "string",
                      "example": "EUR",
                      "nullable": true
                    },
                    "lieferdatum": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "skontoZahlungsdatum": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "skontoZahlungsdatum2": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "faelligkeitsdatum": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "belegbilder": {
                      "nullable": true
                    },
                    "iban": {
                      "type": "string",
                      "nullable": true
                    },
                    "bankkontonummer": {
                      "type": "number",
                      "nullable": true
                    },
                    "bankleitzahl": {
                      "type": "string",
                      "nullable": true
                    },
                    "bic": {
                      "type": "string",
                      "nullable": true
                    },
                    "istZahlungsauftrag": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "rechnungsordner": {
                      "type": "string",
                      "nullable": true
                    },
                    "positionen": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "type": "object",
                        "properties": {
                          "erstellungsdatum": {
                            "type": "string",
                            "nullable": true
                          },
                          "belegtext": {
                            "type": "string",
                            "nullable": true
                          },
                          "betrag": {
                            "type": "number",
                            "nullable": true
                          },
                          "steuersatzProzent": {
                            "type": "number",
                            "nullable": true
                          },
                          "skontoBetrag": {
                            "type": "number",
                            "nullable": true
                          },
                          "skontoProzent": {
                            "type": "number",
                            "nullable": true
                          },
                          "skontoBetrag2": {
                            "type": "number",
                            "nullable": true
                          },
                          "skontoProzent2": {
                            "type": "number",
                            "nullable": true
                          },
                          "kontoname": {
                            "type": "string",
                            "nullable": true
                          },
                          "kontonummer": {
                            "type": "number",
                            "nullable": true
                          },
                          "buSchluessel": {
                            "type": "string",
                            "nullable": true
                          },
                          "kostenstelle1": {
                            "type": "string",
                            "nullable": true
                          },
                          "kostenstelle2": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "belegnummer": {
                      "type": "string",
                      "example": "RE-2025-001",
                      "nullable": true
                    },
                    "notizen": {
                      "type": "string",
                      "nullable": true
                    },
                    "bestellId": {
                      "type": "string",
                      "nullable": true
                    },
                    "zahlungsdatum": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "zahlungsbedingungenId": {
                      "type": "string",
                      "nullable": true
                    },
                    "aufgabenId": {
                      "type": "string",
                      "nullable": true
                    },
                    "betrag": {
                      "type": "number",
                      "example": 119,
                      "nullable": true
                    },
                    "ustId": {
                      "type": "string",
                      "nullable": true
                    },
                    "datevAntwort": {
                      "description": "Ergebnis des DATEV-Async-Tasks. `null`, wenn kein Task gepollt wurde.",
                      "nullable": true,
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DatevAntwort"
                        }
                      ]
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende oder ungültige Pflichtfelder im JSON-Body (inkl. Validierung des Buchungsvorschlags).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Fehlende Pflichtfelder: belegdatum, waehrung, rechnungsordner, belegnummer, betrag, positionen, belegtyp"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "$ref": "#/components/responses/DatevAsyncTimeout504"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-duo/connections": {
      "get": {
        "tags": [
          "DATEV DUO"
        ],
        "summary": "Verbindungen",
        "description": "Gibt alle Verbindungen der Organisation für **DATEV Unternehmen Online** zurück.\n\n**Kosten:** 0 Credits",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Liste der Verbindungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "UUID der Verbindung",
                            "example": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145"
                          },
                          "organization_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "Organisations-ID des Mandanten. **Nur bei Agency-Scope** gesetzt (Aufruf mit `x-agency-id`-Header oder Agency-API-Key) — dann sehen Agency-Mitglieder, zu welcher Mandanten-Org die Connection gehört. Bei normalen Org-API-Calls weggelassen.",
                            "example": "01941b8a-c428-7e9a-9c1c-2a8c5a8c9e10"
                          },
                          "bezeichnung": {
                            "type": "string",
                            "nullable": true,
                            "description": "Optionale Bezeichnung der Verbindung",
                            "example": "Mandant Müller GmbH"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "connected",
                              "pending"
                            ],
                            "description": "`connected` wenn Verbindung aktiv, `pending` wenn OAuth noch nicht abgeschlossen"
                          },
                          "verbunden_seit": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der letzten erfolgreichen Verbindung (ISO 8601). `null` bei `pending`.",
                            "example": "2026-04-05T21:47:29Z"
                          },
                          "erstellt_am": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der Erstellung (ISO 8601)",
                            "example": "2026-03-27T09:31:04Z"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "connections": [
                    {
                      "id": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145",
                      "bezeichnung": "Mandant Müller GmbH",
                      "status": "connected",
                      "verbunden_seit": "2026-04-05T21:47:29Z",
                      "erstellt_am": "2026-03-27T09:31:04Z"
                    },
                    {
                      "id": "8e563966-79d1-4dbf-9d7f-f23e43351bdd",
                      "bezeichnung": null,
                      "status": "pending",
                      "verbunden_seit": null,
                      "erstellt_am": "2026-04-01T10:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          }
        }
      }
    },
    "/v2/datev-rewe/belegtypen": {
      "get": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Belegtypen",
        "description": "Listet alle verfügbaren Belegtypen für Datei-Uploads in DATEV Rechnungswesen.\n\n**Kosten:** 1 Credit pro Aufruf (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Belegtypen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "belegtyp": {
                            "type": "string",
                            "description": "Anzeigename des Belegtyps (u. a. für Uploads)",
                            "example": "Rechnungseingang"
                          },
                          "belegkreis": {
                            "type": "string",
                            "description": "Maschinenlesbare Kategorie laut Schnittstelle",
                            "example": "invoices_received"
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "description": "Metadaten zur Credit-Abbuchung: verbleibendes Guthaben nach erfolgreicher Buchung",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "belegtyp": "ohne Belegtyp",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "Rechnungseingang",
                      "belegkreis": "invoices_received"
                    },
                    {
                      "belegtyp": "Rechnungsausgang",
                      "belegkreis": "outgoing_invoices"
                    },
                    {
                      "belegtyp": "Kasse",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "Sonstige",
                      "belegkreis": "other_documents"
                    },
                    {
                      "belegtyp": "DATEV Lohn-Unterlagen",
                      "belegkreis": "personnel_documents"
                    },
                    {
                      "belegtyp": "DATEV Reisekosten-Belege",
                      "belegkreis": "travel_expense_documents"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 315
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe/steuersaetze": {
      "get": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Steuersätze",
        "description": "Gibt alle verfügbaren Steuersätze für den verbundenen Mandanten zurück. Erfordert die **Write**-Verbindung zu DATEV Rechnungswesen.\n\n**Kosten:** 1 Credit (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Steuersätze",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "buSchluessel": {
                            "type": "string",
                            "description": "BU-Schlüssel (Steuersatz-Kennzeichen)",
                            "example": "03"
                          },
                          "beschreibung": {
                            "type": "string",
                            "description": "Bezeichnung des Steuersatzes",
                            "example": "19% Vorsteuer"
                          },
                          "prozentsatz": {
                            "type": "number",
                            "description": "Prozentualer Steuersatz",
                            "example": 19
                          },
                          "verwendung": {
                            "type": "string",
                            "enum": [
                              "Kassenbuch",
                              "Eingangsrechnung",
                              "Ausgangsrechnung"
                            ],
                            "description": "Belegkontext, in dem dieser Steuersatz gilt: `Kassenbuch`, `Eingangsrechnung` oder `Ausgangsrechnung`.",
                            "example": "Ausgangsrechnung"
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe/beleg-bereitstellen": {
      "post": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Beleg bereitstellen",
        "description": "Stellt eine Belegdatei (z. B. PDF-Rechnung) in DATEV Rechnungswesen bereit.\n\n**Kosten:** 1 Credit pro Aufruf",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "datei",
                  "belegdatum",
                  "belegtyp"
                ],
                "properties": {
                  "datei": {
                    "type": "object",
                    "required": [
                      "content",
                      "dateiname"
                    ],
                    "properties": {
                      "content": {
                        "type": "string",
                        "description": "Base64-kodierter Dateiinhalt."
                      },
                      "dateiname": {
                        "type": "string",
                        "description": "Dateiname inkl. Erweiterung (z. B. `rechnung.pdf`).",
                        "example": "rechnung.pdf"
                      }
                    }
                  },
                  "belegdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Belegdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-03-15T00:00:00Z"
                  },
                  "belegtyp": {
                    "type": "string",
                    "description": "Belegtyp — muss einem `belegtyp`-Wert aus `GET /v2/datev-rewe/belegtypen` entsprechen.",
                    "example": "Rechnungseingang"
                  },
                  "belegId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUID zur eindeutigen Identifikation des Belegs."
                  },
                  "belegnotiz": {
                    "type": "string",
                    "description": "Notiz zum Beleg (max. 60 Zeichen)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Beleg erfolgreich bereitgestellt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "ID der bereitgestellten Belegdatei",
                      "example": "768E0E789A70499B91729C4516143135"
                    },
                    "dateiname": {
                      "type": "string",
                      "nullable": true,
                      "description": "Dateiname der bereitgestellten Datei",
                      "example": "rechnung.pdf"
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende Pflichtfelder.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Fehlende Pflichtfelder: datei.content, belegdatum"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/geschaeftsjahre": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Geschäftsjahre",
        "description": "Listet alle Geschäftsjahre in dem ausgewählten DATEV Rechnungswesen Account.\n\n**Kosten:** 1 Credit (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Geschäftsjahre",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Geschäftsjahr-ID",
                            "example": "20260101"
                          },
                          "startDatum": {
                            "type": "string",
                            "format": "date",
                            "example": "2026-01-01"
                          }
                        },
                        "required": [
                          "id",
                          "startDatum"
                        ]
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "description": "Metadaten zur Credit-Abbuchung",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/geschaeftsjahre/{geschaeftsjahrId}": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Geschäftsjahr (Detail)",
        "description": "Ruft detaillierte Informationen eines einzelnen Geschäftsjahrs anhand der ID ab.\n\n**Kosten:** 1 Credit (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          },
          {
            "name": "geschaeftsjahrId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "20260101"
            },
            "description": "Identifikator des Geschäftsjahrs – entspricht dem Feld `id` eines Eintrags aus der Antwort von `GET /v2/datev-rewe-read/geschaeftsjahre`."
          }
        ],
        "responses": {
          "200": {
            "description": "Einzelnes Geschäftsjahr",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Eindeutige ID des Geschäftsjahrs",
                          "example": "20260101"
                        },
                        "kontonummernLaenge": {
                          "type": "integer",
                          "description": "Länge der Kontonummer (Anzahl Stellen)",
                          "example": 4
                        },
                        "kontenrahmen": {
                          "type": "string",
                          "description": "Verwendeter Kontenrahmen",
                          "enum": [
                            "SKR03",
                            "SKR04",
                            "SKR51",
                            "SKR14",
                            "SKR42"
                          ],
                          "example": "SKR03"
                        },
                        "endDatum": {
                          "type": "string",
                          "format": "date",
                          "description": "Letzter Tag des Geschäftsjahrs",
                          "example": "2026-12-31"
                        },
                        "startDatum": {
                          "type": "string",
                          "format": "date",
                          "description": "Erster Tag des Geschäftsjahrs",
                          "example": "2026-01-01"
                        }
                      },
                      "required": [
                        "id",
                        "kontonummernLaenge",
                        "kontenrahmen",
                        "endDatum",
                        "startDatum"
                      ]
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/zahlungsbedingungen": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Zahlungsbedingungen",
        "description": "Listet Zahlungsbedingungen für das angegebene Geschäftsjahr.\n\n**Kosten:** 1 Credit (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request GET \\\n  --url 'https://api.business-os.de/v2/datev-rewe-read/zahlungsbedingungen?geschaeftsjahrStartDatum=2026-01-01&quelle=API' \\\n  --header 'x-api-key: <api-key>'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "geschaeftsjahrStartDatum",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01",
            "description": "Startdatum des Geschäftsjahrs (YYYY-MM-DD)."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Zahlungsbedingungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ZahlungsbedingungRead"
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlendes oder ungültiges geschaeftsjahrStartDatum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Query-Parameter geschaeftsjahrStartDatum ist erforderlich (Format YYYY-MM-DD, entspricht dem Startdatum des Geschäftsjahrs)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/kontenplan": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Kontenplan",
        "description": "Listet Sach- und Personenkonten für das angegebene Geschäftsjahr.\n\n**Kosten:** 1 Credit (entfällt bei Nutzung als Make-Dropdown/RPC)",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request GET \\\n  --url 'https://api.business-os.de/v2/datev-rewe-read/kontenplan?geschaeftsjahrStartDatum=2026-01-01&quelle=API' \\\n  --header 'x-api-key: <api-key>'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "geschaeftsjahrStartDatum",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01",
            "description": "Startdatum des Geschäftsjahrs (YYYY-MM-DD)."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Kontenplan: Liste der Sach- und Personenkonten",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KontoRead"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "description": "Metadaten der DATEV-Schnittstelle (z.B. Pagination-Hinweise), nur wenn geliefert.",
                      "additionalProperties": true
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "kontobeschriftung": "Fällige Einzahlung auf Geschäftsanteile",
                      "kontonummer": "50000"
                    },
                    {
                      "kontobeschriftung": "EDV-Software, entgeltl. erworben",
                      "kontonummer": "270000"
                    },
                    {
                      "kontobeschriftung": "Gew. Schutzrechte, entgeltl. erworben",
                      "kontonummer": "200000"
                    },
                    {
                      "kontobeschriftung": "Rüttinger Maschinenmusterbau",
                      "kontonummer": "901000000"
                    },
                    {
                      "kontobeschriftung": "Levkowitzmuster KG",
                      "kontonummer": "915000000"
                    },
                    {
                      "kontobeschriftung": "Hubertest Installationen",
                      "kontonummer": "920000000"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 336
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlendes oder ungültiges geschaeftsjahrStartDatum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Query-Parameter geschaeftsjahrStartDatum ist erforderlich (Format YYYY-MM-DD, entspricht dem Startdatum des Geschäftsjahrs)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/bwa": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "BWA (Betriebswirtschaftliche Auswertung)",
        "description": "Aggregiert die Summen- und Saldenliste (aktuelles Geschäftsjahr + Vorjahr) zur **DATEV-Standard-BWA Form 01 (\"Kurzfristige Erfolgsrechnung\")** mit standardisierter SKR03/SKR04-Zuordnung.\n\nPerioden-orientierte Ausgabe je nach `einheit` (Monat/Quartal/Jahr) mit Veränderung zur Vorperiode (PoP) und zum Vorjahr (YoY) je Position.\n\n**Wichtig:** Dies ist **nicht** die kanzleiindividuelle DATEV-BWA des Steuerberaters, sondern eine standardisierte Auswertung auf Basis der Summen- und Saldenliste — sie kann von der offiziellen BWA abweichen. Keine steuerliche Beratung.\n\nNur für Mandanten mit Kontenrahmen **SKR03 oder SKR04** (sonst `verfuegbar: false`). Der Kontenrahmen wird automatisch aus dem Kontenplan erkannt.\n\n**Kosten:** 1 Credit",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request GET \\\n  --url 'https://api.business-os.de/v2/datev-rewe-read/bwa?geschaeftsjahrStartDatum=2025-01-01&einheit=monat&quelle=API' \\\n  --header 'x-api-key: <api-key>'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "geschaeftsjahrStartDatum",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2025-01-01",
            "description": "Startdatum des Geschäftsjahrs (YYYY-MM-DD). Das Vorjahr (für YoY) wird automatisch abgeleitet."
          },
          {
            "name": "einheit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "monat",
                "quartal",
                "jahr"
              ],
              "default": "monat"
            },
            "example": "monat",
            "description": "Perioden-Granularität der Ausgabe. Default: monat."
          },
          {
            "name": "kontenrahmen",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "SKR03",
                "SKR04"
              ]
            },
            "description": "Optionaler Override. Ohne Angabe wird der Kontenrahmen aus dem Kontenplan erkannt."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "BWA-Auswertung (oder `verfuegbar: false` bei nicht unterstütztem Kontenrahmen)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verfuegbar": {
                      "type": "boolean",
                      "description": "false, wenn der Kontenrahmen nicht SKR03/SKR04 ist oder keine Daten vorliegen."
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "kontenrahmen": {
                          "type": "string",
                          "enum": [
                            "SKR03",
                            "SKR04"
                          ]
                        },
                        "kontenrahmen_quelle": {
                          "type": "string",
                          "enum": [
                            "inferiert_aus_kontenplan",
                            "explizit"
                          ]
                        },
                        "kontonummer_laenge": {
                          "type": "integer",
                          "example": 8
                        },
                        "einheit": {
                          "type": "string",
                          "enum": [
                            "monat",
                            "quartal",
                            "jahr"
                          ]
                        },
                        "geschaeftsjahr": {
                          "type": "object",
                          "properties": {
                            "jahr": {
                              "type": "integer"
                            },
                            "start": {
                              "type": "string",
                              "format": "date"
                            }
                          }
                        },
                        "vorjahr": {
                          "type": "integer",
                          "nullable": true
                        },
                        "letzte_periode_mit_daten": {
                          "type": "integer",
                          "example": 12
                        },
                        "waehrung": {
                          "type": "string",
                          "example": "EUR"
                        },
                        "disclaimer": {
                          "type": "string"
                        },
                        "quelle": {
                          "type": "string"
                        },
                        "mapping_version": {
                          "type": "string",
                          "example": "skr03-bwa-v1"
                        }
                      }
                    },
                    "perioden": {
                      "type": "array",
                      "description": "Perioden-Achse (Spalten) gemäß einheit. Bei monat/quartal aus dem GJ-Start auf echte Monate gemappt.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string",
                            "example": "2025-01"
                          },
                          "label": {
                            "type": "string",
                            "example": "Jan 2025"
                          },
                          "typ": {
                            "type": "string",
                            "enum": [
                              "monat",
                              "quartal",
                              "jahr"
                            ]
                          },
                          "periode_nr": {
                            "type": "integer"
                          },
                          "hat_daten": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "zeilen": {
                      "type": "array",
                      "description": "BWA-Staffel in Reihenfolge. Konten-Zeilen tragen konten[], Aggregat-Zeilen formel[].",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string",
                            "example": "umsatz"
                          },
                          "label": {
                            "type": "string",
                            "example": "Umsatzerlöse"
                          },
                          "typ": {
                            "type": "string",
                            "enum": [
                              "pos",
                              "neg",
                              "kost",
                              "sum",
                              "sumneg",
                              "result",
                              "final"
                            ]
                          },
                          "ist_aggregat": {
                            "type": "boolean"
                          },
                          "werte": {
                            "type": "array",
                            "description": "Werte parallel zu perioden[]. Vorzeichen: Erträge positiv, Aufwendungen negativ.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "wert": {
                                  "type": "number"
                                },
                                "vorperiode": {
                                  "type": "object",
                                  "nullable": true,
                                  "description": "PoP",
                                  "properties": {
                                    "wert": {
                                      "type": "number"
                                    },
                                    "delta": {
                                      "type": "number"
                                    },
                                    "delta_pct": {
                                      "type": "number",
                                      "nullable": true
                                    }
                                  }
                                },
                                "vorjahr": {
                                  "type": "object",
                                  "nullable": true,
                                  "description": "YoY",
                                  "properties": {
                                    "wert": {
                                      "type": "number"
                                    },
                                    "delta": {
                                      "type": "number"
                                    },
                                    "delta_pct": {
                                      "type": "number",
                                      "nullable": true
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "jahr": {
                            "type": "object",
                            "description": "Jahres-Aggregat der Zeile inkl. YoY.",
                            "properties": {
                              "wert": {
                                "type": "number"
                              },
                              "vorjahr": {
                                "type": "object",
                                "properties": {
                                  "wert": {
                                    "type": "number"
                                  },
                                  "delta": {
                                    "type": "number"
                                  },
                                  "delta_pct": {
                                    "type": "number",
                                    "nullable": true
                                  }
                                }
                              }
                            }
                          },
                          "formel": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Nur bei Aggregat-Zeilen: die summierten Zeilen-Keys."
                          },
                          "konten": {
                            "type": "array",
                            "description": "Nur bei Konten-Zeilen: zugeordnete Einzelkonten.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "kontonummer": {
                                  "type": "string"
                                },
                                "kontobeschriftung": {
                                  "type": "string"
                                },
                                "jahreswert": {
                                  "type": "number"
                                },
                                "bwa_position": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "nicht_zugeordnet": {
                      "type": "object",
                      "description": "GuV-Konten ohne eindeutige BWA-Zuordnung (Edge-Cases). NICHT in den Summen enthalten.",
                      "properties": {
                        "anzahl": {
                          "type": "integer"
                        },
                        "summe_jahr": {
                          "type": "number"
                        },
                        "hinweis": {
                          "type": "string"
                        },
                        "konten": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kontonummer": {
                                "type": "string"
                              },
                              "kontobeschriftung": {
                                "type": "string"
                              },
                              "jahreswert": {
                                "type": "number"
                              },
                              "klasse": {
                                "type": "integer"
                              },
                              "grund": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "kontrolle": {
                      "type": "object",
                      "properties": {
                        "guv_konten_gesamt": {
                          "type": "integer"
                        },
                        "zugeordnet": {
                          "type": "integer"
                        },
                        "nicht_zugeordnet": {
                          "type": "integer"
                        },
                        "bestandskonten_ignoriert": {
                          "type": "integer"
                        },
                        "abdeckung_prozent": {
                          "type": "number",
                          "example": 100
                        },
                        "jahresergebnis_bwa": {
                          "type": "number"
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlendes oder ungültiges geschaeftsjahrStartDatum / connectionId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Query-Parameter geschaeftsjahrStartDatum ist erforderlich (Format YYYY-MM-DD, Startdatum des Geschäftsjahrs)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/susa": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Summen und Salden",
        "description": "Summen- und Saldenliste für das angegebene Geschäftsjahr.\n\n**Kosten:** 1 Credit",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request GET \\\n  --url 'https://api.business-os.de/v2/datev-rewe-read/susa?geschaeftsjahrStartDatum=2026-01-01&quelle=API' \\\n  --header 'x-api-key: <api-key>'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "geschaeftsjahrStartDatum",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01",
            "description": "Startdatum des Geschäftsjahrs (YYYY-MM-DD)."
          },
          {
            "name": "kontonummer",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "120000"
            },
            "description": "Filter auf eine Kontonummer."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Summen- und Saldenliste",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SummenSaldenZeileRead"
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlendes oder ungültiges geschaeftsjahrStartDatum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Query-Parameter geschaeftsjahrStartDatum ist erforderlich (Format YYYY-MM-DD, entspricht dem Startdatum des Geschäftsjahrs)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/buchungsdaten": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Journalbuchungen",
        "description": "Liest Journalbuchungen für das angegebene Geschäftsjahr.\n\n**Kosten:** 1 Credit",
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl --request GET \\\n  --url 'https://api.business-os.de/v2/datev-rewe-read/buchungsdaten?geschaeftsjahrStartDatum=2026-01-01&quelle=API' \\\n  --header 'x-api-key: <api-key>'"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "geschaeftsjahrStartDatum",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01",
            "description": "Startdatum des Geschäftsjahrs (YYYY-MM-DD)."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Journalbuchungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BuchungsdatumRead"
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung",
                          "example": 499
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": null,
                      "waehrung": "EUR",
                      "buchungstext": "Musterleuchte, Maurice",
                      "buchungszeilen": [
                        {
                          "kontonummer": "14000000",
                          "kostenstellen": {
                            "kost1": "202",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": 5845.27
                        },
                        {
                          "kontonummer": "84000000",
                          "kostenstellen": {
                            "kost1": "202",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": -5845.27
                        }
                      ],
                      "sollHabenKennzeichen": "SOLL"
                    },
                    {
                      "id": null,
                      "waehrung": "EUR",
                      "buchungstext": "Koberbeispiel, Margareta",
                      "buchungszeilen": [
                        {
                          "kontonummer": "84000000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": 4539.66
                        },
                        {
                          "kontonummer": "601820000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": -4539.66
                        }
                      ],
                      "sollHabenKennzeichen": "HABEN"
                    },
                    {
                      "id": null,
                      "waehrung": "EUR",
                      "buchungstext": "Pastalina-Muster, Sofia",
                      "buchungszeilen": [
                        {
                          "kontonummer": "83200000",
                          "kostenstellen": {
                            "kost1": "199",
                            "kost2": null
                          },
                          "buSchluessel": "240",
                          "umsatz": 1468.8
                        },
                        {
                          "kontonummer": "606030000",
                          "kostenstellen": {
                            "kost1": "199",
                            "kost2": null
                          },
                          "buSchluessel": "240",
                          "umsatz": -1468.8
                        }
                      ],
                      "sollHabenKennzeichen": "HABEN"
                    },
                    {
                      "id": null,
                      "waehrung": "PLN",
                      "buchungstext": "Novák-Test, Pavel",
                      "buchungszeilen": [
                        {
                          "kontonummer": "83200000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": "241",
                          "umsatz": 1699.84
                        },
                        {
                          "kontonummer": "606060000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": "241",
                          "umsatz": -1699.84
                        }
                      ],
                      "sollHabenKennzeichen": "HABEN"
                    },
                    {
                      "id": null,
                      "waehrung": "EUR",
                      "buchungstext": "Spanplatten",
                      "buchungszeilen": [
                        {
                          "kontonummer": "30310000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": 15089.41
                        },
                        {
                          "kontonummer": "700000000",
                          "kostenstellen": {
                            "kost1": "201",
                            "kost2": null
                          },
                          "buSchluessel": null,
                          "umsatz": -15089.41
                        }
                      ],
                      "sollHabenKennzeichen": "SOLL"
                    }
                  ],
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlendes oder ungültiges geschaeftsjahrStartDatum",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Query-Parameter geschaeftsjahrStartDatum ist erforderlich (Format YYYY-MM-DD, entspricht dem Startdatum des Geschäftsjahrs)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "$ref": "#/components/responses/DatevAsyncTimeout504"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/opos": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "OPOS — Offene Posten",
        "description": "Aggregiert alle Buchungen aller Geschäftsjahre der Connection und gibt den **Stand der offenen Posten** pro Personenkonto zurück — gruppiert nach `(Personenkonto, Belegnummer)`, sortiert nach |Saldo| absteigend.\n\nIntern werden Geschäftsjahre + Kontenplan + alle GJ-Buchungen parallel von DATEV gefetched (typisch 15-30s für mittelgroße Mandanten). EBs werden nach DATEV-Konvention (saldo-neutrales SOLL/HABEN-Paar pro Personenkonto) korrekt behandelt; bei Konten mit Vor-Sync-Aktivität erscheint ein `EB-RESIDUAL`-Posten.\n\n**Bekannte Limitation:** der Endpoint erfasst nur **klassische 9-stellige Personenkonten**. Mandanten mit eigenen 8-stelligen Forderungs-/Verbindlichkeits-Sachkonten (z.B. `15970000 Forderungen gg. XYZ`) sehen darüber nicht alle ihre OPs — solche Konten sind über die SuSa direkt abrufbar.\n\n**Kosten:** 5 Credits",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CompanyIdParam"
          },
          {
            "name": "stichtag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "OP-Stichtag (YYYY-MM-DD). Default: heute. Filter `belegdatum <= stichtag`.",
            "example": "2026-12-31"
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "debitors",
                "creditors"
              ],
              "default": "all"
            },
            "description": "Optionaler Server-Filter: `debitors` (nur erste Ziffer 1-6), `creditors` (7-9), `all` (default)."
          },
          {
            "name": "eb",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "reconcile",
                "raw"
              ],
              "default": "reconcile"
            },
            "description": "Behandlung der Eröffnungsbilanz-Werte. `reconcile` (default): EBs werden mit Detail-Posten verrechnet; ein Restbetrag erscheint als `EB-RESIDUAL`-Posten. `raw`: EBs werden als reguläre Posten unter `beleg = '0'` ausgegeben (Debug/Wirtschaftsprüfung)."
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OP-Stand pro Personenkonto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "stichtag": {
                          "type": "string",
                          "format": "date",
                          "example": "2026-12-31"
                        },
                        "konten": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kontonummer": {
                                "type": "string",
                                "example": "100012345"
                              },
                              "bezeichnung": {
                                "type": "string",
                                "example": "Mustermann GmbH"
                              },
                              "isDebitor": {
                                "type": "boolean",
                                "description": "`true` wenn erste Ziffer 1-6 (Debitor/Forderung), `false` wenn 7-9 (Kreditor/Verbindlichkeit). DATEV-Standard, kontenrahmen-unabhängig."
                              },
                              "totalSaldo": {
                                "type": "number",
                                "description": "Saldo des Kontos zum Stichtag. Positiv = Forderung (Debitor) / Anzahlung (Kreditor). Negativ = Verbindlichkeit (Kreditor) / Gutschrift (Debitor).",
                                "example": 12450.5
                              },
                              "posten": {
                                "type": "array",
                                "description": "Liste der OPs. Sortiert: `EB-RESIDUAL` zuerst (falls vorhanden), dann chronologisch nach `belegdatum` aufsteigend (Aging-Logik).",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "beleg": {
                                      "type": "string",
                                      "description": "Belegnummer. Spezialwert `EB-RESIDUAL` für nicht-detaillierten Vor-Sync-Saldo.",
                                      "example": "R-2024-003"
                                    },
                                    "belegdatum": {
                                      "type": "string",
                                      "format": "date",
                                      "nullable": true,
                                      "example": "2024-03-15"
                                    },
                                    "buchungstext": {
                                      "type": "string",
                                      "example": "Lizenzgebühr Q1 2024"
                                    },
                                    "saldo": {
                                      "type": "number",
                                      "example": 4500
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "sumDebitoren": {
                          "type": "number",
                          "description": "Summe aller Debitoren-Salden",
                          "example": 24500
                        },
                        "sumKreditoren": {
                          "type": "number",
                          "description": "Summe aller Kreditoren-Salden (typisch negativ)",
                          "example": -8200
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach 5-Credit-Abbuchung"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/DatevServiceError"
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "description": "Asynchroner DATEV-Task-Timeout (Polling-Fenster überschritten — bei großen Mandanten ggf. retry)."
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe-read/connections": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "Verbindungen",
        "description": "Gibt alle Verbindungen der Organisation für **DATEV Rechnungswesen - Read** zurück.\n\n**Kosten:** 0 Credits",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Liste der Verbindungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "UUID der Verbindung",
                            "example": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145"
                          },
                          "organization_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "Organisations-ID des Mandanten. **Nur bei Agency-Scope** gesetzt (Aufruf mit `x-agency-id`-Header oder Agency-API-Key) — dann sehen Agency-Mitglieder, zu welcher Mandanten-Org die Connection gehört. Bei normalen Org-API-Calls weggelassen.",
                            "example": "01941b8a-c428-7e9a-9c1c-2a8c5a8c9e10"
                          },
                          "bezeichnung": {
                            "type": "string",
                            "nullable": true,
                            "description": "Optionale Bezeichnung der Verbindung",
                            "example": "Mandant Müller GmbH"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "connected",
                              "pending"
                            ],
                            "description": "`connected` wenn Verbindung aktiv, `pending` wenn OAuth noch nicht abgeschlossen"
                          },
                          "verbunden_seit": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der letzten erfolgreichen Verbindung (ISO 8601). `null` bei `pending`.",
                            "example": "2026-04-05T21:47:29Z"
                          },
                          "erstellt_am": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der Erstellung (ISO 8601)",
                            "example": "2026-03-27T09:31:04Z"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "connections": [
                    {
                      "id": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145",
                      "bezeichnung": "Mandant Müller GmbH",
                      "status": "connected",
                      "verbunden_seit": "2026-04-05T21:47:29Z",
                      "erstellt_am": "2026-03-27T09:31:04Z"
                    },
                    {
                      "id": "8e563966-79d1-4dbf-9d7f-f23e43351bdd",
                      "bezeichnung": null,
                      "status": "pending",
                      "verbunden_seit": null,
                      "erstellt_am": "2026-04-01T10:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          }
        }
      }
    },
    "/v2/datev-rewe-read/permissions": {
      "get": {
        "tags": [
          "DATEV ReWe - Read"
        ],
        "summary": "RVO-Rechte-Probe",
        "description": "Diagnostiziert die 4 DATEV-RVO-Lese-Rechte einer Read-Verbindung (Stammdaten, Auswertungen, Kontobuchungen, OPOS) durch jeweils einen leichten Read-Call gegen die zugehörigen DATEV-Endpoints. Klassifiziert die Antwort als `ok` / `permission` / `expired` / `error` — damit Make-Apps, CLI, MCP und AI-Agents vor dem eigentlichen Datenabruf deterministisch wissen, welche RVO-Teilrechte fehlen.\n\nNicht-destruktiv (nur GETs gegen DATEV). **Kosten:** 0 Credits.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Probe-Ergebnis pro RVO-Teilrecht",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscription": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "missing",
                        "expired",
                        "unknown"
                      ],
                      "description": "Aggregierter Status über alle 4 Teilrechte hinweg. `ok` wenn mindestens eines `ok` ist; `missing` wenn alle 4 mit 403 antworten (Service-/RVO-Recht fehlt komplett); `expired` wenn mindestens eines mit 401 antwortet (Token abgelaufen); sonst `unknown`."
                    },
                    "fiscalYearStartDate": {
                      "type": "string",
                      "format": "date",
                      "nullable": true,
                      "description": "Aus der Stammdaten-Probe (`/accounting/fiscalYears`) abgeleitetes Start-Datum des jüngsten Geschäftsjahres — wird intern für die anderen 3 Probes als Query-Parameter benötigt. `null` wenn Stammdaten-Probe nicht 200 zurückgegeben hat.",
                      "example": "2026-01-01"
                    },
                    "yearsCount": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Anzahl Geschäftsjahre, die der Mandant in DATEV hat. `null` wenn Stammdaten-Probe nicht 200 zurückgegeben hat.",
                      "example": 2
                    },
                    "checks": {
                      "type": "object",
                      "description": "Pro RVO-Teilrecht ein Check-Eintrag.",
                      "properties": {
                        "stammdaten": {
                          "$ref": "#/components/schemas/RvoCheck"
                        },
                        "auswertungen": {
                          "$ref": "#/components/schemas/RvoCheck"
                        },
                        "kontobuchungen": {
                          "$ref": "#/components/schemas/RvoCheck"
                        },
                        "opos": {
                          "$ref": "#/components/schemas/RvoCheck"
                        }
                      },
                      "required": [
                        "stammdaten",
                        "auswertungen",
                        "kontobuchungen",
                        "opos"
                      ]
                    },
                    "tool": {
                      "type": "string",
                      "example": "DATEV Rechnungswesen - Read"
                    },
                    "probedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Zeitstempel der Probe (ISO 8601)."
                    }
                  },
                  "required": [
                    "subscription",
                    "checks",
                    "tool",
                    "probedAt"
                  ]
                },
                "example": {
                  "subscription": "ok",
                  "fiscalYearStartDate": "2026-01-01",
                  "yearsCount": 2,
                  "checks": {
                    "stammdaten": {
                      "status": "ok",
                      "httpStatus": 200
                    },
                    "auswertungen": {
                      "status": "ok",
                      "httpStatus": 200
                    },
                    "kontobuchungen": {
                      "status": "permission",
                      "httpStatus": 403,
                      "message": "Access to the requested resource is forbidden."
                    },
                    "opos": {
                      "status": "ok",
                      "httpStatus": 200
                    }
                  },
                  "tool": "DATEV Rechnungswesen - Read",
                  "probedAt": "2026-05-30T09:24:46.125Z"
                }
              }
            }
          },
          "400": {
            "description": "`connectionId` fehlt im Query-String."
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          }
        }
      }
    },
    "/v2/datev-rewe/personenkonto": {
      "post": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Geschäftspartner anlegen / aktualisieren",
        "description": "Erstellt oder aktualisiert einen Geschäftspartner in DATEV Rechnungswesen.\n\n**Kosten:** 1 Credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personenkontoNummer",
                  "kontaktTyp",
                  "kontenrahmen",
                  "kontonummernLaenge",
                  "geschaeftsjahrStartDatum"
                ],
                "properties": {
                  "personenkontoNummer": {
                    "type": "string",
                    "description": "Personenkonto-Nummer. Ist die Nummer bereits vergeben, wird der bestehende Kontakt aktualisiert.",
                    "example": "70001"
                  },
                  "kontaktTyp": {
                    "type": "string",
                    "enum": [
                      "NATUERLICHE_PERSON",
                      "UNTERNEHMEN"
                    ],
                    "description": "Art des Geschäftspartners: `NATUERLICHE_PERSON` (z. B. Freelancer) oder `UNTERNEHMEN` (juristische Person).",
                    "example": "UNTERNEHMEN"
                  },
                  "firmenname": {
                    "type": "string",
                    "description": "Firmenname (für `kontaktTyp: UNTERNEHMEN`).",
                    "example": "Beispiel GmbH"
                  },
                  "ustId": {
                    "type": "string",
                    "description": "Umsatzsteuer-Identifikationsnummer (USt-IdNr.).",
                    "example": "DE123456789"
                  },
                  "emailAdressen": {
                    "type": "array",
                    "description": "E-Mail-Adressen des Geschäftspartners. **Nur bei `UNTERNEHMEN`** — bei `NATUERLICHE_PERSON` müssen E-Mail-Adressen innerhalb von `kontaktpersonen` angegeben werden.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string",
                          "example": "info@beispiel.de"
                        },
                        "typ": {
                          "type": "string",
                          "enum": [
                            "GESCHAEFTLICH"
                          ],
                          "example": "GESCHAEFTLICH"
                        }
                      }
                    }
                  },
                  "telefonnummern": {
                    "type": "array",
                    "description": "Telefonnummern des Geschäftspartners. **Nur bei `UNTERNEHMEN`** — bei `NATUERLICHE_PERSON` müssen Telefonnummern innerhalb von `kontaktpersonen` angegeben werden.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "nummer": {
                          "type": "string",
                          "example": "+49 89 123456"
                        },
                        "typ": {
                          "type": "string",
                          "enum": [
                            "GESCHAEFTLICH",
                            "MOBIL"
                          ],
                          "example": "GESCHAEFTLICH"
                        }
                      }
                    }
                  },
                  "bankkonten": {
                    "type": "array",
                    "description": "Bankverbindungen des Geschäftspartners.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "iban": {
                          "type": "string",
                          "example": "DE89370400440532013000"
                        },
                        "bic": {
                          "type": "string",
                          "example": "COBADEFFXXX"
                        },
                        "name": {
                          "type": "string",
                          "description": "Name der Bank oder des Kontos.",
                          "example": "Geschäftskonto"
                        },
                        "istHauptkonto": {
                          "type": "boolean",
                          "description": "Gibt an, ob dies das Hauptkonto ist.",
                          "example": true
                        }
                      }
                    }
                  },
                  "kontaktpersonen": {
                    "type": "array",
                    "description": "Kontaktpersonen des Geschäftspartners. **Pflicht bei `NATUERLICHE_PERSON`** (mind. 1 Eintrag). **Verboten bei `UNTERNEHMEN`**.",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "properties": {
                        "vorname": {
                          "type": "string",
                          "example": "Max"
                        },
                        "nachname": {
                          "type": "string",
                          "example": "Mustermann"
                        },
                        "anrede": {
                          "type": "string",
                          "example": "Herr"
                        },
                        "emailAdressen": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "email": {
                                "type": "string",
                                "example": "m.mustermann@beispiel.de"
                              },
                              "typ": {
                                "type": "string",
                                "enum": [
                                  "GESCHAEFTLICH"
                                ],
                                "example": "GESCHAEFTLICH"
                              }
                            }
                          }
                        },
                        "telefonnummern": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "nummer": {
                                "type": "string",
                                "example": "+49 89 123456"
                              },
                              "typ": {
                                "type": "string",
                                "enum": [
                                  "GESCHAEFTLICH",
                                  "MOBIL"
                                ],
                                "example": "MOBIL"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "adressen": {
                    "type": "array",
                    "description": "Adressen des Geschäftspartners.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "adresszeile": {
                          "type": "string",
                          "example": "Musterstraße 1"
                        },
                        "postleitzahl": {
                          "type": "string",
                          "example": "80331"
                        },
                        "ort": {
                          "type": "string",
                          "example": "München"
                        },
                        "laendercode": {
                          "type": "string",
                          "description": "ISO 3166-1 alpha-2 Ländercode.",
                          "example": "DE"
                        },
                        "typ": {
                          "type": "string",
                          "enum": [
                            "RECHNUNGSADRESSE",
                            "GESCHAEFTLICH"
                          ],
                          "example": "RECHNUNGSADRESSE"
                        }
                      }
                    }
                  },
                  "kontenrahmen": {
                    "type": "string",
                    "description": "Kontenrahmen des Mandanten.",
                    "example": "SKR03"
                  },
                  "kontonummernLaenge": {
                    "type": "integer",
                    "description": "Länge der Kontonummer des Mandanten.",
                    "example": 5
                  },
                  "geschaeftsjahrStartDatum": {
                    "type": "string",
                    "format": "date",
                    "description": "Erster Tag des Geschäftsjahres (YYYY-MM-DD). Üblicherweise der 1. Januar.",
                    "example": "2025-01-01"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Geschäftspartner erfolgreich angelegt / aktualisiert",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "nullable": true
                        },
                        "kontonummernLaenge": {
                          "type": "integer"
                        },
                        "kontenrahmen": {
                          "type": "string"
                        },
                        "erstelltAm": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "geschaeftsjahrStartDatum": {
                          "type": "string",
                          "format": "date"
                        },
                        "eintraege": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "nullable": true
                              },
                              "kontaktTyp": {
                                "type": "string"
                              },
                              "personenkontoNummer": {
                                "type": "integer"
                              },
                              "nummer": {
                                "type": "string",
                                "nullable": true
                              },
                              "firmenname": {
                                "type": "string"
                              },
                              "ustId": {
                                "type": "string",
                                "nullable": true
                              },
                              "aktualisiertAm": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "projektId": {
                                "type": "string",
                                "nullable": true
                              },
                              "bankkonten": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true
                                }
                              },
                              "emailAdressen": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true
                                }
                              },
                              "telefonnummern": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true
                                }
                              },
                              "kontaktpersonen": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true
                                }
                              },
                              "adressen": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "datevAntwort": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "antwortDaten": {
                          "type": "object",
                          "nullable": true
                        },
                        "meldungen": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": null,
                    "kontonummernLaenge": 4,
                    "kontenrahmen": "SKR03",
                    "erstelltAm": "2025-03-15T10:32:27.122Z",
                    "geschaeftsjahrStartDatum": "2025-01-01",
                    "eintraege": [
                      {
                        "id": null,
                        "kontaktTyp": "UNTERNEHMEN",
                        "personenkontoNummer": 70001,
                        "nummer": null,
                        "firmenname": "Musterbau GmbH",
                        "ustId": "DE123456789",
                        "aktualisiertAm": null,
                        "projektId": null,
                        "bankkonten": [
                          {
                            "iban": "DE89370400440532013000",
                            "bic": "COBADEFFXXX",
                            "name": "Geschäftskonto",
                            "istHauptkonto": true
                          }
                        ],
                        "emailAdressen": [
                          {
                            "email": "info@musterbau.de",
                            "typ": "GESCHAEFTLICH"
                          }
                        ],
                        "telefonnummern": [
                          {
                            "nummer": "+49 89 123456",
                            "typ": "GESCHAEFTLICH"
                          }
                        ],
                        "kontaktpersonen": [
                          {
                            "vorname": "Max",
                            "nachname": "Mustermann",
                            "anrede": "Herr",
                            "emailAdressen": [
                              {
                                "email": "m.mustermann@musterbau.de",
                                "typ": "GESCHAEFTLICH"
                              }
                            ],
                            "telefonnummern": [
                              {
                                "nummer": "+49 171 9876543",
                                "typ": "MOBIL"
                              }
                            ]
                          }
                        ],
                        "adressen": [
                          {
                            "adresszeile": "Musterstraße 12",
                            "adresszeile2": null,
                            "postleitzahl": "80331",
                            "ort": "München",
                            "laendercode": "DE",
                            "typ": "RECHNUNGSADRESSE"
                          }
                        ]
                      }
                    ]
                  },
                  "datevAntwort": {
                    "status": "ERFOLGREICH",
                    "antwortDaten": null,
                    "meldungen": []
                  },
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende Pflichtfelder oder von DATEV abgewiesene Felder.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "examples": {
                  "pflichtfelderFehlen": {
                    "summary": "Pflichtfelder fehlen",
                    "value": {
                      "error": "Fehlende Pflichtfelder: kontaktdetails, kontenrahmen, kontonummernLaenge, geschaeftsjahrStartDatum"
                    }
                  },
                  "datevValidierung": {
                    "summary": "DATEV lehnt die Anfrage ab (optional details)",
                    "value": {
                      "error": "…",
                      "details": {
                        "message": "…"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe/buchung": {
      "post": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Buchung erstellen",
        "description": "Erstellt einen einzelnen Buchungssatz direkt in DATEV Rechnungswesen.\n\n**Kosten:** 1 Credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ConnectionIdParam"
          },
          {
            "$ref": "#/components/parameters/CreditQuelleParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kontenrahmen",
                  "kontonummernLaenge",
                  "geschaeftsjahrStartDatum",
                  "waehrung",
                  "sollHabenKennzeichen",
                  "buchungstext",
                  "belegfeld1",
                  "transaktionsdatum",
                  "buchungszeilen"
                ],
                "properties": {
                  "kontenrahmen": {
                    "type": "string",
                    "enum": [
                      "SKR03",
                      "SKR04",
                      "SKR42",
                      "SKR51",
                      "SKR14"
                    ],
                    "description": "Kontenrahmen des Mandanten.",
                    "example": "SKR03"
                  },
                  "kontonummernLaenge": {
                    "type": "integer",
                    "description": "Länge der Sachkontonummern — muss der Konfiguration im DATEV-Mandanten entsprechen.",
                    "example": 4
                  },
                  "geschaeftsjahrStartDatum": {
                    "type": "string",
                    "format": "date",
                    "description": "Erster Tag des Geschäftsjahres (YYYY-MM-DD). Üblicherweise der 1. Januar.",
                    "example": "2025-01-01"
                  },
                  "waehrung": {
                    "type": "string",
                    "description": "Währung (ISO 4217, 3-Buchstaben-Code).",
                    "example": "EUR"
                  },
                  "sollHabenKennzeichen": {
                    "type": "string",
                    "enum": [
                      "SOLL",
                      "HABEN"
                    ],
                    "description": "`SOLL` (Debit) oder `HABEN` (Credit) für das Konto in der positiven Buchungszeile.",
                    "example": "HABEN"
                  },
                  "buchungstext": {
                    "type": "string",
                    "description": "Beschreibungstext der Buchung (max. 60 Zeichen).",
                    "example": "Ausgangsrechnung März 2025"
                  },
                  "belegfeld1": {
                    "type": "string",
                    "description": "Belegnummer. Erlaubte Zeichen: Ziffern, Groß- und Kleinbuchstaben sowie `$ & % * + - /`.",
                    "example": "RE-2025-0042"
                  },
                  "transaktionsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Buchungsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-03-31T00:00:00Z"
                  },
                  "buchungszeilen": {
                    "type": "array",
                    "description": "Buchungszeilen. Jede Buchung muss mindestens zwei Zeilen enthalten — eine mit positivem und eine mit negativem `umsatz`.",
                    "minItems": 2,
                    "items": {
                      "type": "object",
                      "required": [
                        "kontonummer",
                        "umsatz"
                      ],
                      "properties": {
                        "kontonummer": {
                          "type": "integer",
                          "description": "Kontonummer (Sachkonto oder Personenkonto). Sachkonten haben die Länge `kontonummernLaenge`, Personenkonten `kontonummernLaenge + 1`.",
                          "example": 8400
                        },
                        "umsatz": {
                          "type": "number",
                          "description": "Bruttobetrag der Buchungszeile. Max. 10 Stellen vor dem Komma, max. 2 Nachkommastellen. Darf nicht 0 sein.",
                          "example": 119
                        },
                        "buSchluessel": {
                          "type": "string",
                          "description": "BU-Schlüssel (Steuercode) — muss einem Wert aus `GET /v2/datev-rewe/steuersaetze` (Feld `buSchluessel`) entsprechen.",
                          "example": "03"
                        },
                        "kostenstelle1": {
                          "type": "string",
                          "description": "Kostenstelle 1 (KOST1) für die Buchungszeile (max. 36 Zeichen).",
                          "example": "Marketing"
                        },
                        "kostenstelle2": {
                          "type": "string",
                          "description": "Kostenstelle 2 (KOST2) für die Buchungszeile (max. 36 Zeichen).",
                          "example": "Projekt-42"
                        },
                        "skontobetrag": {
                          "type": "number",
                          "description": "Skontobetrag (nur EUR, positiv, max. 8 Stellen vor dem Komma, max. 2 Nachkommastellen). Erfordert genau ein Personenkonto und ein Bankkonto.",
                          "example": 2.38
                        }
                      }
                    }
                  },
                  "belegId": {
                    "type": "string",
                    "description": "ID einer zuvor mit `POST /v2/datev-rewe/beleg-bereitstellen` hochgeladenen Datei.",
                    "example": "768E0E789A70499B91729C4516143135"
                  },
                  "lieferdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Lieferdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Wenn gesetzt, ist `steuererfassungsdatum` Pflicht.",
                    "example": "2025-03-28T00:00:00Z"
                  },
                  "faelligkeitsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Fälligkeitsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339).",
                    "example": "2025-04-30T00:00:00Z"
                  },
                  "wechselkurs": {
                    "type": "string",
                    "description": "Wechselkurs — Pflicht wenn `waehrung` nicht EUR. Format: bis zu 4 Stellen, Komma, 2–6 Nachkommastellen (z. B. `1,234567`).",
                    "example": "1,082500"
                  },
                  "steuererfassungsdatum": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Steuererfassungsdatum. ISO-8601-Datum und -Uhrzeit mit Zeitzone (RFC 3339). Pflicht wenn `lieferdatum` gesetzt.",
                    "example": "2025-03-31T00:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Buchung erfolgreich erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "datevAntwort": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "antwortDaten": {
                          "type": "object",
                          "nullable": true
                        },
                        "meldungen": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "business-os": {
                      "type": "object",
                      "properties": {
                        "neuesGuthaben": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Verbleibende Credits nach Abbuchung"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "datevAntwort": {
                    "status": "ERFOLGREICH",
                    "antwortDaten": null,
                    "meldungen": []
                  },
                  "business-os": {
                    "neuesGuthaben": 499
                  }
                }
              }
            }
          },
          "400": {
            "description": "Fehlende Pflichtfelder.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Fehlende Pflichtfelder: kontenrahmen, buchungszeilen"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/DatevPaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/DatevNoConnection404Rewe"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          },
          "502": {
            "$ref": "#/components/responses/DatevBadGateway502"
          },
          "504": {
            "description": "Async-Task-Timeout: DATEV hat den Task nicht rechtzeitig abgeschlossen.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatevError"
                },
                "example": {
                  "error": "Async-Task-Timeout: Task wurde nicht rechtzeitig abgeschlossen."
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/DatevServiceError"
          }
        }
      }
    },
    "/v2/datev-rewe/connections": {
      "get": {
        "tags": [
          "DATEV ReWe - Write"
        ],
        "summary": "Verbindungen",
        "description": "Gibt alle Verbindungen der Organisation für **DATEV Rechnungswesen - Write** zurück.\n\n**Kosten:** 0 Credits",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Liste der Verbindungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "UUID der Verbindung",
                            "example": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145"
                          },
                          "organization_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "Organisations-ID des Mandanten. **Nur bei Agency-Scope** gesetzt (Aufruf mit `x-agency-id`-Header oder Agency-API-Key) — dann sehen Agency-Mitglieder, zu welcher Mandanten-Org die Connection gehört. Bei normalen Org-API-Calls weggelassen.",
                            "example": "01941b8a-c428-7e9a-9c1c-2a8c5a8c9e10"
                          },
                          "bezeichnung": {
                            "type": "string",
                            "nullable": true,
                            "description": "Optionale Bezeichnung der Verbindung",
                            "example": "Mandant Müller GmbH"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "connected",
                              "pending"
                            ],
                            "description": "`connected` wenn Verbindung aktiv, `pending` wenn OAuth noch nicht abgeschlossen"
                          },
                          "verbunden_seit": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der letzten erfolgreichen Verbindung (ISO 8601). `null` bei `pending`.",
                            "example": "2026-04-05T21:47:29Z"
                          },
                          "erstellt_am": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "Zeitstempel der Erstellung (ISO 8601)",
                            "example": "2026-03-27T09:31:04Z"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "connections": [
                    {
                      "id": "abbc18fd-ba5e-4dfd-afc4-9dec0c0ad145",
                      "bezeichnung": "Mandant Müller GmbH",
                      "status": "connected",
                      "verbunden_seit": "2026-04-05T21:47:29Z",
                      "erstellt_am": "2026-03-27T09:31:04Z"
                    },
                    {
                      "id": "8e563966-79d1-4dbf-9d7f-f23e43351bdd",
                      "bezeichnung": null,
                      "status": "pending",
                      "verbunden_seit": null,
                      "erstellt_am": "2026-04-01T10:00:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DatevUnauthorized"
          },
          "500": {
            "$ref": "#/components/responses/DatevInternal500"
          }
        }
      }
    },
    "/v2/banking/connect": {
      "post": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Create Connection",
        "description": "Erstellt eine Bank-Connect-Session und gibt die Widget-URL zurück. Der User wird zum Widget weitergeleitet, wählt seine Bank und autorisiert den Zugriff via OAuth.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiParam"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "E-Mail-Adresse des Kunden (für Banking-Customer)",
                    "example": "info@mustermann.de"
                  },
                  "return_to": {
                    "type": "string",
                    "format": "uri",
                    "description": "Redirect-URL nach erfolgreicher Verbindung",
                    "example": "https://app.business-os.de/close"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "accounts",
                        "holder_info",
                        "transactions"
                      ]
                    },
                    "default": [
                      "accounts",
                      "holder_info",
                      "transactions"
                    ],
                    "description": "Banking-Scopes für die Verbindung. Standard deckt alle drei ab: Kontoinfos, Inhaberdaten und Transaktionen.",
                    "example": [
                      "accounts",
                      "holder_info",
                      "transactions"
                    ]
                  },
                  "custom_fields": {
                    "type": "object",
                    "description": "Benutzerdefinierte Felder (werden im Callback zurückgegeben)",
                    "example": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connect Session erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectSessionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      }
    },
    "/v2/banking/connections": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "List Connections",
        "description": "Listet alle Bank-Verbindungen der Organisation auf.\n\nOhne `api`-Parameter werden alle Verbindungen (Partner + Open Banking) zurückgegeben.\n\n**Cost:** 0 Credits",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Liste der Verbindungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Connection"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      }
    },
    "/v2/banking/connections/{id}": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Get Connection",
        "description": "Ruft die Details einer bestimmten Bank-Verbindung ab.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Connection-ID",
            "example": "9182736450918273645"
          }
        ],
        "responses": {
          "200": {
            "description": "Verbindungsdetails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Verbindung nicht gefunden"
          }
        }
      },
      "delete": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Delete Connection",
        "description": "Löscht eine Bank-Verbindung und alle zugehörigen Konten und Transaktionen unwiderruflich.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Connection-ID",
            "example": "9182736450918273645"
          }
        ],
        "responses": {
          "200": {
            "description": "Verbindung erfolgreich gelöscht. Response wird unverändert von der Banking-Schnittstelle durchgereicht — Schema kann je nach API-Variante minimal abweichen.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "connection_id": {
                          "type": "string",
                          "description": "Banking-Connection-ID der gelöschten Verbindung",
                          "example": "9182736450918273645"
                        },
                        "customer_id": {
                          "type": "string",
                          "description": "Banking-Customer-ID (nur bei einigen API-Varianten)",
                          "example": "1738564738291"
                        },
                        "removed": {
                          "type": "boolean",
                          "description": "Ob die Verbindung erfolgreich entfernt wurde",
                          "example": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Verbindung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/connections/{id}/refresh": {
      "post": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Refresh Connection",
        "description": "Aktualisiert die Kontodaten einer Verbindung. Kann eine erneute Autorisierung über das Connect Widget erfordern (z.B. bei abgelaufenem Consent).\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Connection-ID",
            "example": "9182736450918273645"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "return_to": {
                    "type": "string",
                    "format": "uri",
                    "description": "Redirect-URL nach erneuter Autorisierung",
                    "example": "https://app.business-os.de/close"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refresh gestartet. Enthält ggf. eine Widget-URL wenn erneute Autorisierung nötig.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshResponse"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Verbindung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/connections/{id}/reconnect": {
      "post": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Reconnect Connection",
        "description": "Erstellt eine Reconnect-Session für eine inaktive oder fehlgeschlagene Verbindung. Gibt eine Connect Widget URL zurück.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Connection-ID",
            "example": "9182736450918273645"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "return_to": {
                    "type": "string",
                    "format": "uri",
                    "description": "Redirect-URL nach erneuter Autorisierung",
                    "example": "https://app.business-os.de/close"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reconnect-Session erstellt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshResponse"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Verbindung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/connections/{id}/display-name": {
      "put": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Set Display Name",
        "description": "Setzt einen benutzerdefinierten Anzeigenamen für eine Bank-Verbindung.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Connection-ID",
            "example": "9182736450918273645"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "display_name"
                ],
                "properties": {
                  "display_name": {
                    "type": "string",
                    "description": "Neuer Anzeigename für die Verbindung",
                    "example": "Sparkasse Firmenkonto"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Anzeigename aktualisiert",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "display_name": {
                      "type": "string",
                      "example": "Sparkasse Firmenkonto"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Verbindung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/accounts": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "List Accounts",
        "description": "Listet Bankkonten auf. Ohne `connection_id` werden alle Konten der Organisation zurückgegeben.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiParam"
          },
          {
            "name": "connection_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ID der Bank-Verbindung (optional — ohne Filter werden alle Konten zurückgegeben)",
            "example": "9182736450918273645"
          },
          {
            "name": "pis",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Wenn `true`: nur Konten zurückgeben, deren Provider Payment Initiation Services (PIS) unterstützt. Nützlich um Konten zu finden, von denen aus Überweisungen via `POST /v2/banking/payments` möglich sind.",
            "example": true
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Konten",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      }
    },
    "/v2/banking/accounts/{id}": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Get Account",
        "description": "Ruft die Details eines bestimmten Bankkontos ab.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Account-ID",
            "example": "8273645091827364509"
          }
        ],
        "responses": {
          "200": {
            "description": "Kontodetails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "404": {
            "description": "Konto nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/providers": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Search Providers",
        "description": "Sucht Bank-Provider nach Name über Partner- und Open-Banking-API. Liefert die `provider_code`-Werte, die für `POST /v2/banking/connect` und `POST /v2/banking/payments` benötigt werden.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Suchbegriff (Bankname)",
            "example": "Sparkasse"
          },
          {
            "name": "api",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "partner",
                "openbanking"
              ]
            },
            "description": "API-Typ (default: partner)"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste passender Provider",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/v2/banking/payment-templates": {
      "get": {
        "tags": [
          "Banking PIS"
        ],
        "summary": "List Payment Templates",
        "description": "Listet die für das Konto verfügbaren Payment-Templates (z.B. SEPA, SEPA_INSTANT) auf — abgeleitet aus der Bank des Kontos. Jedes Template kann `nested`-Felder mitliefern: bankabhängige Zusatzfelder über die Standardfelder hinaus (heute nur `date` für eine geplante Zahlung / Terminüberweisung). Vorbereitung für `POST /v2/banking/payments`.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "account_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID des eigenen Bankkontos. Daraus werden Bank/Provider und die unterstützten Templates aufgelöst.",
            "example": "8273645091827364509"
          }
        ],
        "responses": {
          "200": {
            "description": "Verfügbare Templates für das Konto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "label": {
                            "type": "string",
                            "example": "SEPA"
                          },
                          "value": {
                            "type": "string",
                            "description": "Wert für `template_identifier`. Erste Option ist immer `AUTO` (Instant bevorzugt).",
                            "example": "AUTO"
                          },
                          "nested": {
                            "type": "array",
                            "description": "Bankabhängige Zusatzfelder für dieses Template (heute nur `date` für eine Terminüberweisung). Leer, wenn die Bank keine Zusatzfelder unterstützt.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "example": "date"
                                },
                                "type": {
                                  "type": "string",
                                  "example": "date"
                                },
                                "label": {
                                  "type": "string",
                                  "example": "Ausführungsdatum (Planen)"
                                },
                                "help": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/v2/banking/transactions": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "List Transactions",
        "description": "Listet Transaktionen auf. **Mindestens einer von `connection_id` oder `account_id` ist erforderlich** — ohne Filter wird 400 zurückgegeben.\n\n- Nur `connection_id`: alle Konten dieser Connection\n- Nur `account_id`: Connection wird automatisch aufgelöst\n- Beide: spezifisches Konto\n\nDer `api`-Parameter wird automatisch aus der `connection_id` abgeleitet und muss nicht angegeben werden. Sortierung: `made_on` aufsteigend.\n\n**Cost:** 1 Credit per call",
        "parameters": [
          {
            "name": "connection_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ID der Bank-Verbindung. Mindestens dieser oder `account_id` muss gesetzt sein.",
            "example": "9182736450918273645"
          },
          {
            "name": "account_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ID des Bankkontos. Mindestens dieser oder `connection_id` muss gesetzt sein.",
            "example": "8273645091827364509"
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Startdatum (YYYY-MM-DD)",
            "example": "2026-01-01"
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Enddatum (YYYY-MM-DD)",
            "example": "2026-03-24"
          },
          {
            "name": "from_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Paginierung/Sync-Cursor: gibt nur Transaktionen mit `id` **strikt größer** als dieser zurück (exklusiv, numerisch verglichen). Für laufenden Sync zusammen mit `sort=id` nutzen — die `id` ist ingestion-monoton (jede neu eingelesene Transaktion bekommt eine höhere `id`) und fängt damit auch **rückdatierte Nachzügler**, die ein Datumsfilter (`from_date`) verpassen würde."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "made_on",
                "id"
              ],
              "default": "made_on"
            },
            "description": "Sortierung der Rückgabe. `made_on` (Default): chronologisch nach Wertstellungsdatum (`id` als Tiebreaker). `id`: aufsteigend nach Transaktions-ID — empfohlen für inkrementellen Sync mit `from_id`, weil dann die letzte zurückgegebene `id` direkt der nächste Cursor ist."
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Transaktionen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "connection_id fehlt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "402": {
            "description": "Nicht genügend Credits"
          }
        }
      }
    },
    "/v2/banking/transactions/{id}": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "Get Transaction",
        "description": "Ruft eine einzelne Transaktion per ID ab — inklusive `description_parsed` (geparste SEPA-Felder aus dem Verwendungszweck) und `payment_id`.\n\nNur `account_id` ist erforderlich; `organization_id`, Connection und `api` werden automatisch aus der (eindeutigen) Account-ID aufgelöst — das gilt auch für Agency-Keys (Scope wird geprüft). Die Transaktion wird über das Konto ermittelt.\n\n**Cost:** 1 Credit per call",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Eindeutige Transaktions-ID",
            "example": "6450918273645091827"
          },
          {
            "name": "account_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID des Bankkontos, zu dem die Transaktion gehört. Organisation, Connection und `api` werden daraus abgeleitet.",
            "example": "8273645091827364509"
          }
        ],
        "responses": {
          "200": {
            "description": "Die Transaktion",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Transaction"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "account_id fehlt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "402": {
            "description": "Nicht genügend Credits"
          },
          "404": {
            "description": "Transaktion oder Konto nicht gefunden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v2/banking/payments": {
      "post": {
        "tags": [
          "Banking PIS"
        ],
        "summary": "Create Payment",
        "description": "Initiiert eine SEPA oder SEPA Instant Zahlung. Gibt eine Payment-URL zurück, über die der User die Zahlung per TAN bestätigt.\n\nNur `account_id` und `amount` sind pflichtig — alle anderen Werte (Provider, Debitor-IBAN, Banking-API) werden automatisch aus der Account-ID aufgelöst. Der `end_to_end_id` wird vom Server generiert (`BOS-{ts}-{hex}`) und in der Response zurückgegeben, damit später die zugehörige Transaction matchbar ist.\n\n**Cost:** 3 Credits (only charged when payment settles successfully)",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Zahlung initiiert — User muss die payment_url aufrufen",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Fehlende oder ungültige Zahlungsdaten",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "402": {
            "description": "Nicht genügend Credits"
          }
        }
      },
      "get": {
        "tags": [
          "Banking PIS"
        ],
        "summary": "List Payments",
        "description": "Listet Zahlungen der Organisation aus den Business-OS-Datensätzen (`banking_payments`) — filterbar nach Verbindung, Konto und Datum. Status wird per Webhook aktuell gehalten; den garantiert live-aktuellen Status liefert `GET /v2/banking/payments/{id}`.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "connection_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Nach Verbindung filtern (Salt-Edge-Connection-ID). `__all__` oder weglassen = alle."
          },
          {
            "name": "account_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Nach Konto filtern. `__all__` oder weglassen = alle."
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Nur Zahlungen ab diesem Datum (YYYY-MM-DD, auf `created_at`)."
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Nur Zahlungen bis zu diesem Datum (YYYY-MM-DD, inklusive)."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "date",
                "id"
              ],
              "default": "date"
            },
            "description": "`date` = neueste zuerst (`created_at` absteigend); `id` = aufsteigend nach Payment-ID (inkrementeller Sync mit `from_id`)."
          },
          {
            "name": "from_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Inkrementeller Cursor: nur Zahlungen mit ID > diesem Wert (wirkt mit `sort=id`)."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Maximale Anzahl. Leer = alle."
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der Zahlungen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentRecord"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      }
    },
    "/v2/banking/payments/{id}": {
      "get": {
        "tags": [
          "Banking PIS"
        ],
        "summary": "Get Payment",
        "description": "Ruft den aktuellen Status und die Details einer initiierten Zahlung ab.\n\n**Cost:** 1 Credit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Payment-ID",
            "example": "7364509182736450918"
          },
          {
            "$ref": "#/components/parameters/ApiParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Zahlungsdetails und Status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "402": {
            "description": "Nicht genügend Credits"
          },
          "404": {
            "description": "Zahlung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/payments/{id}/refresh": {
      "post": {
        "tags": [
          "Banking PIS"
        ],
        "summary": "Refresh Payment Status",
        "description": "Erzwingt ein Live-Re-Poll des Zahlungsstatus direkt bei der Bank (statt des stündlich gecachten Status). Nützlich, um Statusänderungen außerhalb des Webhook-Flows zu erkennen — z.B. eine geplante Zahlung, die der Kunde in seiner Banking-App storniert. Gibt die frisch abgerufene Zahlung zurück.\n\n**Cost:** 1 Credit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Payment-ID",
            "example": "7364509182736450918"
          },
          {
            "$ref": "#/components/parameters/ApiParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Frisch abgerufene Zahlungsdetails und Status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          },
          "402": {
            "description": "Nicht genügend Credits"
          },
          "404": {
            "description": "Zahlung nicht gefunden"
          }
        }
      }
    },
    "/v2/banking/webhook-url": {
      "get": {
        "tags": [
          "Banking Webhooks"
        ],
        "summary": "Get Webhook URL",
        "description": "Gibt die aktuell konfigurierte Webhook-URL der Organisation zurück.\n\n**Cost:** 0 Credits",
        "responses": {
          "200": {
            "description": "Aktuelle Webhook-URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookUrlResponse"
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      },
      "put": {
        "tags": [
          "Banking Webhooks"
        ],
        "summary": "Set Webhook URL",
        "description": "Konfiguriert eine Webhook-URL für automatische Benachrichtigungen bei neuen Transaktionen oder Zahlungsstatus-Änderungen.\n\n**Cost:** 0 Credits",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "webhook_url"
                ],
                "properties": {
                  "webhook_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Deine Webhook-URL (z.B. Make.com Webhook). Auf `null` setzen zum Deaktivieren.",
                    "example": "https://hook.eu1.make.com/abc123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook-URL aktualisiert",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "webhook_url": {
                      "type": "string",
                      "nullable": true,
                      "example": "https://hook.eu1.make.com/abc123"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ungültiger API Key"
          }
        }
      }
    },
    "/v2/banking/balances": {
      "get": {
        "tags": [
          "Banking AIS"
        ],
        "summary": "List Daily Balances",
        "description": "Gibt tägliche SOD/EOD-Salden für ein Bankkonto zurück, inkl. Cash-In, Cash-Out und Delta. Transaktionen pro Tag werden nur zurückgegeben, wenn `include_transactions=true` gesetzt ist (ohne Flag bleibt das Feld `transactions[]` weg — schnelle Abfrage rein aus dem Cache, ohne Banking-Call).\n\nDie Salden werden aus einem Cache gelesen und automatisch bei jedem Refresh aktualisiert.\n\n**Cost:** 0 Credits",
        "parameters": [
          {
            "name": "account_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID des Bankkontos",
            "example": "8273645091827364509"
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Startdatum (YYYY-MM-DD)",
            "example": "2026-04-01"
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Enddatum (YYYY-MM-DD)",
            "example": "2026-04-28"
          },
          {
            "name": "include_transactions",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Wenn `true`: Transaktionen pro Tag werden im Feld `transactions[]` mitgeliefert. Default `false` — nur Salden, deutlich schneller.",
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "Liste der täglichen Salden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DailyBalance"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "account_id fehlt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  }
}