openapi: 3.0.0
info:
  title: Otark 1-Click PPA API
  description: API für den Anfrage- und Angebotsablauf von 1-Click PPA — Anfragen anlegen, Angebote sichten und annehmen — sowie zum Abruf von Einzelverträgen, Lieferdaten und der REMIT-Meldeeinstellung. Das Geld fließt direkt zwischen den Parteien; OES liefert die Datengrundlage der Abrechnung.
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.com
    description: Produktion
tags:
  - name: Counterparties
    description: Die aktiven Verbindungen des angemeldeten Unternehmens samt ihrem Verbindungsstatus
  - name: RFQs
    description: Anfragen — vom Käufer angelegt und an einen ausdrücklichen Empfängerkreis gesendet
  - name: Quotes
    description: Die Angebote auf eine Anfrage — verbindliche Angebote sind annehmbar, indikative nicht
  - name: Contracts
    description: Einzelverträge („1-Click PPA“), die mit der Annahme eines verbindlichen Angebots entstehen
  - name: Deliveries
    description: Indexwerte und gelieferte Mengen je Stunde und Monat — die Datengrundlage der Abrechnung zwischen den Parteien
  - name: REMIT
    description: Die REMIT-Meldeeinstellung des Teilnehmers
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    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: cpt_a1b2c3d4
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  headers:
    X-RateLimit-Limit:
      description: Höchstzahl der Anfragen je Zeitfenster — eine Ratenbegrenzung gilt; die Antwort nennt die Einzelheiten in den Headern
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Verbleibende Anfragen im laufenden Zeitfenster
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Sekunden, bis das Zeitfenster der Ratenbegrenzung zurückgesetzt wird
      schema:
        type: integer
  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: rfq_k8m2p4q7
      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://api.otark.com/errors/indicative_quote_not_acceptable
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Indicative Quote Not Acceptable
        status:
          type: integer
          description: HTTP-Statuscode
          example: 409
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: Indicative quotes cannot be accepted. Only binding quotes can be accepted.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/quotes/qte_c4x8p2n6/accept
        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: nominal_power
        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: value_too_small
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: Nominal power must be at least 1 MW
      required:
        - code
        - message
    Counterparty:
      type: object
      description: Eine Counterparty-Verbindung des angemeldeten Unternehmens. Zwei Unternehmen handeln bei 1-Click PPA nur miteinander, solange sie als Counterparties mit bestätigtem Rahmenvertrag verbunden sind.
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Verbindung
          example: cpt_5m8k2r6d
        company_id:
          type: string
          description: Unternehmenskennung der Counterparty — damit wird das Unternehmen als Empfänger einer Anfrage adressiert
          example: cmp_7d3f9k2a
        company_name:
          type: string
          description: Name des Unternehmens der Counterparty
          example: Solar Nord
        status:
          type: string
          description: "Verbindungsstatus: `invited` (Einladung offen), `onboarding` (angenommen, Dokumente in Vorbereitung), `confirmation` (die Zeichnungsberechtigten sind zur Bestätigung aufgefordert), `active` (Rahmenvertrag in Kraft — verbindliche Anfragen und Angebote sind möglich), `declined` (Einladung abgelehnt), `ended` (abgebrochen oder gekündigt; eine neue Einladung beginnt von vorn)"
          enum:
            - invited
            - onboarding
            - confirmation
            - active
            - declined
            - ended
          example: active
        roles:
          type: array
          description: Die Rollen, die die Counterparty auf der Plattform aktiviert hat — ein Unternehmen kann beide innehaben
          items:
            type: string
            enum:
              - buyer
              - seller
          example:
            - seller
        offers_granular_certificates:
          type: boolean
          description: Ob die Counterparty als Verkäufer granulare Zertifikate anbietet. Anfragen mit der Anforderung granularer Zertifikate lassen sich nur an Verkäufer mit dieser Einstellung richten.
          example: true
        contract_language:
          type: string
          description: Vertragssprache der Verbindung — Rahmenvertrag, Anpassungsvereinbarung und Einzelverträge entstehen in dieser Sprache
          enum:
            - de
            - en
          example: de
        election_sheet:
          type: boolean
          description: Ob für diese Verbindung eine Anpassungsvereinbarung gilt
          example: true
        general_agreement_date:
          type: string
          format: date
          nullable: true
          description: Datum, zu dem der Rahmenvertrag in Kraft getreten ist (letzte Bestätigung eines Zeichnungsberechtigten). Null, solange die Verbindung nicht aktiv ist.
          example: "2026-05-04"
        invited_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Einladung (UTC)
          example: "2026-04-28T09:12:00Z"
        activated_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel, zu dem die Verbindung aktiv wurde (UTC). Null, solange sie es nicht ist.
          example: "2026-05-04T14:30:00Z"
      required:
        - id
        - company_id
        - company_name
        - status
        - roles
        - offers_granular_certificates
        - contract_language
        - election_sheet
        - general_agreement_date
        - invited_at
        - activated_at
    CounterpartyList:
      type: object
      properties:
        counterparties:
          type: array
          description: Liste der Counterparty-Verbindungen
          items:
            $ref: "#/components/schemas/Counterparty"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - counterparties
        - pagination
    DeliveryPeriod:
      type: object
      description: Eine Lieferperiode — eine der derzeit handelbaren Perioden, die die Plattform anbietet, ein Jahr, ein Quartal, ein Monat oder eine Woche
      properties:
        id:
          type: string
          description: Kennung der Periode aus der Liste der handelbaren Perioden, etwa `2026-Q3` für ein Quartal oder `2027` für ein Jahr. Diese Kennung wird beim Anlegen einer Anfrage verwendet.
          example: 2026-Q3
        type:
          type: string
          description: Art der Periode
          enum:
            - year
            - quarter
            - month
            - week
          example: quarter
        display_name:
          type: string
          description: Anzeigename der Periode
          example: Q3 2026
        delivery_start:
          type: string
          format: date
          description: Erster Liefertag der Periode
          example: "2026-07-01"
        delivery_end:
          type: string
          format: date
          description: Letzter Liefertag der Periode
          example: "2026-09-30"
      required:
        - id
        - type
        - display_name
        - delivery_start
        - delivery_end
    RfqRecipient:
      type: object
      description: Ein Empfänger einer Anfrage samt seinem eigenen Status
      properties:
        company_id:
          type: string
          description: Unternehmenskennung des Empfängers
          example: cmp_7d3f9k2a
        company_name:
          type: string
          description: Name des Unternehmens des Empfängers
          example: Solar Nord
        type:
          type: string
          description: "Empfängerklasse: `binding` (aktive Counterparty — ihre Angebote sind annehmbar) oder `indicative` (keine Verbindung nötig — ihre Angebote sind indikativ und nicht annehmbar)"
          enum:
            - binding
            - indicative
          example: binding
        status:
          type: string
          description: "Status des Empfängers: `received` (Anfrage zugestellt), `viewed` (der Empfänger hat die Anfrage geöffnet), `quoted` (Angebot abgegeben), `declined` (mit Grund abgelehnt; endgültig)"
          enum:
            - received
            - viewed
            - quoted
            - declined
          example: quoted
        decline_reason:
          type: string
          nullable: true
          description: Der bei der Ablehnung angegebene Grund — genau einer aus einer festen Liste. Null, solange der Empfänger nicht abgelehnt hat.
          enum:
            - cant_deliver_in_requested_period
            - requested_volume_too_high
            - requested_volume_too_low
            - delivery_profile_mismatch
            - out_of_sales_scope
            - technology_mismatch
            - other
          example: null
      required:
        - company_id
        - company_name
        - type
        - status
        - decline_reason
    Rfq:
      type: object
      description: Eine Anfrage — die Nachfrage eines Käufers an ausgewählte Verkäufer. Die Anfrage ist kein Gebot; erst die Annahme eines Angebots bindet den Käufer.
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Anfrage
          example: rfq_h7t2m9c4
        status:
          type: string
          description: "Status der Anfrage: `scheduled` (angelegt, Veröffentlichung steht aus), `active` (veröffentlicht, das Angebotsfenster läuft oder die anschließende Auswahlphase von 30 Minuten), `accepted` (ein Angebot wurde angenommen — der Einzelvertrag besteht), `expired` (Angebotsfenster und Auswahlphase endeten ohne Annahme), `cancelled` (vom Käufer abgebrochen)"
          enum:
            - scheduled
            - active
            - accepted
            - expired
            - cancelled
          example: active
        energy_source:
          type: string
          description: Energieträger — bestimmt zugleich den Referenzindex
          enum:
            - solar
            - wind
          example: solar
        reference_index:
          type: string
          description: Referenzindex, der sich aus dem Energieträger ergibt — angezeigt, nicht gewählt
          enum:
            - ENWEX Solar DE
            - ENWEX Wind DE
          example: ENWEX Solar DE
        delivery_period:
          $ref: "#/components/schemas/DeliveryPeriod"
        nominal_power:
          type: number
          description: Angefragte Vertragsleistung in MW (mindestens 1, Schrittweite 0,01)
          example: 10.0
        max_nominal_power_deviation:
          type: number
          description: Zulässige Abweichung der angebotenen Leistung in Prozent, nach oben und nach unten. 0 heißt, dass nur Angebote mit genau der angefragten Leistung angenommen werden.
          example: 10
        granular_certificates:
          type: boolean
          description: Ob Lieferung mit granularen Zertifikaten verlangt ist. Ist der Wert gesetzt, ging die Anfrage nur an Verkäufer, die granulare Zertifikate anbieten, und der Einzelvertrag trägt das Merkmal GC-unterlegt.
          example: true
        estimated_delivery_volume:
          type: number
          description: Geschätzte Liefermenge in MWh, von der Plattform aus Leistung und Indexprognose der Periode berechnet
          example: 4300.000
        quoting_window_minutes:
          type: integer
          description: Länge des Angebotsfensters in Minuten, gezählt ab der Veröffentlichung — 2 bis 24 Stunden in Schritten von 2 Stunden
          enum:
            - 120
            - 240
            - 360
            - 480
            - 600
            - 720
            - 840
            - 960
            - 1080
            - 1200
            - 1320
            - 1440
          example: 480
        publication:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Veröffentlichung (UTC). Bei einer geplanten Anfrage die vorgesehene Veröffentlichungszeit.
          example: "2026-05-12T07:00:00Z"
        expires_at:
          type: string
          format: date-time
          description: ISO-8601-Ende des Angebotsfensters (UTC). Danach lassen sich Angebote weder abgeben noch ändern noch zurückziehen; annehmen lässt sich ein verbindliches Angebot noch in der Auswahlphase von 30 Minuten.
          example: "2026-05-12T15:00:00Z"
        recipients:
          type: array
          description: Der ausdrückliche Empfängerkreis samt Status je Empfänger — eine Anfrage geht nie „an den Markt“
          items:
            $ref: "#/components/schemas/RfqRecipient"
        accepted_quote_id:
          type: string
          nullable: true
          description: Kennung des angenommenen Angebots. Null, solange kein Angebot angenommen ist.
          example: null
        contract_number:
          type: string
          nullable: true
          description: Vertragsnummer des mit der Annahme entstandenen Einzelvertrags. Null, solange kein Angebot angenommen ist.
          example: null
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage (UTC)
          example: "2026-05-12T07:00:00Z"
      required:
        - id
        - status
        - energy_source
        - reference_index
        - delivery_period
        - nominal_power
        - max_nominal_power_deviation
        - granular_certificates
        - estimated_delivery_volume
        - quoting_window_minutes
        - publication
        - expires_at
        - recipients
        - accepted_quote_id
        - contract_number
        - created_at
    RfqList:
      type: object
      properties:
        rfqs:
          type: array
          description: Liste der Anfragen
          items:
            $ref: "#/components/schemas/Rfq"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - rfqs
        - pagination
    RfqCreate:
      type: object
      description: Eine neue Anfrage. Der Preis ist nicht Teil der Anfrage — der Käufer sieht Preise, wenn die Angebote eingehen. Preisformel, Lieferprofil, HKN-Mechanik und Zahlungsbedingungen stehen durch Rahmenvertrag und Plattform fest.
      properties:
        energy_source:
          type: string
          description: Energieträger — bestimmt den Referenzindex (ENWEX Solar DE oder ENWEX Wind DE)
          enum:
            - solar
            - wind
          example: solar
        delivery_period:
          type: string
          description: Kennung der Lieferperiode aus der Liste der handelbaren Perioden, etwa `2026-Q3` für ein Quartal oder `2027` für ein Jahr. Sie muss eine der derzeit handelbaren Perioden sein; genau eine je Anfrage.
          example: 2026-Q3
        nominal_power:
          type: number
          description: Vertragsleistung in MW (mindestens 1, Schrittweite 0,01)
          minimum: 1
          example: 10.0
        max_nominal_power_deviation:
          type: number
          description: Zulässige Abweichung der angebotenen Leistung in Prozent, nach oben und nach unten. 0 heißt, dass nur Angebote mit genau der angefragten Leistung zulässig sind.
          minimum: 0
          maximum: 100
          default: 0
          example: 10
        granular_certificates:
          type: boolean
          description: Lieferung mit granularen Zertifikaten verlangen. Ist der Wert gesetzt, darf die Anfrage nur an Verkäufer gehen, die granulare Zertifikate anbieten; jeder Empfänger sieht die Anforderung, und der Einzelvertrag trägt das Merkmal GC-unterlegt.
          default: false
          example: true
        binding_recipients:
          type: array
          description: Unternehmenskennungen aktiver Counterparties in der Verkäuferrolle. Ihre Angebote sind verbindlich und annehmbar — ohne verbindliche Empfänger führt eine Anfrage zu keinem Abschluss. Die Angabe kann entfallen, wenn `indicative_recipients` mindestens einen Empfänger nennt.
          items:
            type: string
          example:
            - cmp_7d3f9k2a
            - cmp_2b8n5t1q
        indicative_recipients:
          type: array
          description: Unternehmenskennungen von Unternehmen in der Verkäuferrolle, die den Empfang indikativer Anfragen aktiviert haben und noch keine Counterparties sind. Ihre Angebote sind indikativ und nicht annehmbar. Die Angabe kann entfallen.
          items:
            type: string
          example: []
        quoting_window_minutes:
          type: integer
          description: Länge des Angebotsfensters in Minuten, gezählt ab der Veröffentlichung — 2 bis 24 Stunden in Schritten von 2 Stunden
          enum:
            - 120
            - 240
            - 360
            - 480
            - 600
            - 720
            - 840
            - 960
            - 1080
            - 1200
            - 1320
            - 1440
          default: 480
          example: 480
        publication:
          type: string
          format: date-time
          description: Geplante Veröffentlichungszeit (ISO 8601, UTC). Bleibt sie weg, wird sofort veröffentlicht — die Anfrage ist mit dem Anlegen aktiv. Die Empfänger werden in jedem Fall mit dem Anlegen benachrichtigt.
          example: "2026-05-12T07:00:00Z"
      required:
        - energy_source
        - delivery_period
        - nominal_power
    QuoteAsset:
      type: object
      description: Eine im Angebot genannte Erzeugungsanlage. Die Stammdaten der Anlage werden Teil des Einzelvertrags.
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Anlage
          example: ast_3p7q1z5v
        name:
          type: string
          description: Anzeigename der Anlage
          example: Solar Park SP-1
        technology:
          type: string
          description: Erzeugungstechnologie
          enum:
            - solar
            - wind
          example: solar
        nominal_power:
          type: number
          description: Installierte Leistung in MW
          example: 10.0
        annual_production:
          type: number
          description: Jahreserzeugung in MWh
          example: 10400
        mastr_number:
          type: string
          description: Nummer der Anlage im Marktstammdatenregister
          example: SEE900012345678
      required:
        - id
        - name
        - technology
        - nominal_power
        - annual_production
        - mastr_number
    QuoteSeller:
      type: object
      description: Der Verkäufer, der das Angebot abgegeben hat
      properties:
        company_id:
          type: string
          description: Unternehmenskennung des Verkäufers
          example: cmp_7d3f9k2a
        company_name:
          type: string
          description: Name des Unternehmens des Verkäufers
          example: Solar Nord
      required:
        - company_id
        - company_name
    Quote:
      type: object
      description: Das Angebot eines Verkäufers auf eine Anfrage — Preis, Leistung, Anlagen. Ob ein Angebot verbindlich oder indikativ ist, folgt der Klasse, in der der Käufer den Verkäufer adressiert hat; der Verkäufer wählt sie nicht.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Angebots
          example: qte_c4x8p2n6
        rfq_id:
          type: string
          description: Kennung der Anfrage, auf die das Angebot antwortet
          example: rfq_h7t2m9c4
        type:
          type: string
          description: "`binding` — der Käufer kann es annehmen; `indicative` — nur Preis und Verfügbarkeit, nicht annehmbar"
          enum:
            - binding
            - indicative
          example: binding
        status:
          type: string
          description: "Status des Angebots: `active` (gültig, bis der Käufer entscheidet oder das Fenster endet), `revoked` (vom Verkäufer zurückgezogen; für den Käufer unsichtbar), `accepted` (der Einzelvertrag besteht), `not_selected` (ein anderes Angebot wurde angenommen, die Anfrage lief ab oder wurde abgebrochen)"
          enum:
            - active
            - revoked
            - accepted
            - not_selected
          example: active
        price_per_mwh:
          type: number
          description: Angebotener Preis in EUR/MWh (zwei Nachkommastellen, mindestens 1,00). Der Preis ist der Kaufpreis einschließlich der Herkunftsnachweise; eine gesonderte HKN-Komponente gibt es nicht.
          example: 52.11
        nominal_power:
          type: number
          description: Angebotene Leistung in MW — innerhalb der Toleranz der Anfrage; ein Angebot außerhalb der Spanne weist die Plattform zurück
          example: 10.000
        estimated_delivery_volume:
          type: number
          description: Geschätzte Liefermenge in MWh, von der Plattform für die angebotene Leistung berechnet
          example: 4300.000
        assets:
          type: array
          description: Die Anlagen des angefragten Energieträgers, die das Angebot unterlegen (mindestens eine)
          items:
            $ref: "#/components/schemas/QuoteAsset"
        message:
          type: string
          nullable: true
          description: Freitextnachricht an den Käufer (bis zu 2.000 Zeichen) — nur bei indikativen Angeboten. Bei verbindlichen Angeboten null.
          example: null
        seller:
          $ref: "#/components/schemas/QuoteSeller"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Abgabe (UTC)
          example: "2026-05-12T07:40:00Z"
      required:
        - id
        - rfq_id
        - type
        - status
        - price_per_mwh
        - nominal_power
        - estimated_delivery_volume
        - assets
        - message
        - seller
        - created_at
    QuoteList:
      type: object
      properties:
        quotes:
          type: array
          description: Liste der Angebote auf die Anfrage. Zurückgezogene Angebote bekommt der Käufer nicht zu sehen.
          items:
            $ref: "#/components/schemas/Quote"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - quotes
        - pagination
    ContractParty:
      type: object
      description: Eine Partei des Einzelvertrags
      properties:
        company_id:
          type: string
          description: Unternehmenskennung der Partei
          example: cmp_7d3f9k2a
        company_name:
          type: string
          description: Name der Partei
          example: Solar Nord
      required:
        - company_id
        - company_name
    Contract:
      type: object
      description: Ein Einzelvertrag („1-Click PPA“), der im Moment der Annahme eines verbindlichen Angebots entsteht. Das unveränderlich archivierte Vertragsdokument steht als PDF bereit.
      properties:
        contract_number:
          type: string
          description: Vertragsnummer — fünf Zeichen, Großbuchstaben und Ziffern. Beide Parteien führen den Vertrag unter dieser Nummer; sie ist zugleich die Referenz gegenüber dem Bilanzkreisverantwortlichen.
          example: 7K2QP
        status:
          type: string
          description: "Lieferstatus: `pending` (abgeschlossen, die Lieferperiode hat noch nicht begonnen), `in_progress` (ab einer Stunde vor Lieferbeginn bis zum Lieferende), `completed` (das Lieferende ist erreicht; die letzte Monatsrechnung und die HKN-Übertragung können noch ausstehen). Der Status beschreibt die Lieferperiode, nicht die Abrechnung und nicht die HKN-Spur. Nach einer außerordentlichen Kündigung folgt der Status weiter den vereinbarten Lieferdaten; OES stellt für den Vertrag ab dann keine Fahrpläne und Nominierungen mehr bereit."
          enum:
            - pending
            - in_progress
            - completed
          example: in_progress
        role:
          type: string
          description: Die Rolle des angemeldeten Unternehmens in diesem Vertrag
          enum:
            - buyer
            - seller
          example: buyer
        buyer:
          description: Der Käufer des Vertrags
          example:
            company_id: cmp_9s4w2e8b
            company_name: Stadtwerke
          allOf:
            - $ref: "#/components/schemas/ContractParty"
        seller:
          description: Der Verkäufer des Vertrags
          example:
            company_id: cmp_7d3f9k2a
            company_name: Solar Nord
          allOf:
            - $ref: "#/components/schemas/ContractParty"
        energy_source:
          type: string
          description: Primärenergieträger
          enum:
            - solar
            - wind
          example: solar
        reference_index:
          type: string
          description: Referenzindex des Vertrags (Indexanbieter Enwex GmbH, von OES lizenziert)
          enum:
            - ENWEX Solar DE
            - ENWEX Wind DE
          example: ENWEX Solar DE
        delivery_period:
          $ref: "#/components/schemas/DeliveryPeriod"
        nominal_power:
          type: number
          description: Vertragsleistung in MW. Die Liefermenge ist dynamisch — Leistung × Indexprofil („as indexed“).
          example: 10.000
        price_per_mwh:
          type: number
          description: Kaufpreis in EUR/MWh aus dem angenommenen Angebot, einschließlich der Herkunftsnachweise
          example: 52.11
        gc_backed:
          type: boolean
          description: Ob der Vertrag GC-unterlegt ist — aus der Anfrage übernommen, ab dem Abschluss fest. Ist der Wert gesetzt, schuldet der Verkäufer für diesen Vertrag granulare Zertifikate.
          example: true
        assets:
          type: array
          description: Die Erzeugungsquellen des Vertrags, aus dem Angebot übernommen
          items:
            $ref: "#/components/schemas/QuoteAsset"
        general_agreement_date:
          type: string
          format: date
          description: Datum des Rahmenvertrags, den der Vertrag ergänzt
          example: "2026-05-04"
        concluded_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel des Abschlusses — der Moment der Annahme (UTC)
          example: "2026-05-12T08:42:17Z"
        document_url:
          type: string
          description: URL des unveränderlich archivierten Vertragsdokuments (PDF), erzeugt in der Vertragssprache der Verbindung
          example: https://api.otark.com/v1/contracts/7K2QP/document
      required:
        - contract_number
        - status
        - role
        - buyer
        - seller
        - energy_source
        - reference_index
        - delivery_period
        - nominal_power
        - price_per_mwh
        - gc_backed
        - assets
        - general_agreement_date
        - concluded_at
        - document_url
    ContractList:
      type: object
      properties:
        contracts:
          type: array
          description: Liste der Einzelverträge
          items:
            $ref: "#/components/schemas/Contract"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - contracts
        - pagination
    DeliveryMonth:
      type: object
      description: Die Lieferdaten eines Kalendermonats eines Vertrags — die Datengrundlage der Monatsrechnung des Verkäufers
      properties:
        month:
          type: string
          description: Kalendermonat im Format `YYYY-MM`
          example: 2026-07
        expected_volume:
          type: number
          description: Erwartete Menge in MWh — Vertragsleistung × Indexprofil, über den Monat aufsummiert
          example: 1580.000
        delivered_volume:
          type: number
          description: Gelieferte Menge in MWh — die Summe der gültigen Transaktionen des Vertrags im Monat. Eine Korrektur ersetzt eine Transaktion durch eine neue Version; der Wert gibt stets den aktuell gültigen Stand wieder.
          example: 1580.000
        go_quantity:
          type: integer
          description: "Die für den Monat geschuldeten Herkunftsnachweise — die abgerundete kumulierte Liefermenge des Vertrags seit Lieferbeginn, abzüglich der bereits übertragenen HKN; der Bruchteil wird in den nächsten Liefermonat vorgetragen. Im letzten Liefermonat der Periode rundet OES kaufmännisch; einen Vortrag über das Lieferende hinaus gibt es nicht (Beispiel: 4.302 HKN für 4.301,740 MWh in Q3 2026)"
          example: 1580
        amount:
          type: number
          description: "Gelieferte Menge × Kaufpreis, in EUR: die Datengrundlage der Rechnung. Der Verkäufer rechnet monatlich ab und der Käufer zahlt unmittelbar an ihn; OES rechnet nicht ab."
          example: 82333.80
      required:
        - month
        - expected_volume
        - delivered_volume
        - go_quantity
        - amount
    DeliveryHour:
      type: object
      description: Die Lieferdaten einer Stunde
      properties:
        date:
          type: string
          format: date
          description: Liefertag
          example: "2026-07-15"
        hour:
          type: integer
          description: Stunde des Liefertags, 1–24 nach der EPEX-Konvention — Stunde 14 umfasst 13:00–14:00 Uhr Europe/Berlin. Am 25-Stunden-Tag der Umstellung auf Winterzeit tritt Stunde 3 zweimal auf; die beiden Zeilen unterscheidet `hour_suffix`
          minimum: 1
          maximum: 24
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: Nur am langen Tag der Umstellung auf Winterzeit gesetzt, an dem die doppelte Stunde 3 als 3A (`A`, noch MESZ) und 3B (`B`, schon MEZ) geführt wird — zwei verschiedene Lieferstunden; an allen anderen Tagen null. Am 23-Stunden-Tag der Umstellung auf Sommerzeit fehlt Stunde 3 in den Stundenzeilen
          enum:
            - A
            - B
          example: null
        index_value:
          type: number
          description: Indexwert der Stunde in Prozent — die Liefermenge ist Vertragsleistung × Indexwert
          example: 62.50
        expected_volume:
          type: number
          description: Erwartete Menge in MWh (3 Nachkommastellen)
          example: 6.250
        delivered_volume:
          type: number
          description: Gelieferte Menge in MWh (3 Nachkommastellen) — die aktuell gültige Transaktionsmenge der Stunde
          example: 6.250
      required:
        - date
        - hour
        - index_value
        - expected_volume
        - delivered_volume
    DeliveryMonthList:
      type: object
      properties:
        contract_number:
          type: string
          description: Vertragsnummer
          example: 7K2QP
        months:
          type: array
          description: Die monatlichen Lieferdaten, beginnend mit dem ersten Monat der Lieferperiode
          items:
            $ref: "#/components/schemas/DeliveryMonth"
      required:
        - contract_number
        - months
    DeliveryMonthDetail:
      type: object
      description: Die stündlichen Lieferdaten eines Kalendermonats eines Vertrags
      properties:
        contract_number:
          type: string
          description: Vertragsnummer
          example: 7K2QP
        price_per_mwh:
          type: number
          description: Kaufpreis in EUR/MWh, einschließlich der Herkunftsnachweise
          example: 52.11
        summary:
          $ref: "#/components/schemas/DeliveryMonth"
        hours:
          type: array
          description: Die Stundenzeilen des Monats, nach Tag und Stunde sortiert
          items:
            $ref: "#/components/schemas/DeliveryHour"
      required:
        - contract_number
        - price_per_mwh
        - summary
        - hours
    RemitSetting:
      type: object
      description: Die REMIT-Meldeeinstellung des Teilnehmers. Voreingestellt meldet OES über eine beauftragte registrierte Meldestelle (RRM) jeden Einzelvertrag und jedes Green-SPOT-Geschäft für die Seite des Teilnehmers; die Einstellung gilt je Teilnehmer für alle Verbindungen und Green SPOT. Die Meldepflicht bleibt rechtlich beim Marktteilnehmer.
      properties:
        mode:
          type: string
          description: "`oes_reporting` — OES meldet die Seite des Teilnehmers für jeden Einzelvertrag und jedes Green-SPOT-Geschäft; `self_reporting` — der Teilnehmer meldet seine eigene Seite selbst, für alle Verbindungen und Green SPOT"
          enum:
            - oes_reporting
            - self_reporting
          example: oes_reporting
        status:
          type: string
          description: "Status der Einstellung: `pending_review` (Kennung eingereicht, die Prüfung durch die Otark GmbH steht aus), `active` (die Meldung durch OES ist aktiv), `deregistered` (der Teilnehmer meldet selbst)"
          enum:
            - pending_review
            - active
            - deregistered
          example: active
        market_participant_code:
          type: string
          nullable: true
          description: Marktteilnehmerkennung, unter der OES die Seite des Teilnehmers meldet — ACER-Code, LEI, BIC, EIC oder GLN. Im Selbstmeldemodus null.
          example: A0001234W.DE
        code_type:
          type: string
          nullable: true
          description: Art der Marktteilnehmerkennung. Im Selbstmeldemodus null.
          enum:
            - acer_code
            - lei
            - bic
            - eic
            - gln
          example: acer_code
        updated_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der letzten Änderung (UTC)
          example: "2026-04-20T10:15:00Z"
      required:
        - mode
        - status
        - market_participant_code
        - code_type
        - updated_at
    RemitSettingUpdate:
      type: object
      description: "Erstmalige Wahl des Meldemodus. Sie gilt für den Teilnehmer, für alle seine Verbindungen und für Green SPOT. Ein späterer Wechsel des Meldemodus läuft über den Support. Wer `self_reporting` wählt, meldet seine Seite selbst und trägt die Folgen einer unterlassenen Meldung allein; OES meldet dann nur die Seite der Gegenpartei. Bei 1-Click PPA vereinbaren die Parteien das Selbstmelden in der Anpassungsvereinbarung, die Wahl des Meldemodus ist ihre technische Umsetzung. Änderungen an der Marktteilnehmerkennung laufen über den Support, weil sie in laufende Meldeketten eingreifen."
      properties:
        mode:
          type: string
          description: Neuer Meldemodus
          enum:
            - oes_reporting
            - self_reporting
          example: self_reporting
      required:
        - mode
  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://api.otark.com/errors/rfq_not_found
            title: Anfrage nicht gefunden
            status: 404
            instance: /v1/rfqs/rfq_h7t2m9c4
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/rfqs
            errors:
              - field: nominal_power
                code: value_too_small
                message: Nominal power must be at least 1 MW
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/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://api.otark.com/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: rfq: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://api.otark.com/errors/indicative_quote_not_acceptable
            title: Indikatives Angebot nicht annehmbar
            status: 409
            detail: Indicative quotes cannot be accepted. Only binding quotes can be accepted.
    RateLimited:
      description: Ratenbegrenzung überschritten
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/counterparties:
    get:
      operationId: listCounterparties
      summary: Counterparties auflisten
      description: "Die Counterparty-Verbindungen des angemeldeten Unternehmens samt Verbindungsstatus auflisten. Nur aktive Counterparties in der Verkäuferrolle lassen sich als verbindliche Empfänger einer Anfrage adressieren.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - Counterparties
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      parameters:
        - name: status
          in: query
          description: Nach Verbindungsstatus filtern
          schema:
            type: string
            enum:
              - invited
              - onboarding
              - confirmation
              - active
              - declined
              - ended
        - name: role
          in: query
          description: Nach einer aktivierten Rolle der Counterparty filtern
          schema:
            type: string
            enum:
              - buyer
              - seller
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Counterparties
          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/CounterpartyList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/counterparties/{counterparty_id}:
    get:
      operationId: getCounterparty
      summary: Counterparty abrufen
      description: "Eine einzelne Counterparty-Verbindung über ihre Kennung abrufen.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - Counterparties
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      parameters:
        - name: counterparty_id
          in: path
          required: true
          description: Kennung der Verbindung
          schema:
            type: string
            example: cpt_5m8k2r6d
      responses:
        "200":
          description: Angaben zur Counterparty
          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/Counterparty"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/rfqs:
    post:
      operationId: createRfq
      summary: Anfrage anlegen
      description: "Eine Anfrage anlegen. Die Anfrage geht an einen ausdrücklichen Empfängerkreis — verbindliche Empfänger sind aktive Counterparties in der Verkäuferrolle; indikative Empfänger brauchen keine Verbindung, und ihre Angebote sind nicht annehmbar.\n\nIst `granular_certificates` gesetzt, darf die Anfrage nur an Verkäufer gehen, die granulare Zertifikate anbieten; jeder Empfänger sieht die Anforderung, und der mit der Annahme entstehende Einzelvertrag trägt das Merkmal GC-unterlegt.\n\nDie Empfänger werden mit dem Anlegen benachrichtigt. Ohne `publication` wird die Anfrage sofort veröffentlicht; mit geplanter Veröffentlichungszeit bleibt sie bis dahin `scheduled`. Das Angebotsfenster läuft ab der Veröffentlichung. Nach der Veröffentlichung stehen Energieträger, Lieferperiode und Leistung fest — die Verkäufer haben darauf angeboten. Die Empfängerliste steht mit dem Anlegen fest.\n\nErforderlicher Scope: `rfq:write`"
      tags:
        - RFQs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RfqCreate"
      responses:
        "201":
          description: Die angelegte Anfrage
          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/Rfq"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    get:
      operationId: listRfqs
      summary: Anfragen auflisten
      description: "Die Anfragen des angemeldeten Unternehmens auflisten, die neueste zuerst.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - RFQs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      parameters:
        - name: status
          in: query
          description: Nach Anfragestatus filtern
          schema:
            type: string
            enum:
              - scheduled
              - active
              - accepted
              - expired
              - cancelled
        - name: energy_source
          in: query
          description: Nach Energieträger filtern
          schema:
            type: string
            enum:
              - solar
              - wind
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Anfragen
          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/RfqList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/rfqs/{rfq_id}:
    get:
      operationId: getRfq
      summary: Anfrage abrufen
      description: "Eine einzelne Anfrage samt Empfängerkreis abrufen. Je Empfänger zeigt die Anfrage, ob sie zugestellt, geöffnet, beantwortet oder abgelehnt wurde — samt Ablehnungsgrund.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - RFQs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      parameters:
        - name: rfq_id
          in: path
          required: true
          description: Kennung der Anfrage
          schema:
            type: string
            example: rfq_h7t2m9c4
      responses:
        "200":
          description: Angaben zur Anfrage
          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/Rfq"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/rfqs/{rfq_id}/cancel:
    post:
      operationId: cancelRfq
      summary: Anfrage abbrechen
      description: "Eine Anfrage abbrechen, solange sie `scheduled` oder `active` ist. Alle aktiven Angebote gehen auf `not_selected`, und die Verkäufer mit einem aktiven Angebot werden benachrichtigt. Eine bereits angenommene, abgelaufene oder abgebrochene Anfrage lässt sich nicht abbrechen; der Vorgang antwortet mit `409`.\n\nErforderlicher Scope: `rfq:write`"
      tags:
        - RFQs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:write
      parameters:
        - name: rfq_id
          in: path
          required: true
          description: Kennung der Anfrage
          schema:
            type: string
            example: rfq_h7t2m9c4
      responses:
        "200":
          description: Die abgebrochene Anfrage
          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/Rfq"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/rfqs/{rfq_id}/quotes:
    get:
      operationId: listRfqQuotes
      summary: Angebote einer Anfrage auflisten
      description: "Die auf eine Anfrage eingegangenen Angebote auflisten. Verbindliche und indikative Angebote kommen gemeinsam zurück — der Filter `type` trennt sie. Annehmbar sind allein verbindliche Angebote; indikative dienen der Preisfindung und lassen sich nicht annehmen. Zurückgezogene Angebote werden nicht geliefert.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - Quotes
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      parameters:
        - name: rfq_id
          in: path
          required: true
          description: Kennung der Anfrage
          schema:
            type: string
            example: rfq_h7t2m9c4
        - name: type
          in: query
          description: Nach Angebotsart filtern
          schema:
            type: string
            enum:
              - binding
              - indicative
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Angebote
          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/QuoteList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/quotes/{quote_id}/accept:
    post:
      operationId: acceptQuote
      summary: Angebot annehmen
      description: "Ein verbindliches Angebot annehmen. Die Annahme läuft als eine untrennbare Transaktion: Angebot und Anfrage gehen auf `accepted`, der Einzelvertrag entsteht mit seiner fünfstelligen Vertragsnummer und dem Merkmal GC-unterlegt aus der Anfrage, das Vertragsdokument wird erzeugt und unveränderlich archiviert, und jedes andere aktive Angebot auf die Anfrage geht auf `not_selected`. Die Antwort liefert den entstandenen Vertrag.\n\nDie Annahme ist möglich, solange die Anfrage `active` ist — veröffentlicht und vor dem Ende der Auswahlphase, 30 Minuten nach dem Ende des Angebotsfensters. Die Verbindung zwischen Käufer und Verkäufer muss im Moment der Annahme aktiv sein. **Indikative Angebote sind nicht annehmbar**; ihre Annahme antwortet mit `409`. Es gibt keine Reservierung und keine Bestätigungsschleife: Die Annahme kann der Käufer nicht zurücknehmen, und der Verkäufer kann sie nicht ablehnen. Eine Anfrage erhält eine Annahme — eine Aufteilung der Menge auf mehrere Verkäufer gibt es nicht.\n\nEine Zahlung wird nicht ausgelöst: Das Geld fließt mit der ersten Monatsrechnung des Verkäufers direkt zwischen den Parteien.\n\nErforderlicher Scope: `rfq:write`"
      tags:
        - Quotes
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:write
      parameters:
        - name: quote_id
          in: path
          required: true
          description: Kennung des Angebots
          schema:
            type: string
            example: qte_c4x8p2n6
      responses:
        "200":
          description: Der mit der Annahme entstandene Einzelvertrag
          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"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/contracts:
    get:
      operationId: listContracts
      summary: Einzelverträge auflisten
      description: "Die Einzelverträge des angemeldeten Unternehmens auflisten — als Käufer und als Verkäufer, der neueste zuerst.\n\nErforderlicher Scope: `contracts:read`"
      tags:
        - Contracts
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
      parameters:
        - name: status
          in: query
          description: Nach Lieferstatus filtern
          schema:
            type: string
            enum:
              - pending
              - in_progress
              - completed
        - name: energy_source
          in: query
          description: Nach Energieträger filtern
          schema:
            type: string
            enum:
              - solar
              - wind
        - name: gc_backed
          in: query
          description: Nach dem Merkmal GC-unterlegt filtern
          schema:
            type: string
            enum:
              - "true"
              - "false"
        - name: role
          in: query
          description: Nach der Rolle des angemeldeten Unternehmens im Vertrag filtern
          schema:
            type: string
            enum:
              - buyer
              - seller
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Einzelverträ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_number}:
    get:
      operationId: getContract
      summary: Einzelvertrag abrufen
      description: "Einen einzelnen Einzelvertrag über seine Vertragsnummer abrufen, samt dem Link auf das archivierte Vertragsdokument und dem Merkmal GC-unterlegt.\n\nErforderlicher Scope: `contracts:read`"
      tags:
        - Contracts
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
      parameters:
        - name: contract_number
          in: path
          required: true
          description: Vertragsnummer (fünf Zeichen, Großbuchstaben und Ziffern)
          schema:
            type: string
            example: 7K2QP
      responses:
        "200":
          description: Angaben zum Einzelvertrag
          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_number}/document:
    get:
      operationId: getContractDocument
      summary: Vertragsdokument abrufen
      description: "Das unveränderlich archivierte Vertragsdokument als PDF herunterladen. Das Dokument entsteht im Moment der Annahme in der Vertragssprache der Verbindung und ändert sich danach nicht mehr.\n\nErforderlicher Scope: `contracts:read`"
      tags:
        - Contracts
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
      parameters:
        - name: contract_number
          in: path
          required: true
          description: Vertragsnummer (fünf Zeichen, Großbuchstaben und Ziffern)
          schema:
            type: string
            example: 7K2QP
      responses:
        "200":
          description: Das Vertragsdokument (PDF)
          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/pdf:
              schema:
                type: string
                format: binary
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/contracts/{contract_number}/deliveries:
    get:
      operationId: listContractDeliveries
      summary: Lieferdaten eines Vertrags auflisten
      description: "Die monatlichen Lieferdaten eines Vertrags auflisten: erwartete und gelieferte Menge, Herkunftsnachweise und den Betrag, gelieferte Menge × Kaufpreis. Das ist die Datengrundlage der Monatsrechnung des Verkäufers; das Geld fließt direkt zwischen den Parteien, OES liefert allein die Datengrundlage.\n\nErforderliche Scopes: `contracts:read`, `deliveries:read`"
      tags:
        - Deliveries
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
        - deliveries:read
      parameters:
        - name: contract_number
          in: path
          required: true
          description: Vertragsnummer (fünf Zeichen, Großbuchstaben und Ziffern)
          schema:
            type: string
            example: 7K2QP
      responses:
        "200":
          description: Monatliche Lieferdaten
          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/DeliveryMonthList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/contracts/{contract_number}/deliveries/{month}:
    get:
      operationId: getContractDeliveryMonth
      summary: Liefermonat eines Vertrags abrufen
      description: "Die stündlichen Lieferdaten eines Kalendermonats abrufen: je Stunde den Indexwert in Prozent, die erwartete und die gelieferte Menge in MWh. Die Stunden zählen 1–24 nach der EPEX-Konvention — Stunde 14 umfasst 13:00–14:00 Uhr Europe/Berlin. Eine Korrektur ersetzt eine Transaktion durch eine neue Version; die Zeilen geben stets den aktuell gültigen Stand wieder.\n\nErforderliche Scopes: `contracts:read`, `deliveries:read`"
      tags:
        - Deliveries
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - contracts:read
        - deliveries:read
      parameters:
        - name: contract_number
          in: path
          required: true
          description: Vertragsnummer (fünf Zeichen, Großbuchstaben und Ziffern)
          schema:
            type: string
            example: 7K2QP
        - name: month
          in: path
          required: true
          description: Kalendermonat im Format `YYYY-MM`
          schema:
            type: string
            pattern: "^\\d{4}-(0[1-9]|1[0-2])$"
            example: 2026-07
      responses:
        "200":
          description: Stündliche Lieferdaten des Monats
          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/DeliveryMonthDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/remit-setting:
    get:
      operationId: getRemitSetting
      summary: REMIT-Einstellung abrufen
      description: "Die REMIT-Meldeeinstellung des Teilnehmers abrufen. Voreingestellt ist die Meldung durch OES: OES meldet jeden Einzelvertrag und jedes Green-SPOT-Geschäft für die Seite des Teilnehmers unter der hinterlegten Marktteilnehmerkennung. Im Selbstmeldemodus meldet der Teilnehmer seine eigene Seite selbst, für alle Verbindungen und Green SPOT.\n\nErforderlicher Scope: `rfq:read`"
      tags:
        - REMIT
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:read
      responses:
        "200":
          description: Die REMIT-Meldeeinstellung
          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/RemitSetting"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    patch:
      operationId: updateRemitSetting
      summary: REMIT-Modus einmalig wählen
      description: "Den Meldemodus einmalig wählen, solange noch keiner gewählt ist; ist bereits ein Modus gewählt, antwortet der Vorgang mit `409`. Ein späterer Wechsel des Meldemodus läuft über den Support. Die Wahl gilt für den Teilnehmer, für alle seine Verbindungen und für Green SPOT. Wer `self_reporting` wählt, meldet seine Seite selbst und trägt die Folgen einer unterlassenen Meldung allein; OES meldet dann nur die Seite der Gegenpartei. Bei 1-Click PPA vereinbaren die Parteien das Selbstmelden in der Anpassungsvereinbarung, die Wahl des Meldemodus ist ihre technische Umsetzung. Änderungen an der Marktteilnehmerkennung laufen über den Support, weil sie in laufende Meldeketten eingreifen.\n\nErforderlicher Scope: `rfq:write`"
      tags:
        - REMIT
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - rfq:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RemitSettingUpdate"
      responses:
        "200":
          description: Die gewählte REMIT-Meldeeinstellung
          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/RemitSetting"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
