openapi: 3.0.0
info:
  title: Otark GCR Connect API
  description: "Programmatischer Zugang zum GCR Portal, der Kontosicht auf das Granular Certificate Register (GCR), das die Zertifikatstelle von OES betreibt: die Teilnehmer des GCR-Kontos auflisten, den Bestand an HC einsehen, Entwertungen beantragen und die drei Nachweisreports abrufen."
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.energy
    description: Produktion
tags:
  - name: Customers
    description: "Die Teilnehmer, deren GC das angemeldete GCR-Konto führt, als Einstieg jeder Anbindung"
  - name: Certificates
    description: Der Bestand an HC je Liefertag und Stunde, mit den Registerangaben je HC
  - name: Cancellations
    description: Die Entwertung von GC beantragen — der Antrag, nicht der Vollzug; zuerst wird der HKN entwertet
  - name: Reports
    description: Die drei Nachweisreports — Stunden-Zeitreihe, HKN-Monatsmengen, Entwertungsnachweis
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    CustomerIdParam:
      name: customer_id
      in: query
      required: true
      description: "Der Teilnehmer, dessen Sicht abgefragt wird. Die Sichten sind streng je Teilnehmer getrennt; es gibt keine Sicht, die den Bestand zweier Teilnehmer zusammenfasst."
      schema:
        type: string
        example: cust_b7e4a2c9
    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: gc_a1b2c3d4
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    DeliveryDateParam:
      name: delivery_date
      in: query
      description: Nach Liefertag filtern (lokaler Kalendertag, Europe/Berlin)
      schema:
        type: string
        format: date
        example: "2026-03-18"
    DeliveryDateFromParam:
      name: delivery_date_from
      in: query
      description: "Filter: Liefertag >= diesem Wert"
      schema:
        type: string
        format: date
        example: "2026-03-01"
    DeliveryDateToParam:
      name: delivery_date_to
      in: query
      description: "Filter: Liefertag <= diesem Wert"
      schema:
        type: string
        format: date
        example: "2026-03-31"
    HourParam:
      name: hour
      in: query
      description: Nach Lieferstunde 1–24 filtern (EPEX-Konvention — Stunde 14 umfasst 13:00–14:00 Uhr Ortszeit, Europe/Berlin)
      schema:
        type: integer
        minimum: 1
        maximum: 24
        example: 14
    MastrNumberParam:
      name: mastr_number
      in: query
      description: Nach der MaStR-Nummer der Erzeugungsanlage filtern
      schema:
        type: string
        example: SEE941280003651
    ProductionMonthParam:
      name: production_month
      in: query
      description: Nach Erzeugungsmonat (Liefermonat) filtern, Format `YYYY-MM`
      schema:
        type: string
        example: "2026-03"
  headers:
    X-RateLimit-Limit:
      description: Höchstzahl der Anfragen je Zeitfenster
      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: gc_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://gcr.otark.energy/errors/certificate_not_found
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Certificate Not Found
        status:
          type: integer
          description: HTTP-Statuscode
          example: 404
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: The requested certificate does not exist or is not assigned to the given customer.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/certificates/gc_5d8f3a1c
        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: certificate_ids
        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: required
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: At least one certificate ID is required
      required:
        - code
        - message
    Customer:
      type: object
      description: "Ein Teilnehmer, dessen GC das angemeldete GCR-Konto führt: sein eigenes GCR-Konto, das OES ihm mit der Zulassung anlegt, oder das GCR-Konto eines Dienstleisters, mit dem er sein Konto verknüpft hat. Inhaber der GC bleibt immer der Teilnehmer."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Kunden
          example: cust_b7e4a2c9
        name:
          type: string
          description: Anzeigename des Teilnehmers
          example: Käufer A
        linked_at:
          type: string
          format: date-time
          description: "ISO-8601-Zeitstempel, ab dem das GCR-Konto die GC dieses Teilnehmers führt. Eine Verknüpfung mit dem GCR-Konto eines Dienstleisters braucht dessen Zustimmung und wirkt ab dem nächsten Monatsabschluss."
          example: "2026-01-12T08:00:00Z"
      required:
        - id
        - name
        - linked_at
    CustomerList:
      type: object
      properties:
        customers:
          type: array
          description: Liste der Teilnehmer
          items:
            $ref: "#/components/schemas/Customer"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - customers
        - pagination
    Asset:
      type: object
      description: Die Erzeugungsanlage hinter einem GC, bezeichnet durch ihre MaStR-Nummer
      properties:
        mastr_number:
          type: string
          description: MaStR-Nummer der Erzeugungsanlage
          example: SEE941280003651
        name:
          type: string
          description: Anzeigename der Erzeugungsanlage
          example: WEA Nord 1
      required:
        - mastr_number
        - name
    CertificateAttributes:
      type: object
      description: Die Merkmale des GC — seit der Ausstellung unveränderlich. Das Register führt den vollständigen Merkmalskatalog des EnergyTag-Standards; dieses Objekt nennt den Ausschnitt, den der Merkmalsnachweis der Reports und die Detailansicht des Portals verwenden.
      properties:
        technology_code:
          type: string
          description: Technologie-Code der EECS-Systematik — ein dreistufig hierarchischer Code aus der offenen Codeliste der Association of Issuing Bodies (AIB), keine abgeschlossene Liste dieser API
          example: T020001
        technology:
          type: string
          description: Lesbare Technologiebezeichnung für die Anzeige, abgeleitet aus dem Technologie-Code
          example: Wind onshore
        energy_carrier_code:
          type: string
          description: Energieträger-Code der EECS-Systematik, getrennt vom Technologie-Code geführt
          example: F01050100
        location:
          type: string
          description: Standort der Erzeugungsanlage — Straße, Postleitzahl, Ort und Land
          example: Windparkstraße 1, 25813 Husum, DE
        coordinates:
          type: string
          nullable: true
          description: GPS-Koordinaten der Erzeugungsanlage, soweit vorhanden; sonst null
          example: 54.4858, 9.0605
        installed_capacity_mw:
          type: number
          description: Installierte elektrische Leistung der Erzeugungsanlage zum Zeitpunkt der Ausstellung, in MW
          example: 18.0
        commissioning_date:
          type: string
          format: date
          description: Inbetriebnahmedatum der Erzeugungsanlage
          example: "2019-06-27"
        subsidy_status:
          type: string
          description: Vermarktungsform des Erzeugungsmonats — der Nachweis, dass keine Förderung in Anspruch genommen wurde. GC entstehen ausschließlich für Anlagen ohne EEG-Einspeisevergütung und ohne Marktprämie; der einzige vorkommende Wert ist deshalb `unsubsidised`
          enum:
            - unsubsidised
          example: unsubsidised
        emission_factor:
          type: number
          description: Emissionsfaktor, der im EECS-Energieträger-Code der AIB-Systematik hinterlegt ist, fixiert zum Zeitpunkt der Ausstellung
          example: 0
      required:
        - technology_code
        - technology
        - energy_carrier_code
        - location
        - installed_capacity_mw
        - commissioning_date
        - subsidy_status
        - emission_factor
    GoTransfer:
      type: object
      description: "Die Nettoposition, mit der der zugehörige HKN auf das benannte HKNR-Konto gegangen ist: in Green SPOT automatisch im Monatsabschluss am 10. des übernächsten Monats oder nach einem Aftermarket-Kauf mit dem festgestellten Geldeingang, bei 1-Click PPA durch automatische Weiterleitung nach dem Eingang oder, wenn der Käufer die Halteoption gewählt hat, auf seinen Abruf"
      properties:
        transferred_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der HKN-Übertragung auf das benannte Registerkonto
          example: "2026-05-11T08:00:00Z"
        quantity_mwh:
          type: number
          description: Übertragene HKN-Menge in MWh (ganze MWh — 1 HKN deckt 1 MWh)
          example: 90.000
      required:
        - transferred_at
        - quantity_mwh
    Certificate:
      type: object
      description: "Ein HC, das granulare Zertifikat einer Stunde, wie das GCR es führt, mit den Registerangaben vom Tupel bis zur Entwertung. Jedes HC ist mit einem HKN hinterlegt. Die Detailansicht nennt nie die Identitäten früherer Inhaber, keine Preise und keine Transaktionen."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des GC im GCR
          example: gc_5d8f3a1c
        customer_id:
          type: string
          description: "Der Teilnehmer, dem das HC gehört und in dessen Sicht es erscheint, nie der Inhaber eines verknüpften Dienstleisterkontos. In Green SPOT ist das bis zur Zuteilung der Verkäufer, mit dem Monatsabschluss oder mit der Übertragung nach einem Aftermarket-Kauf der Käufer."
          example: cust_b7e4a2c9
        delivery_date:
          type: string
          format: date
          description: Liefertag (lokaler Kalendertag, Europe/Berlin)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Lieferstunde 1–24 (EPEX-Konvention) — Stunde 14 umfasst 13:00–14:00 Uhr Ortszeit (Europe/Berlin)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: Nur am langen Tag der Zeitumstellung gesetzt, an dem die doppelte Stunde 3 als 3A/3B geführt wird; an allen anderen Tagen null
          enum:
            - A
            - B
          example: null
        interval_start:
          type: string
          format: date-time
          description: ISO-8601-Beginn der Lieferstunde (UTC)
          example: "2026-03-18T12:00:00Z"
        interval_end:
          type: string
          format: date-time
          description: ISO-8601-Ende der Lieferstunde (UTC)
          example: "2026-03-18T13:00:00Z"
        asset:
          $ref: "#/components/schemas/Asset"
        quantity_mwh:
          type: number
          description: Menge des GC in MWh (3 Nachkommastellen — kWh-genau; der kleinste Nennwert ist 1 kWh)
          example: 16.000
        attributes:
          $ref: "#/components/schemas/CertificateAttributes"
        status:
          type: string
          description: "Status des HC: der laufende Zustand `issued` (ausgestellt) und zwei Endzustände, `cancelled` (entwertet) und `expired` (verfallen, 18 Kalendermonate nach Ende des Erzeugungsmonats ohne Entwertung). Ein ausgestelltes HC wird nie storniert."
          enum:
            - issued
            - cancelled
            - expired
          example: issued
        go_location:
          type: string
          description: "Wo der zugehörige HKN liegt: `oes_trading_account` auf dem OES-Händlerkonto im HKNR (in Green SPOT bis zur Übertragung im Monatsabschluss oder nach einem Aftermarket-Kauf, bei 1-Click PPA mit Halteoption auch für den Käufer), `buyer_account` auf dem benannten HKNR-Konto des Käufers, `cancelled` entwertet und endgültig. Auf dem Granular Aftermarket anbieten lässt sich nur ein HC, dessen HKN bei OES liegt und das nicht zugeteilt oder auf dem Aftermarket erworben ist."
          enum:
            - oes_trading_account
            - buyer_account
            - cancelled
          example: buyer_account
        coverage_source:
          type: string
          nullable: true
          description: "Nur Green SPOT: die Deckungsquelle, aus der das zugeteilte HC den Anspruch des Käufers erfüllt, `physical_delivery` aus dem Bündel aus Strom und QHC (Day-ahead oder Intraday) oder `granular_matching` aus dem Granular Matching. Vor der Zuteilung und außerhalb von Green SPOT null."
          enum:
            - physical_delivery
            - granular_matching
          example: physical_delivery
        go_transfer:
          nullable: true
          description: "Die Nettoposition, mit der der zugehörige HKN auf das benannte HKNR-Konto gegangen ist; null, solange der HKN bei OES liegt"
          example:
            transferred_at: "2026-05-11T08:00:00Z"
            quantity_mwh: 90.000
          allOf:
            - $ref: "#/components/schemas/GoTransfer"
        go_cancelled_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel, zu dem OES die Entwertung des zugehörigen HKN im HKNR festgestellt hat; bis dahin null
          example: null
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel, zu dem das GC im GCR entwertet wurde — stets nach der HKN-Entwertung; bis dahin null
          example: null
        issued_at:
          type: string
          format: date-time
          description: "ISO-8601-Zeitstempel der Ausstellung; in Green SPOT frühestens am 21. des Folgemonats, wenn die HKN eingegangen und die Messwerte eingefroren sind"
          example: "2026-04-21T05:45:00Z"
      required:
        - id
        - customer_id
        - delivery_date
        - hour
        - interval_start
        - interval_end
        - asset
        - quantity_mwh
        - attributes
        - status
        - go_location
        - issued_at
    CertificateList:
      type: object
      properties:
        certificates:
          type: array
          description: Liste der GC, je Liefertag und Stunde (die Viertelstundenebene bleibt registerintern)
          items:
            $ref: "#/components/schemas/Certificate"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - certificates
        - pagination
    EvidenceDocument:
      type: object
      description: "Die Entwertungsbestätigung des HKNR (Kontoauszug oder Entwertungsbeleg) mit Anlage, Liefermonat und Menge. Pflicht, wenn OES keinen Zugriff auf das benannte HKNR-Konto hat."
      properties:
        file_name:
          type: string
          description: Dateiname des Belegdokuments
          example: hknr-entwertungsbeleg-2026-03.pdf
        media_type:
          type: string
          description: Medientyp des Belegdokuments — die Bestätigung des HKNR wird in dem Format angenommen, in dem das Register sie ausstellt; ein festes Dateiformat ist nicht vorgeschrieben
          example: application/pdf
        content:
          type: string
          format: byte
          description: Dokumentinhalt, Base64-kodiert
          example: JVBERi0xLjcKJ...
      required:
        - file_name
        - media_type
        - content
    CancellationRequestCreate:
      type: object
      description: "Der Antrag, die ausgewählten GC zu entwerten. Die Reihenfolge steht fest: zuerst entwertet der Kontoinhaber den HKN im HKNR, dann entwertet die Zertifikatstelle das GC im GCR. Ohne Zugriff von OES auf das HKNR-Konto ist `evidence` Pflicht."
      properties:
        customer_id:
          type: string
          description: Der Teilnehmer, dessen GC entwertet werden sollen
          example: cust_b7e4a2c9
        certificate_ids:
          type: array
          description: Kennungen der zu entwertenden GC
          items:
            type: string
          minItems: 1
          example:
            - gc_5d8f3a1c
            - gc_8a2c7e4b
        evidence:
          nullable: true
          description: "Der Entwertungsbeleg des HKNR. Bleibt weg, wenn OES Zugriff auf das benannte HKNR-Konto hat (Dienstleisterrolle oder eigener Benutzer mit Lesezugriff); OES stellt die HKN-Entwertung dann im Registerabgleich selbst fest. Andernfalls Pflicht."
          allOf:
            - $ref: "#/components/schemas/EvidenceDocument"
      required:
        - customer_id
        - certificate_ids
    CancellationRequest:
      type: object
      description: Ein Entwertungsantrag — der Antrag, nicht der Vollzug. OES entwertet kein GC, bevor die Entwertung der zugehörigen HKN im HKNR festgestellt ist.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Entwertungsantrags
          example: creq_2e9b4f7a
        customer_id:
          type: string
          description: Der Teilnehmer, zu dem der Antrag gehört
          example: cust_b7e4a2c9
        certificate_ids:
          type: array
          description: Kennungen der GC, die der Antrag umfasst
          items:
            type: string
          example:
            - gc_5d8f3a1c
            - gc_8a2c7e4b
        status:
          type: string
          description: "Status des Antrags: `submitted` (Antrag eingegangen), `under_review` (manuelle Prüfung des hochgeladenen Belegs gegen Anlage, Liefermonat und Menge), `completed` (GC im GCR entwertet), `rejected` (der Beleg weist Anlage, Liefermonat und Menge nicht aus)"
          enum:
            - submitted
            - under_review
            - completed
            - rejected
          example: completed
        evidence_route:
          type: string
          description: "Wie OES die HKN-Entwertung feststellt: `service_provider_role` über den Zugriff auf das HKNR-Konto, als Dienstleisterrolle oder eigener Benutzer mit Lesezugriff (automatisch, ohne Upload und ohne Entgelt), oder `document_upload` über den hochgeladenen Beleg (manuelle Prüfung; es kann ein Entgelt nach dem Preis- und Leistungsverzeichnis anfallen)"
          enum:
            - service_provider_role
            - document_upload
          example: service_provider_role
        rejected_reason:
          type: string
          nullable: true
          description: Grund der Ablehnung; null, solange der Status nicht `rejected` ist
          example: null
        requested_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Antragstellung
          example: "2026-06-02T09:15:00Z"
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel, zu dem die GC im GCR entwertet wurden; bis dahin null
          example: "2026-06-03T11:20:00Z"
      required:
        - id
        - customer_id
        - certificate_ids
        - status
        - evidence_route
        - rejected_reason
        - requested_at
        - completed_at
    GenerationShare:
      type: object
      description: Ein Erzeugungsanteil einer Stundenzeile, mit seinem Merkmalsnachweis
      properties:
        asset:
          $ref: "#/components/schemas/Asset"
        quantity_mwh:
          type: number
          description: Menge dieses Anteils in MWh (3 Nachkommastellen)
          example: 16.000
        coverage_source:
          type: string
          nullable: true
          description: "Nur Green SPOT: Deckungsquelle dieses Anteils, `physical_delivery` aus dem Bündel aus Strom und QHC (Day-ahead oder Intraday) oder `granular_matching` aus dem Granular Matching. Außerhalb von Green SPOT null."
          enum:
            - physical_delivery
            - granular_matching
          example: physical_delivery
        attributes:
          $ref: "#/components/schemas/CertificateAttributes"
      required:
        - asset
        - quantity_mwh
        - attributes
    HourlyTimeSeriesRow:
      type: object
      description: Eine Zeile der Stunden-Zeitreihe, die HC des Teilnehmers für einen Liefertag und eine Stunde
      properties:
        delivery_date:
          type: string
          format: date
          description: Liefertag (lokaler Kalendertag, Europe/Berlin)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Lieferstunde 1–24 (EPEX-Konvention)
          example: 14
        quantity_mwh:
          type: number
          description: HC-Menge des Teilnehmers in dieser Stunde in MWh (3 Nachkommastellen)
          example: 16.000
        designation:
          type: string
          description: "Ausweisung der Stunde, in jedem Format dieselbe: `covered_go_backed` heißt gedeckt, der Regelfall nach der Zuteilung, HC und HKN beim Käufer; `allocated_go_outstanding` heißt Anspruch, Zuteilung ausstehend, der Zustand in Green SPOT zwischen Geschäft und Monatsabschluss; `not_green_covered` heißt nicht grün gedeckt, der Käufer hält kein HC für die Menge, die Ursache steht in `designation_reason`; `uncovered` heißt ungedeckt, Verbrauch ohne HC"
          enum:
            - covered_go_backed
            - allocated_go_outstanding
            - not_green_covered
            - uncovered
          example: covered_go_backed
        designation_reason:
          type: string
          nullable: true
          description: "Ursache bei `not_green_covered`: eine Kürzung aus dem Stundenpool wegen einer Fehlmenge oder einer HKN-Fehlmenge eines Verkäufers, für die der Käufer eine Entschädigung erhält, oder ein weiterverkaufter Anspruch; im Regelfall null"
          example: null
        shares:
          type: array
          description: Die Erzeugungsanteile dieser Stunde, jeder mit seinem Merkmalsnachweis
          items:
            $ref: "#/components/schemas/GenerationShare"
      required:
        - delivery_date
        - hour
        - quantity_mwh
        - designation
        - designation_reason
        - shares
    HourlyTimeSeriesReport:
      type: object
      description: "Die Stunden-Zeitreihe: die HC des Teilnehmers je Liefertag und Stunde, mit dem Merkmalsnachweis je Erzeugungsanteil. Die Reports gehen immer an den Teilnehmer, nie an den Inhaber des benannten Kontos."
      properties:
        customer_id:
          type: string
          description: Der Teilnehmer, für den der Report ausgestellt ist
          example: cust_b7e4a2c9
        rows:
          type: array
          description: Die Stundenzeilen, nach Liefertag und Stunde sortiert
          items:
            $ref: "#/components/schemas/HourlyTimeSeriesRow"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - customer_id
        - rows
        - pagination
    GoMonthlyRow:
      type: object
      description: "Eine Zeile der HKN-Monatsmengen: eine Anlage und ein Erzeugungsmonat, oder ein im Dezember-Clearing als Backup gelieferter HKN"
      properties:
        position_type:
          type: string
          description: "Art der Position: `asset_position` ist die reguläre Zeile mit den Mengen des Teilnehmers aus einer Anlage und einem Erzeugungsmonat; `fractional_balancing` ist ein HKN, den OES im Dezember-Clearing statt des Barausgleichs für den Restsaldo des Käufers geliefert hat, aus den gebundenen HKN ohne Käuferzuordnung desselben Erzeugungsmonats einer anderen Anlage. In dieser Zeile nennt `asset` die Herkunftsanlage, `go_quantity_mwh` die Menge in ganzen MWh, und `gc_quantity_mwh` ist `0`."
          enum:
            - asset_position
            - fractional_balancing
          example: asset_position
        production_month:
          type: string
          description: Erzeugungsmonat (Liefermonat), Format `YYYY-MM`
          example: "2026-03"
        asset:
          description: "Die Erzeugungsanlage dieser Position, in einer Zeile `fractional_balancing` die Herkunftsanlage des HKN"
          allOf:
            - $ref: "#/components/schemas/Asset"
        gc_quantity_mwh:
          type: number
          description: "Menge der zugeteilten GC des Teilnehmers aus dieser Anlage und diesem Monat in MWh (3 Nachkommastellen)"
          example: 90.400
        go_quantity_mwh:
          type: number
          description: "Aus dieser Anlage und diesem Monat auf das benannte HKNR-Konto des Teilnehmers übertragene HKN in MWh (ganze MWh, 1 HKN deckt 1 MWh): der Stand der Übertragung"
          example: 90.000
      required:
        - position_type
        - production_month
        - asset
        - gc_quantity_mwh
        - go_quantity_mwh
    GoMonthlyQuantitiesReport:
      type: object
      description: "Die HKN-Monatsmengen: je Anlage und Liefermonat die GC-Menge des Teilnehmers und die auf sein benanntes HKNR-Konto übertragenen HKN. Den HKN-Übertrag rechnet OES je Käufer über alle Anlagen abgerundet und entnimmt die ganzen HKN den Anlagen in der Reihenfolge der größten Bruchteile des Käufers; HKN- und GC-Menge einer Zeile können deshalb auf Bruchteilsebene voneinander abweichen. Ein als Backup gelieferter HKN erscheint als eigene Zeile mit Menge und Herkunftsanlage. Die Reports gehen immer an den Teilnehmer, nie an den Inhaber des benannten Kontos."
      properties:
        customer_id:
          type: string
          description: Der Teilnehmer, für den der Report ausgestellt ist
          example: cust_b7e4a2c9
        rows:
          type: array
          description: Die Monatszeilen, nach Erzeugungsmonat und Anlage sortiert
          items:
            $ref: "#/components/schemas/GoMonthlyRow"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - customer_id
        - rows
        - pagination
    CancellationProofEntry:
      type: object
      description: "Ein Eintrag des Entwertungsnachweises: die Bestätigung von OES, dass GC und HKN entwertet sind"
      properties:
        cancellation_request_id:
          type: string
          description: Der Entwertungsantrag, aus dem dieser Eintrag stammt
          example: creq_2e9b4f7a
        production_month:
          type: string
          description: Erzeugungsmonat (Liefermonat), Format `YYYY-MM`
          example: "2026-03"
        asset:
          $ref: "#/components/schemas/Asset"
        quantity_mwh:
          type: number
          description: Entwertete Zertifikatsmenge in MWh (3 Nachkommastellen)
          example: 90.000
        go_cancelled_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel, zu dem OES die Entwertung der zugehörigen HKN im HKNR festgestellt hat
          example: "2026-06-03T10:12:00Z"
        gc_cancelled_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel, zu dem die GC im GCR entwertet wurden — stets nach der HKN-Entwertung
          example: "2026-06-03T11:20:00Z"
      required:
        - cancellation_request_id
        - production_month
        - asset
        - quantity_mwh
        - go_cancelled_at
        - gc_cancelled_at
    CancellationProofReport:
      type: object
      description: Der Entwertungsnachweis — erst nach der Entwertung verfügbar. Die Reports gehen immer an den Teilnehmer, nie an den Inhaber des benannten Kontos.
      properties:
        customer_id:
          type: string
          description: Der Teilnehmer, für den der Nachweis ausgestellt ist
          example: cust_b7e4a2c9
        entries:
          type: array
          description: Die Entwertungseinträge; leer, solange nichts entwertet ist
          items:
            $ref: "#/components/schemas/CancellationProofEntry"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - customer_id
        - entries
        - pagination
  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://gcr.otark.energy/errors/certificate_not_found
            title: GC nicht gefunden
            status: 404
            instance: /v1/certificates/gc_5d8f3a1c
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://gcr.otark.energy/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/cancellation-requests
            errors:
              - field: evidence
                code: required
                message: Evidence is required because OES has no access to the named register account
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://gcr.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://gcr.otark.energy/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: cancellations: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://gcr.otark.energy/errors/certificate_already_cancelled
            title: GC bereits entwertet
            status: 409
            detail: Cancellation is final — a cancelled certificate cannot be cancelled again.
    RateLimited:
      description: Ratenbegrenzung überschritten
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://gcr.otark.energy/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/customers:
    get:
      operationId: listCustomers
      summary: Kunden auflisten
      description: "Die Teilnehmer auflisten, deren GC das angemeldete GCR-Konto führt: beim eigenen GCR-Konto eines Teilnehmers ihn selbst, beim GCR-Konto eines Dienstleisters jeden Teilnehmer, der sein Konto damit verknüpft hat. Hier beginnt jede Anbindung: Alle weiteren Aufrufe tragen eine `customer_id`, und die Sichten sind streng je Teilnehmer getrennt; es gibt keine Sicht, die den Bestand zweier Teilnehmer zusammenfasst. Inhaber der GC bleibt immer der Teilnehmer.\n\nErforderlicher Scope: `certificates:read`"
      tags:
        - Customers
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - certificates:read
      parameters:
        - $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"
              example:
                customers:
                  - id: cust_b7e4a2c9
                    name: Käufer A
                    linked_at: "2026-01-12T08:00:00Z"
                pagination:
                  limit: 10
                  has_more: false
                  next_cursor: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/certificates:
    get:
      operationId: listCertificates
      summary: GC auflisten
      description: "Die HC des angegebenen Teilnehmers auflisten, je Liefertag und Stunde. Ein HC ist die Zusammenfassung der vier QHC derselben Stunde; darunter führt das GCR viertelstündlich, weist die Viertelstunde aber nicht aus. Filterbar nach Liefertag, Stunde, Erzeugungsanlage, Status und Ort des HKN.\n\nErforderlicher Scope: `certificates:read`"
      tags:
        - Certificates
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - certificates:read
      parameters:
        - $ref: "#/components/parameters/CustomerIdParam"
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/DeliveryDateFromParam"
        - $ref: "#/components/parameters/DeliveryDateToParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/MastrNumberParam"
        - name: status
          in: query
          description: Nach dem Status des GC filtern
          schema:
            type: string
            enum:
              - issued
              - cancelled
              - expired
        - name: go_location
          in: query
          description: Nach dem Ort des zugehörigen HKN filtern
          schema:
            type: string
            enum:
              - oes_trading_account
              - buyer_account
              - cancelled
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der GC
          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/CertificateList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/certificates/{certificate_id}:
    get:
      operationId: getCertificate
      summary: GC abrufen
      description: "Ein einzelnes HC samt der Registerangaben abrufen, die das GCR dazu führt: Tupel, Anlage, Menge, Merkmale, Status, Ort des HKN, Deckungsquelle, HKN-Übertragung und Entwertung. Die Detailansicht nennt nie die Identitäten früherer Inhaber — der Handel ist anonym, und das Register hebt das nicht auf; die vollständige Kette kennt allein OES. Preise und Transaktionen enthält sie ebenfalls nicht.\n\nErforderlicher Scope: `certificates:read`"
      tags:
        - Certificates
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - certificates:read
      parameters:
        - name: certificate_id
          in: path
          required: true
          description: Kennung des GC
          schema:
            type: string
            example: gc_5d8f3a1c
      responses:
        "200":
          description: Angaben zum GC
          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/Certificate"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/cancellation-requests:
    post:
      operationId: createCancellationRequest
      summary: Entwertungsantrag anlegen
      description: "Den Antrag stellen, die ausgewählten GC zu entwerten — den Antrag, nicht den Vollzug. Die Reihenfolge steht fest und wird durch die API nicht verändert: zuerst der HKN im HKNR, dann das GC im GCR; OES entwertet kein GC, bevor die Entwertung der zugehörigen HKN festgestellt ist.\n\nWie es weitergeht, hängt davon ab, ob OES Zugriff auf das benannte HKNR-Konto hat, über die Dienstleisterrolle oder einen eigenen Benutzer mit Lesezugriff. Mit Zugriff bleibt `evidence` weg: OES stellt die HKN-Entwertung im Registerabgleich selbst fest, automatisch und ohne Entgelt. Ohne Zugriff ist `evidence` Pflicht, die Entwertungsbestätigung des HKNR (Kontoauszug oder Entwertungsbeleg) mit Anlage, Liefermonat und Menge; OES prüft sie manuell, und es kann ein Entgelt nach dem Preis- und Leistungsverzeichnis anfallen. Einen Beleg, der sich nicht zuordnen lässt, lehnt OES mit Begründung ab; die GC bleiben ausgestellt.\n\nEine Pflicht zur Entwertung besteht nicht, und deshalb auch keine Frist. Den Fortgang verfolgen Sie über `GET /v1/cancellation-requests/{request_id}`; der Entwertungsnachweis steht erst nach dem Abschluss bereit.\n\nErforderlicher Scope: `cancellations:write`"
      tags:
        - Cancellations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - cancellations:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancellationRequestCreate"
      responses:
        "201":
          description: Entwertungsantrag angelegt
          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/CancellationRequest"
              example:
                id: creq_2e9b4f7a
                customer_id: cust_b7e4a2c9
                certificate_ids:
                  - gc_5d8f3a1c
                  - gc_8a2c7e4b
                status: submitted
                evidence_route: service_provider_role
                rejected_reason: null
                requested_at: "2026-06-02T09:15:00Z"
                completed_at: null
        "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"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/cancellation-requests/{request_id}:
    get:
      operationId: getCancellationRequest
      summary: Entwertungsantrag abrufen
      description: "Einen Entwertungsantrag abrufen, um seinen Status zu verfolgen. Mit Zugriff von OES auf das HKNR-Konto geht der Antrag von `submitted` auf `completed` über, sobald OES die HKN-Entwertung im Registerabgleich feststellt. Mit hochgeladenem Beleg durchläuft er `under_review` und endet auf `completed` oder `rejected` — abgelehnt, wenn der Beleg Anlage, Liefermonat und Menge nicht ausweist.\n\nNach dem Abschluss tragen die GC im GCR den Status `cancelled`, einen der beiden Endzustände. Erst mit beiden Entwertungen ist der Nachweis vollständig, und erst dann steht der Entwertungsnachweis bereit.\n\nErforderlicher Scope: `cancellations:write`"
      tags:
        - Cancellations
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - cancellations:write
      parameters:
        - name: request_id
          in: path
          required: true
          description: Kennung des Entwertungsantrags
          schema:
            type: string
            example: creq_2e9b4f7a
      responses:
        "200":
          description: Angaben zum Entwertungsantrag
          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/CancellationRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/reports/hourly-time-series:
    get:
      operationId: getHourlyTimeSeries
      summary: Stunden-Zeitreihe abrufen
      description: "Die Stunden-Zeitreihe abrufen: die HC des Teilnehmers je Liefertag und Stunde, mit dem Merkmalsnachweis je Erzeugungsanteil, final mit dem Monatsabschluss. Die Stundenwerte sind laufend verfügbar, sobald sie entstehen. Nach außen gibt es nur die Stunde; darunter führt das GCR viertelstündlich, weist die Viertelstunde aber nicht aus. Jede Stunde trägt ihre Ausweisung, in jedem Format dieselbe, vom Regelfall gedeckt bis zu nicht grün gedeckt samt Ursache; in Green SPOT steht die Deckungsquelle je Anteil dabei.\n\nDer Report geht immer an den Teilnehmer, nie an den Inhaber des benannten Kontos. Dieser Endpunkt ist die API-Fassung des Reports; denselben Inhalt gibt es im GCR Portal als CSV und PDF.\n\nErforderlicher Scope: `reports:read`"
      tags:
        - Reports
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - reports:read
      parameters:
        - $ref: "#/components/parameters/CustomerIdParam"
        - $ref: "#/components/parameters/DeliveryDateFromParam"
        - $ref: "#/components/parameters/DeliveryDateToParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Stunden-Zeitreihe
          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/HourlyTimeSeriesReport"
              example:
                customer_id: cust_b7e4a2c9
                rows:
                  - delivery_date: "2026-03-18"
                    hour: 14
                    quantity_mwh: 29.500
                    designation: covered_go_backed
                    designation_reason: null
                    shares:
                      - asset:
                          mastr_number: SEE941280003651
                          name: WEA Nord 1
                        quantity_mwh: 16.000
                        coverage_source: physical_delivery
                        attributes:
                          technology_code: T020001
                          technology: Wind onshore
                          energy_carrier_code: F01050100
                          location: Windparkstraße 1, 25813 Husum, DE
                          coordinates: 54.4858, 9.0605
                          installed_capacity_mw: 18.0
                          commissioning_date: "2019-06-27"
                          subsidy_status: unsubsidised
                          emission_factor: 0
                      - asset:
                          mastr_number: SEE905467231018
                          name: PV Süd 2
                        quantity_mwh: 13.500
                        coverage_source: physical_delivery
                        attributes:
                          technology_code: T010100
                          technology: Solar photovoltaic
                          energy_carrier_code: F01010100
                          location: Industriestraße 5, 84028 Landshut, DE
                          coordinates: 48.5371, 12.1520
                          installed_capacity_mw: 25.0
                          commissioning_date: "2021-04-30"
                          subsidy_status: unsubsidised
                          emission_factor: 0
                pagination:
                  limit: 10
                  has_more: true
                  next_cursor: "gc_k8m2p4q7"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/reports/go-monthly-quantities:
    get:
      operationId: getGoMonthlyQuantities
      summary: HKN-Monatsmengen abrufen
      description: "Die HKN-Monatsmengen abrufen: je Anlage und Liefermonat die GC-Menge des Teilnehmers und die auf sein benanntes HKNR-Konto übertragenen HKN, mit dem Stand der Übertragung. Den Restsaldo, der im Kalenderjahr in den Folgemonat rollt, liefert die Reporting API. Hat OES im Dezember-Clearing statt des Barausgleichs einen HKN aus einer anderen Anlage geliefert, erscheint er als eigene Zeile (`fractional_balancing`) mit Menge, Erzeugungsmonat und Herkunftsanlage.\n\nDer Report geht immer an den Teilnehmer, nie an den Inhaber des benannten Kontos. Dieser Endpunkt ist die API-Fassung des Reports; denselben Inhalt gibt es im GCR Portal als CSV und PDF.\n\nErforderlicher Scope: `reports:read`"
      tags:
        - Reports
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - reports:read
      parameters:
        - $ref: "#/components/parameters/CustomerIdParam"
        - $ref: "#/components/parameters/ProductionMonthParam"
        - $ref: "#/components/parameters/MastrNumberParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: HKN-Monatsmengen
          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/GoMonthlyQuantitiesReport"
              example:
                customer_id: cust_b7e4a2c9
                rows:
                  - position_type: asset_position
                    production_month: "2026-03"
                    asset:
                      mastr_number: SEE941280003651
                      name: WEA Nord 1
                    gc_quantity_mwh: 90.400
                    go_quantity_mwh: 90.000
                  - position_type: asset_position
                    production_month: "2026-03"
                    asset:
                      mastr_number: SEE905467231018
                      name: PV Süd 2
                    gc_quantity_mwh: 30.000
                    go_quantity_mwh: 30.000
                pagination:
                  limit: 10
                  has_more: false
                  next_cursor: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /v1/reports/cancellation-proof:
    get:
      operationId: getCancellationProof
      summary: Entwertungsnachweis abrufen
      description: "Den Entwertungsnachweis abrufen, die Bestätigung von OES, dass GC und HKN entwertet sind. Es gibt ihn erst nach beiden Entwertungen: Einträge entstehen, sobald ein Entwertungsantrag abgeschlossen ist; solange nichts entwertet ist, bleibt die Liste leer.\n\nDer Nachweis geht immer an den Teilnehmer, nie an den Inhaber des benannten Kontos. Dieser Endpunkt ist die API-Fassung des Reports; denselben Inhalt gibt es im GCR Portal als CSV und PDF. Über die drei Reports hinaus liefert das Register nichts — insbesondere keine Bestandsbestätigung zu einem frei gewählten Stichtag.\n\nErforderlicher Scope: `reports:read`"
      tags:
        - Reports
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - reports:read
      parameters:
        - $ref: "#/components/parameters/CustomerIdParam"
        - $ref: "#/components/parameters/ProductionMonthParam"
        - name: cancellation_request_id
          in: query
          description: Nach dem Entwertungsantrag filtern, aus dem die Einträge stammen
          schema:
            type: string
            example: creq_2e9b4f7a
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Entwertungsnachweis
          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/CancellationProofReport"
              example:
                customer_id: cust_b7e4a2c9
                entries:
                  - cancellation_request_id: creq_2e9b4f7a
                    production_month: "2026-03"
                    asset:
                      mastr_number: SEE941280003651
                      name: WEA Nord 1
                    quantity_mwh: 90.000
                    go_cancelled_at: "2026-06-03T10:12:00Z"
                    gc_cancelled_at: "2026-06-03T11:20:00Z"
                pagination:
                  limit: 10
                  has_more: false
                  next_cursor: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
