openapi: 3.0.0
info:
  title: Otark Reporting API
  description: "API zum automatisierten Abruf von Nachweisen und Reports: Portfolios, stundenscharfer Verbrauchsabgleich, Green-SPOT-Nachweispaket, Jahresnachweis und Restsaldo. Jeder Report geht an den angemeldeten Teilnehmer, nie an den Inhaber eines benannten Bilanzkreises oder Registerkontos. Nach außen gibt es nur die Stunde, die Viertelstundenebene bleibt intern."
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.energy
    description: Produktion
tags:
  - name: Portfolios
    description: Käufer-Portfolios — die plattformweite Einheit, an der der Verbrauchsabgleich gemessen wird
  - name: Coverage matching
    description: "Stundenscharfer Abgleich der HC und Ansprüche auf HC des Käufers gegen die Zielkurve des Portfolios"
  - name: Proofs
    description: Das Green-SPOT-Nachweispaket je Liefermonat und der Jahresnachweis
  - name: Fractional account
    description: "Der Restsaldo des Käufers zwischen GCR-Konto und HKNR-Konto im laufenden Kalenderjahr"
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: pf_a1b2c3d4
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    FormatParam:
      name: format
      in: query
      description: "Antwortformat: `json` (Voreinstellung) liefert den Report als strukturiertes JSON, `csv` denselben Inhalt als CSV (`text/csv`). Die drei Wege tragen denselben Inhalt — sie unterscheiden sich nur darin, wer sie liest."
      schema:
        type: string
        enum:
          - json
          - csv
        default: json
    MonthParam:
      name: month
      in: path
      required: true
      description: Liefermonat (`YYYY-MM`)
      schema:
        type: string
        pattern: '^\d{4}-(0[1-9]|1[0-2])$'
        example: "2026-03"
    PortfolioIdParam:
      name: portfolio_id
      in: path
      required: true
      description: Kennung des Portfolios
      schema:
        type: string
        example: pf_8k3d92hs
  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: pf_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.energy/errors/portfolio_not_found
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Portfolio Not Found
        status:
          type: integer
          description: HTTP-Statuscode
          example: 404
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: No portfolio with id pf_8k3d92hs exists for this participant.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/portfolios/pf_8k3d92hs
        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: month
        code:
          type: string
          description: "Maschinenlesbarer Fehlercode: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large` oder `validation_failed`"
          example: invalid_format
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: "Invalid month format. Expected YYYY-MM, received '2026-3'"
      required:
        - code
        - message
    Asset:
      type: object
      description: "Eine Erzeugungsanlage mit den Merkmalen, die der Nachweis je Erzeugungsanteil ausweist: Anlage, Technologie, Standort und Inbetriebnahmedatum."
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Anlage
          example: ast_7p2q9r4s
        mastr_number:
          type: string
          description: Nummer im Marktstammdatenregister — die deutsche Form der eindeutigen Anlagenkennung
          example: SEE941280003651
        name:
          type: string
          description: Anzeigename der Erzeugungsanlage
          example: WEA Nord 1
        technology:
          type: string
          description: Erzeugungstechnologie, als Kleinbuchstaben-Token in snake_case (etwa `solar`, `wind_onshore`, `wind_offshore`, `hydro`, `biomass`). Keine abgeschlossene Liste — dahinter steht der EECS-Technologie-Code, dreistufig hierarchisch nach der AIB-Systematik; der Nachweis führt dessen lesbare Bezeichnung mit.
          example: wind_onshore
        location:
          type: string
          description: Standort der Anlage (Straße, Postleitzahl, Ort, Land)
          example: Windparkstraße 1, 25813 Husum, DE
        commissioning_date:
          type: string
          format: date
          description: Datum der Inbetriebnahme der Anlage
          example: "2019-06-27"
      required:
        - id
        - mastr_number
        - name
        - technology
        - location
        - commissioning_date
    Portfolio:
      type: object
      description: Ein Käufer-Portfolio — die Einheit, an der der Verbrauchsabgleich gemessen wird. Der Käufer bildet seinen Bedarf in Portfolios ab und hinterlegt je Portfolio eine Zielkurve.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Portfolios
          example: pf_8k3d92hs
        name:
          type: string
          description: Anzeigename des Portfolios
          example: Werk Nord
        target_curve_source:
          type: string
          nullable: true
          description: "Woher die Zielkurve stammt: Messwerte vom MSB oder eine hochgeladene Kurve. Null, wenn das Portfolio keine Zielkurve hat; der Verbrauchsabgleich weist dann allein die Zertifikatskurve aus."
          enum:
            - metering_data
            - deposited_curve
          example: metering_data
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage (UTC)
          example: "2026-01-05T09:00:00Z"
      required:
        - id
        - name
        - target_curve_source
    PortfolioList:
      type: object
      properties:
        portfolios:
          type: array
          description: Liste der Portfolios des angemeldeten Teilnehmers
          items:
            $ref: "#/components/schemas/Portfolio"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - portfolios
        - pagination
    ConsumptionMatchingHour:
      type: object
      description: Eine Stunde des Verbrauchsabgleichs. Überdeckung wird nie in eine andere Stunde übertragen — eine Überschussstunde füllt keine Fehlstunde.
      properties:
        date:
          type: string
          format: date
          description: Liefertag (`YYYY-MM-DD`)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Tages, gezählt 1–24 wie bei EPEX — Stunde 14 ist 13:00–14:00 Uhr Ortszeit (Europe/Berlin)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: Nur bei der doppelten Stunde 3 am Tag der Umstellung auf Winterzeit gesetzt (`A` oder `B`) — die beiden sind physisch verschiedene Stunden und werden ausdrücklich als solche ausgewiesen. Bei allen anderen Stunden null.
          enum:
            - A
            - B
          example: null
        target_curve_mwh:
          type: number
          nullable: true
          description: Zielkurve der Stunde in MWh (bis zu 3 Nachkommastellen). Null, wenn das Portfolio keine Zielkurve hat.
          example: 30.000
        hc_held_mwh:
          type: number
          description: "HC und Ansprüche auf HC des Käufers für diese Stunde in MWh, aus Green SPOT (vor dem Monatsabschluss als Anspruch) und aus 1-Click PPA gleichermaßen; der Report unterscheidet nicht nach Herkunft"
          example: 30.500
        covered_mwh:
          type: number
          nullable: true
          description: "So viel der Zielkurve, wie HC und Ansprüche derselben Stunde tragen, in MWh. Null, wenn das Portfolio keine Zielkurve hat."
          example: 30.000
        under_coverage_mwh:
          type: number
          nullable: true
          description: "Der Teil der Zielkurve, dem in dieser Stunde weder HC noch Anspruch gegenübersteht, in MWh: die maßgebliche Zahl. Der Report weist sie aus, er bewertet sie nicht. Null, wenn das Portfolio keine Zielkurve hat."
          example: 0.000
        over_coverage_mwh:
          type: number
          nullable: true
          description: "Mehr HC und Ansprüche als Zielkurve in dieser Stunde, in MWh. Der Report weist sie aus und überträgt sie nie in eine andere Stunde. Null, wenn das Portfolio keine Zielkurve hat."
          example: 0.500
      required:
        - date
        - hour
        - target_curve_mwh
        - hc_held_mwh
        - covered_mwh
        - under_coverage_mwh
        - over_coverage_mwh
    ConsumptionMatchingTotals:
      type: object
      description: Die Monatssummen. Weil Überdeckung nie die Unterdeckung einer anderen Stunde füllt, ist `covered_mwh` die Summe der Stundenwerte — nicht die Differenz der Gesamtsummen.
      properties:
        target_curve_mwh:
          type: number
          nullable: true
          description: Summe der Zielkurve über den Monat in MWh
          example: 90.000
        hc_held_mwh:
          type: number
          description: Summe der HC und Ansprüche des Monats in MWh
          example: 90.000
        covered_mwh:
          type: number
          nullable: true
          description: Stundenweise aufsummierte Deckung in MWh
          example: 88.500
        under_coverage_mwh:
          type: number
          nullable: true
          description: Summe der Unterdeckung über den Monat in MWh — getrennt von der Überdeckung ausgewiesen
          example: 1.500
        over_coverage_mwh:
          type: number
          nullable: true
          description: Summe der Überdeckung über den Monat in MWh — getrennt von der Unterdeckung ausgewiesen
          example: 1.500
      required:
        - target_curve_mwh
        - hc_held_mwh
        - covered_mwh
        - under_coverage_mwh
        - over_coverage_mwh
    ConsumptionMatchingReport:
      type: object
      description: "Stundenscharfer Abgleich der HC und Ansprüche auf HC gegen die Zielkurve des Portfolios für einen Liefermonat. Produktneutral: GC aus Green SPOT und aus 1-Click PPA haben dieselben Merkmale."
      properties:
        portfolio_id:
          type: string
          description: Portfolio, zu dem der Report gehört
          example: pf_8k3d92hs
        month:
          type: string
          description: Liefermonat (`YYYY-MM`)
          example: "2026-03"
        hours:
          type: array
          description: Ein Eintrag je Stunde des Monats (744 in einem Monat mit 31 Tagen; Tage der Zeitumstellung tragen 23 oder 25 Einträge)
          items:
            $ref: "#/components/schemas/ConsumptionMatchingHour"
        totals:
          $ref: "#/components/schemas/ConsumptionMatchingTotals"
      required:
        - portfolio_id
        - month
        - hours
        - totals
    DisclosureCategory:
      type: string
      description: "Ausweisung einer Menge, in jedem Format gleich: `covered_go_backed` heißt gedeckt, der Regelfall nach der Zuteilung, HC und HKN beim Käufer (produktneutral); `allocated_go_pending` 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 Strom ist geflossen, zählt aber als grau, die Ursache steht in `cause` (nur Green SPOT); `uncovered` heißt ungedeckt, Verbrauch ohne HC, eine Lage und kein Verstoß. Was fehlt, weist der Nachweis aus und ersetzt es nicht; Geld heilt den Nachweis nicht."
      enum:
        - covered_go_backed
        - allocated_go_pending
        - not_green_covered
        - uncovered
      example: covered_go_backed
    ProofPosition:
      type: object
      description: Eine Menge einer Stunde samt ihrer Ausweisung. Eine Stunde kann mehrere Positionen tragen — etwa einen gedeckten Anteil und eine Lücke.
      properties:
        quantity_mwh:
          type: number
          description: Menge in MWh (bis zu 3 Nachkommastellen = kWh-genau; Nennwert eines GC ist 1 kWh)
          example: 4.000
        disclosure:
          $ref: "#/components/schemas/DisclosureCategory"
        coverage_source:
          type: string
          nullable: true
          description: "Deckungsquelle der Menge: `coupled` aus dem Bündel aus Strom und QHC (Day-ahead oder Intraday), `time_matched` aus dem Granular Matching, also ein HC derselben Stunde ohne gleichzeitige Stromlieferung. Wirtschaftlich sind beide gleichwertig, die Angabe ist keine Rangfolge. Bei Lückenpositionen null."
          enum:
            - coupled
            - time_matched
          example: coupled
        asset:
          nullable: true
          description: "Die deckende Anlage je Erzeugungsanteil, offengelegt mit der Zuteilung im Monatsabschluss. Bei Lückenpositionen und vor der Zuteilung null."
          allOf:
            - $ref: "#/components/schemas/Asset"
        cause:
          type: string
          nullable: true
          description: "Ursache einer Menge `not_green_covered`: `coverage_gap` heißt Kürzung aus dem Stundenpool wegen einer Fehlmenge F(h), die zum Ende des GM-Fensters offen war; `go_shortfall` heißt Kürzung wegen einer HKN-Fehlmenge, festgestellt zum Stichtag am 1. des übernächsten Monats. Für beide erhält der Käufer eine Entschädigung aus der Sanktion. Bei einem weiterverkauften Anspruch und bei allen anderen Ausweisungen null."
          enum:
            - coverage_gap
            - go_shortfall
          example: null
      required:
        - quantity_mwh
        - disclosure
        - coverage_source
        - asset
        - cause
    ProofHour:
      type: object
      description: Eine Stunde der GC-Zeitreihe samt ihren Positionen
      properties:
        date:
          type: string
          format: date
          description: Liefertag (`YYYY-MM-DD`)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Tages, gezählt 1–24 wie bei EPEX — Stunde 14 ist 13:00–14:00 Uhr Ortszeit (Europe/Berlin)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: Nur bei der doppelten Stunde 3 am Tag der Umstellung auf Winterzeit gesetzt (`A` oder `B`). Bei allen anderen Stunden null.
          enum:
            - A
            - B
          example: null
        positions:
          type: array
          description: Die Mengen der Stunde samt Ausweisung, deckender Anlage und Deckungsquelle
          items:
            $ref: "#/components/schemas/ProofPosition"
      required:
        - date
        - hour
        - positions
    Addendum:
      type: object
      description: "Ein datierter Nachtrag. Die Zuteilung ist mit dem Monatsabschluss final; ein Zukauf auf dem Aftermarket erscheint als datierter Nachtrag zu seiner Stunde, auch für eine Stunde, die als nicht grün ausgewiesen ist. Er ändert keine Sanktion."
      properties:
        recorded_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel (UTC), zu dem der Nachtrag erfasst wurde
          example: "2026-06-10T09:30:00Z"
        type:
          type: string
          description: "Art des Nachtrags: `aftermarket_purchase`, ein Zukauf auf dem Granular Aftermarket für die genannte Stunde"
          enum:
            - aftermarket_purchase
          example: aftermarket_purchase
        date:
          type: string
          format: date
          description: Liefertag, auf den sich der Nachtrag bezieht (`YYYY-MM-DD`)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde, auf die sich der Nachtrag bezieht (1–24)
          example: 14
        quantity_mwh:
          type: number
          description: Menge in MWh
          example: 1.000
        asset:
          nullable: true
          description: Die Anlage des zugekauften HC
          allOf:
            - $ref: "#/components/schemas/Asset"
      required:
        - recorded_at
        - type
        - date
        - hour
        - quantity_mwh
    RoundingOffset:
      type: object
      description: "Ein HKN, den OES im Dezember-Clearing als Backup statt des Barausgleichs für den Restsaldo des Käufers geliefert hat, mit Menge und Herkunftsanlage. OES liefert ihn nur aus gebundenen HKN ohne Käuferzuordnung desselben Erzeugungsmonats aus einer anderen Anlage und kauft keinen HKN zu; soweit er den Bruchteil des Käufers übersteigt, ist er ein HKN ohne GC."
      properties:
        quantity_mwh:
          type: number
          description: Menge in ganzen MWh (1 HKN deckt 1 MWh)
          example: 1.000
        source_asset:
          description: Die Anlage, aus der der HKN stammt
          allOf:
            - $ref: "#/components/schemas/Asset"
      required:
        - quantity_mwh
        - source_asset
    GreenSpotProofPackage:
      type: object
      description: "Das Green-SPOT-Nachweispaket eines Liefermonats: die stundenscharfe HC-Zeitreihe mit Ausweisung, Deckungsquelle und Anlagenzuordnung, dazu datierte Nachträge, als Backup gelieferte HKN und die entwertete HKN-Menge"
      properties:
        month:
          type: string
          description: Liefermonat (`YYYY-MM`)
          example: "2026-03"
        final:
          type: boolean
          description: "Ob der Nachweis des Liefermonats final ist. Er wird es mit dem Monatsabschluss am 10. des übernächsten Monats. Datierte Nachträge bleiben möglich."
          example: true
        cut_off_date:
          type: string
          format: date
          description: "Der Monatsabschluss des Liefermonats, mit dem der Nachweis final wird: der 10. des übernächsten Monats; rückt der Stichtag durch eine Störung hinter diesen Tag, der fünfte Kalendertag nach dem Stichtag"
          example: "2026-05-10"
        hours:
          type: array
          description: Ein Eintrag je Stunde des Monats (744 in einem Monat mit 31 Tagen; Tage der Zeitumstellung tragen 23 oder 25 Einträge)
          items:
            $ref: "#/components/schemas/ProofHour"
        addenda:
          type: array
          description: Datierte Nachträge des Monats, also Zukäufe auf dem Aftermarket
          items:
            $ref: "#/components/schemas/Addendum"
        rounding_offsets:
          type: array
          description: "Als Backup gelieferte HKN, die der Nachweis dieses Monats ausweist (im Nachweispaket des Liefermonats Dezember)"
          items:
            $ref: "#/components/schemas/RoundingOffset"
        go_cancelled_mwh:
          type: number
          nullable: true
          description: Entwertete HKN-Menge des Monats in MWh — endgültig mit der Entwertung im HKNR; den Zeitpunkt wählt der Käufer selbst. Bis zur Entwertung null.
          example: 120.000
      required:
        - month
        - final
        - cut_off_date
        - hours
        - addenda
        - rounding_offsets
        - go_cancelled_mwh
    ProofPackageSummary:
      type: object
      description: Ein Liefermonat samt seinem Stand der Finalität
      properties:
        month:
          type: string
          description: Liefermonat (`YYYY-MM`)
          example: "2026-03"
        final:
          type: boolean
          description: Ob der Nachweis des Monats final ist (Monatsabschluss erfolgt)
          example: true
        cut_off_date:
          type: string
          format: date
          description: "Der Monatsabschluss des Liefermonats, mit dem der Nachweis final wird (10. des übernächsten Monats)"
          example: "2026-05-10"
      required:
        - month
        - final
        - cut_off_date
    ProofPackageList:
      type: object
      properties:
        proof_packages:
          type: array
          description: Liefermonate, für die ein Nachweispaket vorliegt, der neueste zuerst
          items:
            $ref: "#/components/schemas/ProofPackageSummary"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - proof_packages
        - pagination
    DisclosureTotals:
      type: object
      description: Summen je Ausweisungskategorie in MWh
      properties:
        covered_go_backed_mwh:
          type: number
          description: Summe, die als gedeckt ausgewiesen ist
          example: 1385.000
        allocated_go_pending_mwh:
          type: number
          description: "Summe, die als Anspruch mit ausstehender Zuteilung ausgewiesen ist; im Jahresnachweis null, weil er erst nach dem Monatsabschluss des Dezembers erstellt wird"
          example: 0.000
        not_green_covered_mwh:
          type: number
          description: Summe, die als nicht grün gedeckt ausgewiesen ist
          example: 24.000
        uncovered_mwh:
          type: number
          description: Summe, die als ungedeckt ausgewiesen ist
          example: 5.000
      required:
        - covered_go_backed_mwh
        - allocated_go_pending_mwh
        - not_green_covered_mwh
        - uncovered_mwh
    AnnualProof:
      type: object
      description: "Der Jahresnachweis, einmal jährlich zum 31. März des Folgejahres erstellt, nach dem Monatsabschluss des Dezembers am 10. Februar und dem Dezember-Clearing; produktneutral über Green SPOT und 1-Click PPA hinweg, ausgestellt auf den Teilnehmer"
      properties:
        year:
          type: integer
          description: Kalenderjahr, das der Nachweis abdeckt
          example: 2026
        hours:
          type: array
          description: Die Jahres-Zeitreihe — 8.760 Stundenwerte (8.784 im Schaltjahr); Tage der Zeitumstellung tragen 23 oder 25 Einträge
          items:
            $ref: "#/components/schemas/ProofHour"
        totals:
          $ref: "#/components/schemas/DisclosureTotals"
        go_cancelled_mwh:
          type: number
          description: Entwertete HKN-Menge des Jahres in MWh
          example: 1385.000
        rounding_offsets:
          type: array
          description: Die im Dezember-Clearing des Jahres als Backup gelieferten HKN
          items:
            $ref: "#/components/schemas/RoundingOffset"
      required:
        - year
        - hours
        - totals
        - go_cancelled_mwh
        - rounding_offsets
    FractionalAccount:
      type: object
      description: "Der aktuelle Restsaldo des Käufers im Kalenderjahr: die kumulierte GC-Menge des Jahres abzüglich der im Jahr auf sein HKNR-Konto übertragenen HKN. Der Übertrag im Monatsabschluss ist je Käufer über alle Anlagen abgerundet; der Rest rollt innerhalb des Kalenderjahres in den Folgemonat, nicht über den Jahreswechsel. Im Dezember-Clearing erhält der Käufer für den offenen Restsaldo den Jahresreferenzpreis P_year in bar, oder OES liefert als Backup einen HKN desselben Erzeugungsmonats aus einer anderen Anlage. Der Nachweis weist den Restsaldo als nicht gedeckt aus."
      properties:
        total_carry_forward_mwh:
          type: number
          description: "Restsaldo in MWh mit drei Nachkommastellen, unter 1 MWh, solange in den Monatsabschlüssen keine ganzen HKN gefehlt haben"
          example: 0.400
      required:
        - total_carry_forward_mwh
  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.energy/errors/portfolio_not_found
            title: Portfolio nicht gefunden
            status: 404
            instance: /v1/portfolios/pf_8k3d92hs
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.energy/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/proofs/green-spot/2026-3
            errors:
              - field: month
                code: invalid_format
                message: "Invalid month format. Expected YYYY-MM, received '2026-3'"
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.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://api.otark.energy/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: proofs:read. Please create a new API key with the required scopes."
    RateLimited:
      description: Ratenbegrenzung überschritten — die Antwort nennt Grenze und Rücksetzfenster in den Headern
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.energy/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/portfolios:
    get:
      operationId: listPortfolios
      summary: Portfolios auflisten
      description: "Die Portfolios des angemeldeten Teilnehmers auflisten. Ein Portfolio ist die Einheit, an der der Verbrauchsabgleich gemessen wird; die dahinterliegende Zielkurve wird je Viertelstunde geführt, nach außen gibt es aber nur die Stunde — die API liefert nie Viertelstundenwerte.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Portfolios
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Portfolios
          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/PortfolioList"
              example:
                portfolios:
                  - id: pf_8k3d92hs
                    name: Werk Nord
                    target_curve_source: metering_data
                    created_at: "2026-01-05T09: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"
  /v1/portfolios/{portfolio_id}:
    get:
      operationId: getPortfolio
      summary: Portfolio abrufen
      description: "Ein einzelnes Portfolio über seine Kennung abrufen.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Portfolios
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/PortfolioIdParam"
      responses:
        "200":
          description: Angaben zum Portfolio
          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/Portfolio"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/portfolios/{portfolio_id}/coverage-matching/{month}:
    get:
      operationId: getCoverageMatching
      summary: Verbrauchsabgleich abrufen
      description: "Der Verbrauchsabgleich eines Portfolios für einen Liefermonat, stundenscharf. Je Stunde setzt der Report die HC und Ansprüche des Käufers gegen die Zielkurve: gedeckt, Unterdeckung und Überdeckung. Überdeckung wird nie in eine andere Stunde übertragen — eine Überschussstunde füllt keine Fehlstunde. Der Report ist produktneutral: HC aus 1-Click PPA zählen ebenso wie HC und Ansprüche aus Green SPOT, vor dem Monatsabschluss als Anspruch. Fehlt ein Viertelstundenwert der Zielkurve, rechnet OES die Stunde mit den vorliegenden Viertelstunden. Ohne Zielkurve weist der Report allein die Zertifikatskurve aus; `target_curve_mwh`, `covered_mwh`, `under_coverage_mwh` und `over_coverage_mwh` sind dann null. Die Stundenwerte sind laufend abrufbar, sobald sie entstehen.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Coverage matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/PortfolioIdParam"
        - $ref: "#/components/parameters/MonthParam"
        - $ref: "#/components/parameters/FormatParam"
      responses:
        "200":
          description: Verbrauchsabgleich — der vollständige Monat, ohne Paginierung
          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/ConsumptionMatchingReport"
              example:
                portfolio_id: pf_8k3d92hs
                month: "2026-03"
                hours:
                  - date: "2026-03-18"
                    hour: 14
                    hour_suffix: null
                    target_curve_mwh: 30.000
                    hc_held_mwh: 30.500
                    covered_mwh: 30.000
                    under_coverage_mwh: 0.000
                    over_coverage_mwh: 0.500
                  - date: "2026-03-18"
                    hour: 15
                    hour_suffix: null
                    target_curve_mwh: 30.000
                    hc_held_mwh: 28.500
                    covered_mwh: 28.500
                    under_coverage_mwh: 1.500
                    over_coverage_mwh: 0.000
                  - date: "2026-03-18"
                    hour: 16
                    hour_suffix: null
                    target_curve_mwh: 30.000
                    hc_held_mwh: 31.000
                    covered_mwh: 30.000
                    under_coverage_mwh: 0.000
                    over_coverage_mwh: 1.000
                totals:
                  target_curve_mwh: 90.000
                  hc_held_mwh: 90.000
                  covered_mwh: 88.500
                  under_coverage_mwh: 1.500
                  over_coverage_mwh: 1.500
            text/csv:
              schema:
                type: string
                description: Derselbe Inhalt als CSV — eine Zeile je Stunde, die Spaltenüberschriften in der ersten Zeile. Die Spalte `hour_suffix` bleibt leer, außer bei der doppelten Stunde 3 am Tag der Umstellung auf Winterzeit (`A`/`B`).
              example: |
                date,hour,hour_suffix,target_curve_mwh,hc_held_mwh,covered_mwh,under_coverage_mwh,over_coverage_mwh
                2026-03-18,14,,30.000,30.500,30.000,0.000,0.500
                2026-03-18,15,,30.000,28.500,28.500,1.500,0.000
                2026-03-18,16,,30.000,31.000,30.000,0.000,1.000
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/proofs/green-spot:
    get:
      operationId: listGreenSpotProofPackages
      summary: Green-SPOT-Nachweispakete auflisten
      description: "Die Liefermonate auflisten, für die ein Green-SPOT-Nachweispaket vorliegt, samt ihrem Stand der Finalität. Ein Monat wird mit dem Monatsabschluss am 10. des übernächsten Monats final.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Proofs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liefermonate samt ihrem Stand der Finalität
          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/ProofPackageList"
              example:
                proof_packages:
                  - month: "2026-07"
                    final: false
                    cut_off_date: "2026-09-10"
                  - month: "2026-03"
                    final: true
                    cut_off_date: "2026-05-10"
                pagination:
                  limit: 10
                  has_more: false
                  next_cursor: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/proofs/green-spot/{month}:
    get:
      operationId: getGreenSpotProofPackage
      summary: Green-SPOT-Nachweispaket abrufen
      description: "Das Green-SPOT-Nachweispaket eines Liefermonats: die stundenscharfe HC-Zeitreihe mit der Ausweisung je Menge, der Deckungsquelle (`coupled` aus dem Bündel aus Strom und QHC, `time_matched` aus dem Granular Matching) und der Anlagenzuordnung je Stunde, dazu datierte Nachträge, als Backup gelieferte HKN und die entwertete HKN-Menge. Ab D+1 liefert der Report vorläufige Stundenwerte aus Messwerten und Verkäufermeldung, die Mengen als Anspruch mit ausstehender Zuteilung. Mit dem Monatsabschluss am 10. des übernächsten Monats teilt OES die HC und HKN je Stunde und Anlage zu, und der Nachweis des Monats ist final. Weil der HKN-Übertrag je Käufer über alle Anlagen abgerundet wird, können HKN und GC auf Bruchteilsebene aus verschiedenen Anlagen stammen. Was fehlt, weist der Nachweis aus und ersetzt es nicht; die Ursache steht je Menge dabei. Eine PDF-Fassung für Prüfer liefert die Anfrage mit `Accept: application/pdf`.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Proofs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/MonthParam"
        - $ref: "#/components/parameters/FormatParam"
      responses:
        "200":
          description: Green-SPOT-Nachweispaket — der vollständige Monat, ohne Paginierung
          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/GreenSpotProofPackage"
              example:
                month: "2026-03"
                final: true
                cut_off_date: "2026-05-10"
                hours:
                  - date: "2026-03-18"
                    hour: 14
                    hour_suffix: null
                    positions:
                      - quantity_mwh: 16.000
                        disclosure: covered_go_backed
                        coverage_source: coupled
                        asset:
                          id: ast_7p2q9r4s
                          mastr_number: SEE941280003651
                          name: WEA Nord 1
                          technology: wind_onshore
                          location: Windparkstraße 1, 25813 Husum, DE
                          commissioning_date: "2019-06-27"
                        cause: null
                      - quantity_mwh: 13.500
                        disclosure: covered_go_backed
                        coverage_source: coupled
                        asset:
                          id: ast_3f8b1c6d
                          mastr_number: SEE905467231018
                          name: PV Süd 2
                          technology: solar
                          location: Industriestraße 5, 84028 Landshut, DE
                          commissioning_date: "2021-04-30"
                        cause: null
                      - quantity_mwh: 0.500
                        disclosure: not_green_covered
                        coverage_source: null
                        asset: null
                        cause: coverage_gap
                addenda:
                  - recorded_at: "2026-06-10T09:30:00Z"
                    type: aftermarket_purchase
                    date: "2026-03-18"
                    hour: 14
                    quantity_mwh: 1.000
                    asset:
                      id: ast_3f8b1c6d
                      mastr_number: SEE905467231018
                      name: PV Süd 2
                      technology: solar
                      location: Industriestraße 5, 84028 Landshut, DE
                      commissioning_date: "2021-04-30"
                rounding_offsets: []
                go_cancelled_mwh: 120.000
            text/csv:
              schema:
                type: string
                description: Derselbe Inhalt als CSV — eine Zeile je Stunde und Position, die Spaltenüberschriften in der ersten Zeile. Die Spalte `hour_suffix` bleibt leer, außer bei der doppelten Stunde 3 am Tag der Umstellung auf Winterzeit (`A`/`B`).
              example: |
                date,hour,hour_suffix,quantity_mwh,disclosure,coverage_source,asset,cause
                2026-03-18,14,,16.000,covered_go_backed,coupled,WEA Nord 1,
                2026-03-18,14,,13.500,covered_go_backed,coupled,PV Süd 2,
                2026-03-18,14,,0.500,not_green_covered,,,coverage_gap
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/proofs/annual/{year}:
    get:
      operationId: getAnnualProof
      summary: Jahresnachweis abrufen
      description: "Der Jahresnachweis des angemeldeten Teilnehmers, einmal jährlich zum 31. März des Folgejahres erstellt, in denselben Formaten wie die Monatsreports. Er trägt die Jahres-Zeitreihe aus 8.760 Stundenwerten (8.784 im Schaltjahr), produktneutral über Green SPOT und 1-Click PPA hinweg, mit den Summen je Ausweisung, der entwerteten HKN-Menge des Jahres und den im Dezember-Clearing als Backup gelieferten HKN. Solange der Nachweis des angefragten Jahres nicht erstellt ist, antwortet die Route mit 404. Eine PDF-Fassung für Prüfer liefert die Anfrage mit `Accept: application/pdf`.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Proofs
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - name: year
          in: path
          required: true
          description: Kalenderjahr (`YYYY`)
          schema:
            type: integer
            example: 2026
        - $ref: "#/components/parameters/FormatParam"
      responses:
        "200":
          description: Jahresnachweis — das vollständige Jahr, ohne Paginierung
          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/AnnualProof"
              example:
                year: 2026
                hours:
                  - date: "2026-03-18"
                    hour: 14
                    hour_suffix: null
                    positions:
                      - quantity_mwh: 16.000
                        disclosure: covered_go_backed
                        coverage_source: coupled
                        asset:
                          id: ast_7p2q9r4s
                          mastr_number: SEE941280003651
                          name: WEA Nord 1
                          technology: wind_onshore
                          location: Windparkstraße 1, 25813 Husum, DE
                          commissioning_date: "2019-06-27"
                        cause: null
                      - quantity_mwh: 13.500
                        disclosure: covered_go_backed
                        coverage_source: coupled
                        asset:
                          id: ast_3f8b1c6d
                          mastr_number: SEE905467231018
                          name: PV Süd 2
                          technology: solar
                          location: Industriestraße 5, 84028 Landshut, DE
                          commissioning_date: "2021-04-30"
                        cause: null
                      - quantity_mwh: 0.500
                        disclosure: not_green_covered
                        coverage_source: null
                        asset: null
                        cause: coverage_gap
                totals:
                  covered_go_backed_mwh: 1385.000
                  allocated_go_pending_mwh: 0.000
                  not_green_covered_mwh: 24.000
                  uncovered_mwh: 5.000
                go_cancelled_mwh: 1385.000
                rounding_offsets:
                  - quantity_mwh: 1.000
                    source_asset:
                      id: ast_3f8b1c6d
                      mastr_number: SEE905467231018
                      name: PV Süd 2
                      technology: solar
                      location: Industriestraße 5, 84028 Landshut, DE
                      commissioning_date: "2021-04-30"
            text/csv:
              schema:
                type: string
                description: Derselbe Inhalt als CSV — eine Zeile je Stunde und Position, die Spaltenüberschriften in der ersten Zeile. Die Spalte `hour_suffix` bleibt leer, außer bei der doppelten Stunde 3 am Tag der Umstellung auf Winterzeit (`A`/`B`).
              example: |
                date,hour,hour_suffix,quantity_mwh,disclosure,coverage_source,asset,cause
                2026-03-18,14,,16.000,covered_go_backed,coupled,WEA Nord 1,
                2026-03-18,14,,13.500,covered_go_backed,coupled,PV Süd 2,
                2026-03-18,14,,0.500,not_green_covered,,,coverage_gap
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/fractional-account:
    get:
      operationId: getFractionalAccount
      summary: Restsaldo abrufen
      description: "Den aktuellen Restsaldo des angemeldeten Teilnehmers abrufen: die Differenz zwischen seinem GCR-Konto bei OES (drei Nachkommastellen) und den auf sein HKNR-Konto übertragenen HKN (ganze HKN) im laufenden Kalenderjahr. Im Monatsabschluss überträgt OES die abgerundete kumulierte GC-Menge des Jahres abzüglich der schon übertragenen HKN, je Käufer über alle Anlagen; der Rest rollt in den Folgemonat. Mit dem Dezember-Abschluss am 10. Februar erhält der Käufer für den offenen Restsaldo den Jahresreferenzpreis P_year in bar, oder OES liefert als Backup einen HKN desselben Erzeugungsmonats aus einer anderen Anlage; ein unterjährig ausgeschiedener Käufer ebenso. Einen Verfall gibt es nicht.\n\nErforderlicher Scope: `proofs:read`"
      tags:
        - Fractional account
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - proofs:read
      parameters:
        - $ref: "#/components/parameters/FormatParam"
      responses:
        "200":
          description: Stand des Restsaldos
          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/FractionalAccount"
              example:
                total_carry_forward_mwh: 0.400
            text/csv:
              schema:
                type: string
                description: Derselbe Inhalt als CSV, die Spaltenüberschrift in der ersten Zeile
              example: |
                total_carry_forward_mwh
                0.400
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
