openapi: 3.0.0
info:
  title: Otark BRP Connect API
  description: API für Bilanzkreisverantwortliche (BKV) zur Einsicht in Verträge, Transaktionen und Nominierungen und zur Verwaltung der Kunden auf der Otark-Plattform.
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.energy
    description: Produktion
tags:
  - name: Contracts
    description: Die 1-Click-PPA-Einzelverträge der Kunden einsehen, ohne Preise
  - name: Transactions
    description: Liefermengen je Geschäft und Viertelstunde, aus Einzelverträgen und aus Green SPOT
  - name: Nominations
    description: Nettosaldo, aggregiert nach Bilanzkreis
  - name: Customers
    description: Die dem BKV zugeordneten Kunden verwalten
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    AfterParam:
      name: after
      in: query
      description: Cursor für die nächste Seite — den Wert `next_cursor` aus der vorherigen Antwort übergeben
      schema:
        type: string
        example: con_a1b2c3d4
    DeliveryStartParam:
      name: delivery_start
      in: query
      description: "Filter: Lieferbeginn >= diesem Wert (ISO 8601)"
      schema:
        type: string
        format: date-time
        example: "2026-06-30T22:00:00Z"
    DeliveryEndParam:
      name: delivery_end
      in: query
      description: "Filter: Lieferende <= diesem Wert (ISO 8601)"
      schema:
        type: string
        format: date-time
        example: "2026-09-30T22:00:00Z"
    DeliveryDateParam:
      name: delivery_date
      in: query
      description: Nach Liefertag filtern (Kurzform für einen ganzen Tag)
      schema:
        type: string
        format: date
        example: "2026-07-15"
    SlotNumberFromParam:
      name: slot_number_from
      in: query
      description: "Filter: Nummer der Zeitscheibe >= diesem Wert (1–100)"
      schema:
        type: integer
        minimum: 1
        maximum: 100
    SlotNumberToParam:
      name: slot_number_to
      in: query
      description: "Filter: Nummer der Zeitscheibe <= diesem Wert (1–100)"
      schema:
        type: integer
        minimum: 1
        maximum: 100
    IncludeAssetsParam:
      name: include_assets
      in: query
      description: Ein bereinigtes Feld `assets` in die Antwort aufnehmen, das alle von den gelieferten Transaktionen referenzierten Anlagen enthält
      schema:
        type: string
        enum:
          - "true"
          - "false"
        default: "false"
  headers:
    X-RateLimit-Limit:
      description: Höchstzahl der Anfragen je Zeitfenster
      schema:
        type: integer
        example: 300
    X-RateLimit-Remaining:
      description: Verbleibende Anfragen im laufenden Zeitfenster
      schema:
        type: integer
        example: 299
    X-RateLimit-Reset:
      description: Sekunden, bis das Zeitfenster der Ratenbegrenzung zurückgesetzt wird
      schema:
        type: integer
        example: 60
  schemas:
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Höchstzahl der Einträge pro Seite
          example: 10
        has_more:
          type: boolean
          description: Ob nach dem letzten gelieferten Eintrag weitere Einträge folgen
          example: true
        next_cursor:
          type: string
          nullable: true
          description: Cursor, der als Query-Parameter `after` übergeben wird, um die nächste Seite abzurufen. Null, wenn keine weiteren Seiten folgen.
          example: txn_k8m2p4q7r1
      required:
        - limit
        - has_more
        - next_cursor
    Problem:
      type: object
      description: Fehlerantwort nach [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).
      properties:
        type:
          type: string
          format: uri
          description: Absolute URI, die die Fehlerklasse bezeichnet
          example: https://brp.otark.energy/errors/balance_group_tso_not_enabled
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Balance Group TSO Not Enabled
        status:
          type: integer
          description: HTTP-Statuscode
          example: 400
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: The requested TSO is not enabled for this balance group. Enable it via the balance group settings first.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/customers/cust_r8s9t0u1
        errors:
          type: array
          description: Feldbezogene Validierungsfehler (nur bei fehlgeschlagener Validierung)
          items:
            $ref: "#/components/schemas/ProblemFieldError"
      required:
        - type
        - title
        - status
    ProblemFieldError:
      type: object
      description: Ein einzelner feldbezogener Validierungsfehler
      properties:
        field:
          type: string
          description: JSON-Pfad des Feldes, das den Fehler ausgelöst hat
          example: balance_group.tso
        code:
          type: string
          description: "Maschinenlesbarer Fehlercode: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large` oder `validation_failed`"
          example: invalid_enum_value
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: "Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID'"
      required:
        - code
        - message
    Counterparty:
      type: object
      description: Eine über den EIC-Code bezeichnete Gegenpartei
      properties:
        name:
          type: string
          description: Name des Unternehmens oder der Einheit
          example: Stadtwerke
        eic:
          type: string
          description: EIC-Code (Bilanzkreis)
          example: 11YSTADTWERKE--Z
        tso:
          type: string
          description: ÜNB, der für den Bilanzkreis zuständig ist
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - name
        - eic
        - tso
    Asset:
      type: object
      description: Eine Erzeugungsanlage
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Anlage
          example: ast_w1x2y3z4
        name:
          type: string
          description: Anzeigename der Erzeugungsanlage
          example: Solar Park SP-1
        nominal_power:
          type: number
          description: Nennleistung in MW
          example: 10.0
        technology:
          type: string
          description: Erzeugungstechnologie
          enum:
            - solar
            - wind_onshore
            - wind_offshore
          example: solar
        tso:
          type: string
          description: ÜNB, in dessen Regelzone die Anlage angeschlossen ist
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - id
        - name
        - nominal_power
        - technology
        - tso
    Contract:
      type: object
      description: "Ein 1-Click-PPA-Einzelvertrag eines Kunden, mit den Namen beider Vertragsparteien und ohne Preis. Green-SPOT-Zuschläge erzeugen keinen Vertrag; sie erscheinen als eigene Posten unter den Transaktionen, mit `contract_id` null."
      properties:
        id:
          type: string
          description: Interne eindeutige Kennung des Vertrags
          example: con_a1b2c3d4
        external_id:
          type: string
          description: Externe Referenzkennung des Vertrags
          example: 7K2QP
        type:
          type: string
          description: "Vertragstyp. Ein Vertrag trägt immer `ppa`; die Werte `day_ahead` und `intraday` kommen bei Verträgen nicht vor."
          enum:
            - ppa
            - day_ahead
            - intraday
          example: ppa
        status:
          type: string
          description: Vertragsstatus
          enum:
            - pending
            - in_progress
            - completed
          example: in_progress
        delivery_start:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Lieferbeginn (UTC)
          example: "2026-06-30T22:00:00Z"
        delivery_end:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Lieferende (UTC)
          example: "2026-09-30T22:00:00Z"
        seller:
          $ref: "#/components/schemas/Counterparty"
        buyer:
          $ref: "#/components/schemas/Counterparty"
        ppa_type:
          type: string
          nullable: true
          description: "Preis- und Lieferart des PPA. Ein 1-Click-PPA-Einzelvertrag liefert as indexed nach dem ENWEX-Index und trägt immer `indexed`."
          enum:
            - forecasted
            - produced
            - consumed
            - baseload
            - shaped
            - peakload
            - indexed
          example: indexed
        period:
          type: string
          nullable: true
          description: Anzeigename der Vertragsperiode, ein Kalenderquartal oder Kalenderjahr
          example: Q3-2026
        delivery_profile:
          type: string
          nullable: true
          description: Name des Lieferprofils, ENWEX Solar DE oder ENWEX Wind DE
          example: ENWEX Solar DE
        asset:
          description: Die Erzeugungsanlage (nur vorhanden, wenn dem Vertrag eine Anlage zugeordnet ist)
          allOf:
            - $ref: "#/components/schemas/Asset"
        created_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-05-12T08:42:17Z"
      required:
        - id
        - external_id
        - type
        - status
        - delivery_start
        - delivery_end
        - seller
        - buyer
        - created_at
    ContractList:
      type: object
      properties:
        contracts:
          type: array
          description: Liste der Verträge
          items:
            $ref: "#/components/schemas/Contract"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - contracts
        - pagination
    TransactionSender:
      type: object
      description: Die sendende Partei einer Transaktion
      properties:
        eic:
          type: string
          description: EIC-Code (Bilanzkreis) des Senders
          example: 11YDIREKTVERM--A
        asset_id:
          type: string
          nullable: true
          description: Kennung der Anlage (mit `include_assets=true` werden die vollständigen Anlagendaten mitgeliefert)
          example: ast_w1x2y3z4
        tso:
          type: string
          description: ÜNB des Senders
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - eic
        - asset_id
        - tso
    TransactionReceiver:
      type: object
      description: Die empfangende Partei einer Transaktion
      properties:
        eic:
          type: string
          description: EIC-Code (Bilanzkreis) des Empfängers
          example: 11YSTADTWERKE--Z
        tso:
          type: string
          description: ÜNB des Empfängers
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - eic
        - tso
    Transaction:
      type: object
      description: "Die Liefermenge eines Geschäfts in einer Viertelstunde. Eine Transaktion aus einem 1-Click-PPA-Einzelvertrag verbindet die Bilanzkreise von Verkäufer und Käufer; eine Green-SPOT-Transaktion hat immer OTARK-CLEARING als Gegenseite, die Handelsgegenseite bleibt anonym. Transaktionen sind unveränderlich, eine Korrektur durch OES erzeugt eine neue Version, die die vorherige ersetzt."
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Transaktion
          example: txn_k8m2p4q7r1
        type:
          type: string
          description: "Transaktionstyp: `ppa` für Einzelverträge, `day_ahead` für jede Green-SPOT-Transaktion, auch aus einem Intraday-Abschluss"
          enum:
            - ppa
            - day_ahead
          example: ppa
        contract_id:
          type: string
          nullable: true
          description: Kennung des übergeordneten Vertrags; null bei jeder Green-SPOT-Transaktion, ob aus einem Day-ahead-Zuschlag oder einem Intraday-Abschluss
          example: con_a1b2c3d4
        status:
          type: string
          description: Transaktionsstatus
          enum:
            - valid
            - invalid
            - superseded
          example: valid
        version:
          type: integer
          description: Versionsnummer (beginnt bei 1, erhöht sich mit jeder Korrektur)
          example: 2
        previous_transaction_id:
          type: string
          nullable: true
          description: Kennung der Transaktion, die diese Version ersetzt
          example: txn_j5n3w8v2x6
        sender:
          $ref: "#/components/schemas/TransactionSender"
        receiver:
          $ref: "#/components/schemas/TransactionReceiver"
        delivery_start:
          type: string
          format: date-time
          description: ISO-8601-Beginn des Lieferzeitraums (UTC)
          example: "2026-07-15T11:00:00Z"
        delivery_end:
          type: string
          format: date-time
          description: ISO-8601-Ende des Lieferzeitraums (UTC)
          example: "2026-07-15T11:15:00Z"
        slot_number:
          type: integer
          description: "Nummer der Viertelstunden-Zeitscheibe innerhalb des Liefertags (1–96). Am 23-Stunden-Tag der Umstellung auf Sommerzeit entfallen die Zeitscheiben 9–12 (92 Einträge). Am 25-Stunden-Tag der Umstellung auf Winterzeit treten die Zeitscheiben der wiederholten Stunde zweimal auf: Der erste Durchlauf behält die Nummern 9–12, der zweite trägt die Nummern 97–100 (97–100 entsprechen `9b`–`12b` in den Nominierungsdateien); die beiden Durchläufe unterscheiden sich durch ihre UTC-Zeitstempel."
          minimum: 1
          maximum: 100
          example: 53
        volume:
          type: number
          description: Energiemenge in MWh (3 Nachkommastellen)
          example: 1.563
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-07-14T10:30:00Z"
      required:
        - id
        - type
        - status
        - version
        - sender
        - receiver
        - delivery_start
        - delivery_end
        - slot_number
        - volume
        - created_at
    TransactionList:
      type: object
      properties:
        transactions:
          type: array
          description: Liste der Transaktionen
          items:
            $ref: "#/components/schemas/Transaction"
        pagination:
          $ref: "#/components/schemas/Pagination"
        assets:
          type: array
          description: Bereinigte Liste der Anlagen, auf die die gelieferten Transaktionen verweisen (nur vorhanden bei `include_assets=true`)
          items:
            $ref: "#/components/schemas/Asset"
      required:
        - transactions
        - pagination
    TransactionHistoryList:
      type: object
      properties:
        transactions:
          type: array
          description: Versionsverlauf, von der neuesten zur ältesten Version sortiert
          items:
            $ref: "#/components/schemas/Transaction"
        assets:
          type: array
          description: Bereinigte Liste der Anlagen, auf die die gelieferten Transaktionen verweisen (nur vorhanden bei `include_assets=true`)
          items:
            $ref: "#/components/schemas/Asset"
      required:
        - transactions
    BulkTransactionList:
      type: object
      properties:
        transactions:
          type: array
          description: Liste der Transaktionen (Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen)
          items:
            $ref: "#/components/schemas/Transaction"
        assets:
          type: array
          description: Bereinigte Liste der Anlagen, auf die die gelieferten Transaktionen verweisen (nur vorhanden bei `include_assets=true`)
          items:
            $ref: "#/components/schemas/Asset"
      required:
        - transactions
    NominationCounterparty:
      type: object
      description: "Die Gegenseite einer Nominierung: der Clearing-Bilanzkreis von OES (OTARK-CLEARING), in allen vier Regelzonen unter derselben EIC-Kennung"
      properties:
        name:
          type: string
          description: Name der Gegenseite
          example: OTARK-CLEARING
        eic:
          type: string
          description: EIC-Code
          example: 11Y0-0000-3333-F
      required:
        - name
        - eic
    NominationSlot:
      type: object
      description: Eine Zeitscheibe der Lieferung innerhalb einer Nominierung
      properties:
        delivery_start:
          type: string
          format: date-time
          description: ISO-8601-Beginn der Zeitscheibe (UTC)
          example: "2026-07-15T11:00:00Z"
        delivery_end:
          type: string
          format: date-time
          description: ISO-8601-Ende der Zeitscheibe (UTC)
          example: "2026-07-15T11:15:00Z"
        slot_number:
          type: integer
          description: "Nummer der Viertelstunden-Zeitscheibe innerhalb des Liefertags (1–96). Am 23-Stunden-Tag der Umstellung auf Sommerzeit entfallen die Zeitscheiben 9–12 (92 Einträge). Am 25-Stunden-Tag der Umstellung auf Winterzeit treten die Zeitscheiben der wiederholten Stunde zweimal auf: Der erste Durchlauf behält die Nummern 9–12, der zweite trägt die Nummern 97–100 (97–100 entsprechen `9b`–`12b` in den Nominierungsdateien); die beiden Durchläufe unterscheiden sich durch ihre UTC-Zeitstempel."
          minimum: 1
          maximum: 100
          example: 53
        amount:
          type: number
          description: Nominierte Energiemenge in MWh (3 Nachkommastellen)
          example: 1.563
        matched_amount:
          type: number
          nullable: true
          description: Bestätigte oder abgeglichene Menge in MWh (null bis zum Abgleich)
          example: 1.563
      required:
        - delivery_start
        - delivery_end
        - slot_number
        - amount
    Nomination:
      type: object
      description: Der Nettosaldo der gültigen Transaktionen, aggregiert nach Bilanzkreis und Lieferzeitraum. Nominierungen sind unveränderlich — eine Korrektur erzeugt eine neue Version.
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Nominierung
          example: nom_t4u5v6w7x8
        status:
          type: string
          description: Nominierungsstatus
          enum:
            - pending
            - partial_match
            - match
            - superseded
          example: match
        version:
          type: integer
          description: Versionsnummer (beginnt bei 1, erhöht sich mit jeder Korrektur)
          example: 2
        previous_nomination_id:
          type: string
          nullable: true
          description: Kennung der Nominierung, die diese Version ersetzt
          example: nom_s3t4u5v6w7
        gate_closure:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Frist der Gate Closure des Fahrplanmanagements
          example: "2026-07-14T12:30:00Z"
        confirmed_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel der Bestätigung der Nominierung
          example: "2026-07-14T12:45:00Z"
        direction:
          type: string
          description: Richtung des Energieflusses aus Sicht des BKV
          enum:
            - out
            - in
          example: out
        eic:
          type: string
          description: EIC-Code (Bilanzkreis) des BKV
          example: 11YDIREKTVERM--A
        tso:
          type: string
          description: ÜNB des BKV
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
        sent_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel der Übermittlung an den ÜNB
          example: "2026-07-14T12:20:00Z"
        counterparty:
          $ref: "#/components/schemas/NominationCounterparty"
        slots:
          type: array
          description: Zeitscheiben der Lieferung samt Mengen (am Listen-Endpunkt nur bei `include_slots=true`; an den Endpunkten für Detail, Stapelabruf und Verlauf stets vorhanden)
          items:
            $ref: "#/components/schemas/NominationSlot"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-07-14T10:30:00Z"
      required:
        - id
        - status
        - version
        - gate_closure
        - direction
        - eic
        - tso
        - counterparty
        - created_at
    NominationList:
      type: object
      properties:
        nominations:
          type: array
          description: Liste der Nominierungen
          items:
            $ref: "#/components/schemas/Nomination"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - nominations
        - pagination
    NominationHistoryList:
      type: object
      properties:
        nominations:
          type: array
          description: Versionsverlauf, von der neuesten zur ältesten Version sortiert
          items:
            $ref: "#/components/schemas/Nomination"
      required:
        - nominations
    BulkNominationList:
      type: object
      properties:
        nominations:
          type: array
          description: Liste der Nominierungen (Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen)
          items:
            $ref: "#/components/schemas/Nomination"
      required:
        - nominations
    BalanceGroup:
      type: object
      description: Eine Bilanzkreis-Zuordnung
      properties:
        eic:
          type: string
          description: EIC-Code (Bilanzkreis)
          example: 11YSOLARDACH--A
        tso:
          type: string
          description: ÜNB
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_AMPRION
      required:
        - eic
        - tso
    Customer:
      type: object
      description: Ein Kunde, der dem BKV zugeordnet ist
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Kunden
          example: cust_r8s9t0u1
        name:
          type: string
          description: Anzeigename des Kunden
          example: SolarDach GmbH
        status:
          type: string
          description: Kundenstatus
          enum:
            - pending
            - active
            - deactivated
          example: active
        balance_group:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/BalanceGroup"
        metadata:
          type: object
          description: Vom BKV vergebene Schlüssel-Wert-Paare (frei wählbar)
          additionalProperties:
            type: string
          example:
            customer_number: KD-2026-0815
            cost_center: CC-4200
            region: NRW
        assigned_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Zuordnung des Kunden
          example: "2026-01-10T09:00:00Z"
        activated_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel der Aktivierung des Kunden
          example: "2026-01-10T11:30:00Z"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-01-10T09:00:00Z"
      required:
        - id
        - name
        - status
        - balance_group
        - metadata
        - assigned_at
        - created_at
    CustomerList:
      type: object
      properties:
        customers:
          type: array
          description: Liste der Kunden
          items:
            $ref: "#/components/schemas/Customer"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - customers
        - pagination
    CustomerUpdate:
      type: object
      description: Teilaktualisierung eines Kunden. Metadaten werden zusammengeführt — nur übergebene Schlüssel werden ergänzt oder überschrieben. Um einen Schlüssel zu entfernen, setzen Sie ihn auf `null`. Werden schreibgeschützte Felder übergeben (`id`, `name`, `assigned_at`, `activated_at`, `created_at`), antwortet die API mit einem Fehler `read_only_field`.
      properties:
        status:
          type: string
          description: Neuer Kundenstatus
          enum:
            - pending
            - active
            - deactivated
        balance_group:
          $ref: "#/components/schemas/BalanceGroup"
        metadata:
          type: object
          description: Schlüssel-Wert-Paare, die in die vorhandenen Metadaten übernommen werden
          additionalProperties:
            type: string
            nullable: true
          example:
            customer_number: KD-2026-0815
            cost_center: CC-4200
    BulkTransactionIdsRequest:
      type: object
      properties:
        ids:
          type: array
          description: Liste der abzurufenden Transaktionskennungen (höchstens 100)
          items:
            type: string
          minItems: 1
          maxItems: 100
          example:
            - txn_k8m2p4q7r1
            - txn_j5n3w8v2x6
            - txn_h2b7f9d4g3
        include_assets:
          type: boolean
          description: Ein bereinigtes Feld `assets` in die Antwort aufnehmen
          default: false
      required:
        - ids
    BulkNominationIdsRequest:
      type: object
      properties:
        ids:
          type: array
          description: Liste der abzurufenden Nominierungskennungen (höchstens 100)
          items:
            type: string
          minItems: 1
          maxItems: 100
          example:
            - nom_t4u5v6w7x8
            - nom_q1r2s3t4u5
      required:
        - ids
  responses:
    NotFound:
      description: Die Ressource existiert nicht, oder der Aufrufer hat keinen Zugriff
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/customer_not_found
            title: Kunde nicht gefunden
            status: 404
            instance: /v1/customers/cust_r8s9t0u1
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/customers/cust_r8s9t0u1
            errors:
              - field: balance_group.tso
                code: invalid_enum_value
                message: "Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID'"
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/invalid_api_key
            title: Ungültiger API-Schlüssel
            status: 401
    Forbidden:
      description: Dem API-Schlüssel fehlen die erforderlichen Scopes
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: customers:write. Please create a new API key with the required scopes."
    Conflict:
      description: Zustandskonflikt — der Vorgang lässt sich im aktuellen Zustand nicht ausführen
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/already_active
            title: Kunde bereits aktiv
            status: 409
    RateLimited:
      description: Ratenbegrenzung überschritten
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://brp.otark.energy/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/contracts:
    get:
      operationId: listContracts
      summary: Verträge auflisten
      description: "Die Verträge auflisten, auf die der angemeldete BKV Zugriff hat. Filterbar nach Status, Typ, EIC-Code, Lieferzeitraum und dem Tag, an dem der Vertrag gilt.\n\nErforderlicher Scope: `contracts:read`"
      tags:
        - Contracts
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
      parameters:
        - name: status
          in: query
          description: Nach Vertragsstatus filtern
          schema:
            type: string
            enum:
              - pending
              - in_progress
              - completed
        - name: type
          in: query
          description: Nach Vertragstyp filtern; Einzelverträge tragen `ppa`
          schema:
            type: string
            enum:
              - ppa
              - day_ahead
              - intraday
        - name: eic
          in: query
          description: Nach dem EIC-Code des Käufers oder Verkäufers filtern
          schema:
            type: string
            example: 11YSTADTWERKE--Z
        - $ref: "#/components/parameters/DeliveryStartParam"
        - $ref: "#/components/parameters/DeliveryEndParam"
        - name: active_on
          in: query
          description: Verträge filtern, die an diesem Tag gültig sind
          schema:
            type: string
            format: date
            example: "2026-07-15"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Verträge
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/contracts/{contract_id}:
    get:
      operationId: getContract
      summary: Vertrag abrufen
      description: "Einen einzelnen Vertrag über seine Kennung abrufen.\n\nErforderlicher Scope: `contracts:read`"
      tags:
        - Contracts
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
      parameters:
        - name: contract_id
          in: path
          required: true
          description: Kennung des Vertrags
          schema:
            type: string
            example: con_a1b2c3d4
      responses:
        "200":
          description: Angaben zum Vertrag
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contract"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/contracts/{contract_id}/transactions:
    get:
      operationId: listContractTransactions
      summary: Transaktionen eines Vertrags auflisten
      description: "Die Transaktionen eines bestimmten Vertrags auflisten. Dieselben Filter wie beim übergreifenden Transaktions-Endpunkt, ohne `contract_id` und `type`.\n\nErforderliche Scopes: `contracts:read`, `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
        - transactions:read
      parameters:
        - name: contract_id
          in: path
          required: true
          description: Kennung des Vertrags
          schema:
            type: string
            example: con_a1b2c3d4
        - name: status
          in: query
          description: Nach Transaktionsstatus filtern
          schema:
            type: string
            enum:
              - valid
              - invalid
              - superseded
        - name: sender_eic
          in: query
          description: Nach dem EIC-Code des Senders filtern
          schema:
            type: string
            example: 11YDIREKTVERM--A
        - name: receiver_eic
          in: query
          description: Nach dem EIC-Code des Empfängers filtern
          schema:
            type: string
            example: 11YSTADTWERKE--Z
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/DeliveryStartParam"
        - $ref: "#/components/parameters/DeliveryEndParam"
        - $ref: "#/components/parameters/SlotNumberFromParam"
        - $ref: "#/components/parameters/SlotNumberToParam"
        - $ref: "#/components/parameters/IncludeAssetsParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Transaktionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/transactions:
    get:
      operationId: listTransactions
      summary: Alle Transaktionen auflisten
      description: "Alle Transaktionen des BKV auflisten, aus Einzelverträgen und aus Green SPOT. Nimmt dieselben Filter entgegen wie der vertragsbezogene Endpunkt, zusätzlich die Filter contract_id und type.\n\nErforderlicher Scope: `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - transactions:read
      parameters:
        - name: contract_id
          in: query
          description: Nach Vertrag filtern
          schema:
            type: string
            example: con_a1b2c3d4
        - name: type
          in: query
          description: Nach Transaktionstyp filtern
          schema:
            type: string
            enum:
              - ppa
              - day_ahead
        - name: status
          in: query
          description: Nach Transaktionsstatus filtern
          schema:
            type: string
            enum:
              - valid
              - invalid
              - superseded
        - name: sender_eic
          in: query
          description: Nach dem EIC-Code des Senders filtern
          schema:
            type: string
            example: 11YDIREKTVERM--A
        - name: receiver_eic
          in: query
          description: Nach dem EIC-Code des Empfängers filtern
          schema:
            type: string
            example: 11YSTADTWERKE--Z
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/DeliveryStartParam"
        - $ref: "#/components/parameters/DeliveryEndParam"
        - $ref: "#/components/parameters/SlotNumberFromParam"
        - $ref: "#/components/parameters/SlotNumberToParam"
        - $ref: "#/components/parameters/IncludeAssetsParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Transaktionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/transactions/{transaction_id}:
    get:
      operationId: getTransaction
      summary: Transaktion abrufen
      description: "Eine einzelne Transaktion über ihre Kennung abrufen.\n\nErforderlicher Scope: `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - transactions:read
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: Kennung der Transaktion
          schema:
            type: string
            example: txn_k8m2p4q7r1
      responses:
        "200":
          description: Angaben zur Transaktion
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/transactions/{transaction_id}/history:
    get:
      operationId: getTransactionHistory
      summary: Versionsverlauf einer Transaktion abrufen
      description: "Den vollständigen Versionsverlauf einer Transaktion abrufen, entlang der Kette `previous_transaction_id`. Liefert alle Versionen, von der neuesten zur ältesten sortiert.\n\nErforderlicher Scope: `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - transactions:read
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: Kennung der Transaktion
          schema:
            type: string
            example: txn_k8m2p4q7r1
        - $ref: "#/components/parameters/IncludeAssetsParam"
      responses:
        "200":
          description: Versionsverlauf der Transaktion
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionHistoryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/transactions/bulk:
    get:
      operationId: bulkGetTransactions
      summary: Mehrere Transaktionen abrufen
      description: "Mehrere Transaktionen über ihre Kennungen in einer einzigen Anfrage abrufen. Über den Query-Parameter sind höchstens 100 Kennungen möglich. Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen.\n\nErforderlicher Scope: `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - transactions:read
      parameters:
        - name: ids
          in: query
          required: true
          description: Kommagetrennte Liste von Transaktionskennungen (höchstens 100)
          schema:
            type: string
            example: txn_k8m2p4q7r1,txn_j5n3w8v2x6,txn_h2b7f9d4g3
        - $ref: "#/components/parameters/IncludeAssetsParam"
      responses:
        "200":
          description: Liste der Transaktionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkTransactionList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: bulkPostTransactions
      summary: Mehrere Transaktionen abrufen (POST)
      description: "Mehrere Transaktionen über ihre Kennungen im Anfrage-Body abrufen. Dieser Weg ist für große Kennungsmengen gedacht, die über das Limit des GET-Query-Parameters hinausgehen. Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen.\n\nErforderlicher Scope: `transactions:read`"
      tags:
        - Transactions
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - transactions:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkTransactionIdsRequest"
      responses:
        "200":
          description: Liste der Transaktionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkTransactionList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/nominations:
    get:
      operationId: listNominations
      summary: Nominierungen auflisten
      description: "Die Nominierungen auflisten, auf die der angemeldete BKV Zugriff hat.\n\nErforderlicher Scope: `nominations:read`"
      tags:
        - Nominations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - nominations:read
      parameters:
        - name: status
          in: query
          description: Nach Nominierungsstatus filtern
          schema:
            type: string
            enum:
              - pending
              - partial_match
              - match
              - superseded
        - name: eic
          in: query
          description: Nach dem EIC-Code des Kunden filtern
          schema:
            type: string
            example: 11YDIREKTVERM--A
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/DeliveryStartParam"
        - $ref: "#/components/parameters/DeliveryEndParam"
        - $ref: "#/components/parameters/SlotNumberFromParam"
        - $ref: "#/components/parameters/SlotNumberToParam"
        - name: include_slots
          in: query
          description: Das Feld `slots` in die Antwort aufnehmen (Voreinstellung false). Bei false entfällt das Feld.
          schema:
            type: string
            enum:
              - "true"
              - "false"
            default: "false"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Nominierungen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NominationList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/nominations/{nomination_id}:
    get:
      operationId: getNomination
      summary: Nominierung abrufen
      description: "Eine einzelne Nominierung samt Gegenseite und Zeitscheiben abrufen.\n\nErforderlicher Scope: `nominations:read`"
      tags:
        - Nominations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - nominations:read
      parameters:
        - name: nomination_id
          in: path
          required: true
          description: Kennung der Nominierung
          schema:
            type: string
            example: nom_t4u5v6w7x8
      responses:
        "200":
          description: Angaben zur Nominierung
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Nomination"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/nominations/{nomination_id}/history:
    get:
      operationId: getNominationHistory
      summary: Versionsverlauf einer Nominierung abrufen
      description: "Den vollständigen Versionsverlauf einer Nominierung abrufen, entlang der Kette `previous_nomination_id`. Liefert alle Versionen, von der neuesten zur ältesten sortiert.\n\nErforderlicher Scope: `nominations:read`"
      tags:
        - Nominations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - nominations:read
      parameters:
        - name: nomination_id
          in: path
          required: true
          description: Kennung der Nominierung
          schema:
            type: string
            example: nom_t4u5v6w7x8
      responses:
        "200":
          description: Versionsverlauf der Nominierung
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NominationHistoryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/nominations/bulk:
    get:
      operationId: bulkGetNominations
      summary: Mehrere Nominierungen abrufen
      description: "Mehrere Nominierungen über ihre Kennungen in einer einzigen Anfrage abrufen. Über den Query-Parameter sind höchstens 100 Kennungen möglich. Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen.\n\nErforderlicher Scope: `nominations:read`"
      tags:
        - Nominations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - nominations:read
      parameters:
        - name: ids
          in: query
          required: true
          description: Kommagetrennte Liste von Nominierungskennungen (höchstens 100)
          schema:
            type: string
            example: nom_t4u5v6w7x8,nom_q1r2s3t4u5
      responses:
        "200":
          description: Liste der Nominierungen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkNominationList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: bulkPostNominations
      summary: Mehrere Nominierungen abrufen (POST)
      description: "Mehrere Nominierungen über ihre Kennungen im Anfrage-Body abrufen. Dieser Weg ist für große Kennungsmengen gedacht, die über das Limit des GET-Query-Parameters hinausgehen. Kennungen, die nicht existieren oder nicht zugänglich sind, werden stillschweigend übergangen.\n\nErforderlicher Scope: `nominations:read`"
      tags:
        - Nominations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - nominations:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkNominationIdsRequest"
      responses:
        "200":
          description: Liste der Nominierungen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkNominationList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/customers:
    get:
      operationId: listCustomers
      summary: Kunden auflisten
      description: "Die Kunden auflisten, die dem angemeldeten BKV zugeordnet sind.\n\nErforderlicher Scope: `customers:read`"
      tags:
        - Customers
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - customers:read
      parameters:
        - name: status
          in: query
          description: Nach Kundenstatus filtern
          schema:
            type: string
            enum:
              - pending
              - active
              - deactivated
        - name: search
          in: query
          description: Freitextsuche über Namen und Metadatenwerte
          schema:
            type: string
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Kunden
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/customers/{customer_id}:
    get:
      operationId: getCustomer
      summary: Kunden abrufen
      description: "Einen einzelnen Kunden über seine Kennung abrufen.\n\nErforderlicher Scope: `customers:read`"
      tags:
        - Customers
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - customers:read
      parameters:
        - name: customer_id
          in: path
          required: true
          description: Kennung des Kunden
          schema:
            type: string
            example: cust_r8s9t0u1
      responses:
        "200":
          description: Angaben zum Kunden
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateCustomer
      summary: Kunden aktualisieren
      description: "Status, Bilanzkreis oder Metadaten eines Kunden aktualisieren. Damit wird ein ausstehender Kunde aktiviert, ein bestehender deaktiviert, sein Bilanzkreis gewechselt oder seine eigenen Metadaten gepflegt. Metadaten werden beim Aktualisieren zusammengeführt — nur übergebene Schlüssel werden ergänzt oder überschrieben. Um einen Schlüssel zu entfernen, setzen Sie seinen Wert auf `null`.\n\nErforderlicher Scope: `customers:write`"
      tags:
        - Customers
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - customers:write
      parameters:
        - name: customer_id
          in: path
          required: true
          description: Kennung des Kunden
          schema:
            type: string
            example: cust_r8s9t0u1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerUpdate"
      responses:
        "200":
          description: Aktualisierter Kunde
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
