Engrate Clearing API

openapi: 3.2.0
info:
  title: Netzbetreiber-API (Referenzentwurf) Clearing API
  version: 2026-2.0.0
  summary: Ressourcenorientierter Gegenentwurf zu locationBundleV1
  description: '**Referenzentwurf — kein offizielles Dokument der Bundesnetzagentur, des BDEW oder der

    Projektgruppe EDI@Energy.**


    Dieser Entwurf ist ein Konsultationsbeitrag zu Mitteilung Nr.'
  contact:
    name: '[Unternehmen — Kontakt eintragen]'
  license:
    name: CC0-1.0
    identifier: CC0-1.0
servers:
- url: https://{host}/nb/{basePath}
  description: 'Endpunkt der Netzbetreiber-API. Host und Basispfad werden über den Verzeichnisdienst

    aufgelöst; die API-Kennung ist `nb`.

    '
  variables:
    host:
      default: api.example-netzbetreiber.de
    basePath:
      default: 2026-2
      description: 'Semester-Release. Zusätzlich steht der unveränderliche Pfad ohne Versionsangabe

        zur Verfügung, der stets auf das aktuell verpflichtende Semester-Release zeigt,

        sowie `v` für die Vorweg-Version.

        '
security:
- oauth2:
  - lokationsbuendel:lesen
tags:
- name: Clearing
  description: Abweichende Sichtweisen als Vorgang mit definiertem Endzustand.
paths:
  /location-bundles/{locationBundleId}/clearing-cases:
    parameters:
    - $ref: '#/components/parameters/LocationBundleId'
    get:
      tags:
      - Clearing
      operationId: listClearingCases
      summary: Clearing-Fälle zu einem Lokationsbündel auflisten
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Cursor'
      - name: state
        in: query
        schema:
          $ref: '#/components/schemas/ClearingState'
      responses:
        '200':
          description: Die Clearing-Fälle.
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/ClearingCaseList'
    post:
      tags:
      - Clearing
      operationId: createClearingCase
      summary: Clearing-Fall eröffnen
      description: 'Eröffnet einen Clearing-Fall, wenn die Sicht des Berechtigten von der Sicht des

        Netzbetreibers abweicht.


        Der wesentliche Unterschied zur konsultierten Fassung: Das Clearing ist hier eine

        **Ressource mit Zustand und Lebenszyklus**, nicht ein Aufruf ohne Rückbezug. Der

        Fall hat eine URL, einen Zustand (`offen`, `inBearbeitung`, `beigelegt`,

        `zurückgewiesen`), einen Eröffner, einen Zeitpunkt und eine Frist. Beide Seiten

        können jederzeit abrufen, wie der Stand ist. In der konsultierten Fassung trägt der

        Clearing-Aufruf keine Vorgangsreferenz und kennt keinen definierten Endzustand.


        `POST` ist nicht idempotent. Um doppelte Fälle zu vermeiden, kann der Aufrufer den

        Header `Idempotency-Key` setzen; ein Wiederholungsaufruf mit demselben Schlüssel

        gibt den bereits erzeugten Fall zurück.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optionaler Schlüssel zur Duplikatvermeidung bei Wiederholungsaufrufen.
        schema:
          type: string
          format: uuid
      security:
      - oauth2:
        - clearing:schreiben
      requestBody:
        required: true
        content:
          application/vnd.edi-energy+json:
            schema:
              $ref: '#/components/schemas/ClearingCaseWrite'
      responses:
        '201':
          description: Der Clearing-Fall wurde eröffnet.
          headers:
            Location:
              description: URL des erzeugten Clearing-Falls.
              schema:
                type: string
                format: uri-reference
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/ClearingCaseDocument'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: 'Zu demselben Sachverhalt besteht bereits ein offener Clearing-Fall. Der

            Response-Body verweist über `instance` auf dessen URL.

            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /clearing-cases/{clearingCaseId}:
    parameters:
    - name: clearingCaseId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Clearing
      operationId: getClearingCase
      summary: Clearing-Fall abrufen
      responses:
        '200':
          description: Der Clearing-Fall.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/ClearingCaseDocument'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Clearing
      operationId: patchClearingCase
      summary: Clearing-Fall fortschreiben oder abschließen
      description: 'Ändert den Zustand des Clearing-Falls. Zulässige Übergänge:


        - `offen` → `inBearbeitung` (durch den Netzbetreiber)

        - `offen` | `inBearbeitung` → `beigelegt` (durch den Netzbetreiber, nachdem er das

        Bündel korrigiert hat — `resolution.correctedBundle` verweist auf den neuen Stand)

        - `offen` | `inBearbeitung` → `zurückgewiesen` (durch den Netzbetreiber, mit

        Antwortcode aus dem Entscheidungsbaumdiagramm und Begründung)

        - `offen` | `inBearbeitung` → `zurückgezogen` (durch den Eröffner)


        Ein unzulässiger Übergang wird mit `422` und einem Problem-Details-Dokument

        abgelehnt, das den aktuellen und die zulässigen Folgezustände nennt.'
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      security:
      - oauth2:
        - clearing:schreiben
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ClearingCasePatch'
      responses:
        '200':
          description: Der aktualisierte Clearing-Fall.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/ClearingCaseDocument'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    ClearingCaseDocument:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/ClearingCase'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            bundle:
              $ref: '#/components/schemas/Link'
    MarketPartnerRef:
      type: object
      required:
      - marketPartnerId
      properties:
        marketPartnerId:
          $ref: '#/components/schemas/MarketPartnerId'
        role:
          type: string
          enum:
          - NB
          - LF
          - MSB
          - MWV
          - UENB
        href:
          type: string
          format: uri-reference
    IntelligentMeteringSystem:
      type: object
      required:
      - type
      - configurationId
      - obisCodes
      additionalProperties: false
      properties:
        type:
          const: iMS
        configurationId:
          type: string
          description: Konfigurations-ID. Bei einem intelligenten Messsystem erforderlich.
        obisCodes:
          type: array
          minItems: 1
          items:
            type: string
    ClearingCase:
      type: object
      required:
      - type
      - clearingCaseId
      - state
      - openedBy
      - openedAt
      - subject
      properties:
        type:
          const: ClearingFall
        clearingCaseId:
          type: string
          format: uuid
        href:
          type: string
          format: uri-reference
        state:
          $ref: '#/components/schemas/ClearingState'
        openedBy:
          $ref: '#/components/schemas/MarketPartnerRef'
        openedAt:
          type: string
          format: date-time
        dueAt:
          type: string
          format: date-time
          description: Frist, bis zu der der Verantwortliche zu reagieren hat.
        subject:
          type: object
          required:
          - locationBundle
          description: Gegenstand des Falls.
          properties:
            locationBundle:
              $ref: '#/components/schemas/Link'
            timeSlice:
              allOf:
              - $ref: '#/components/schemas/Link'
              description: Betroffene Zeitscheibe, sofern der Fall auf eine begrenzt ist.
        observed:
          allOf:
          - $ref: '#/components/schemas/TimeSliceWrite'
          description: 'Der Stand, den der Eröffner beim Verantwortlichen vorgefunden hat — als Beleg

            dafür, worauf sich der Fall bezieht.

            '
        expected:
          allOf:
          - $ref: '#/components/schemas/TimeSliceWrite'
          description: Der Stand, den der Eröffner erwartet.
        reason:
          type: string
          description: Begründung des Eröffners.
        resolution:
          $ref: '#/components/schemas/ClearingResolution'
    Metering:
      description: 'Die Messung an einer Messlokation, als tagged union über die Art des Messsystems.


        **Konkretes Beispiel für den Nutzen:** Bei einem intelligenten Messsystem ist die

        Konfigurations-ID erforderlich; bei einem konventionellen Messsystem darf sie

        nicht vorhanden sein; bei einer pauschalen Messlokation gibt es weder Zähler noch

        OBIS-Kennzahlen noch Messwerte. Heute stehen diese drei Regeln als Bedingungen im

        Anwendungshandbuch. Hier sind sie Teil des Schemas: Ein Payload, der einer

        pauschalen Messlokation eine OBIS-Kennzahl zuordnet, ist schlicht nicht gültig und

        wird von jedem Standardvalidator abgelehnt — nicht erst im Produktivbetrieb durch

        einen Klärfall.

        '
      oneOf:
      - $ref: '#/components/schemas/IntelligentMeteringSystem'
      - $ref: '#/components/schemas/ModernMeteringDevice'
      - $ref: '#/components/schemas/FlatRateMetering'
      discriminator:
        propertyName: type
        mapping:
          iMS: '#/components/schemas/IntelligentMeteringSystem'
          mME: '#/components/schemas/ModernMeteringDevice'
          pauschal: '#/components/schemas/FlatRateMetering'
    LocationBundleId:
      type: string
      pattern: ^F[A-Z\d]{9}\d$
      description: 'Lokationsbündel-ID.


        Muster und Beispiel sind unverändert aus der konsultierten Fassung

        übernommen (`schema/identifier/locationBundleId.yaml`).


        **Hinweis:** Issue #175 im Repository `EDI-Energy/api-electricity`

        (eingereicht am 20.08.2026) macht geltend, dass nach der

        Bildungsvorschrift an der ersten Stelle `G` statt `F` stehen muss.

        Wir teilen diese Auffassung. Wird das Issue angenommen, sind Muster

        und Beispiele hier und in den beigefügten Beispiel-Payloads

        entsprechend auf `G` zu ändern. Wir haben bewusst nicht vorgegriffen,

        damit dieser Entwurf gegen den konsultierten Stand vergleichbar

        bleibt.

        '
      examples:
      - F1234848431
    ControllableResourceMember:
      type: object
      required:
      - type
      - srId
      additionalProperties: false
      properties:
        type:
          const: SteuerbareRessource
        srId:
          $ref: '#/components/schemas/SrId'
        href:
          type: string
          format: uri-reference
    Problem:
      type: object
      description: 'Fehlermeldung nach RFC 9457 (Problem Details for HTTP APIs).


        Die konsultierte Fassung definiert für keine Operation einen Response-Body — auch

        nicht für `400` und `422`. Ein Empfänger kann einen Validierungsfehler dort nicht

        maschinenlesbar zurückmelden; inhaltliche Fehler müssen den Umweg über einen

        neuen Aufruf in Gegenrichtung nehmen.

        '
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          examples:
          - tag:edi-energy.de:api:error:validation
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        errors:
          type: array
          description: Einzelne Verstöße mit Fundstelle.
          items:
            type: object
            required:
            - pointer
            - message
            properties:
              pointer:
                type: string
                description: JSON-Pointer nach RFC 6901 auf die betroffene Stelle.
                examples:
                - /timeSlices/0/members/2/metering/configurationId
              message:
                type: string
              code:
                type: string
    MaloId:
      type: string
      pattern: ^\d{11}$
      description: Identifiziert die Marktlokation oder Tranche.
      examples:
      - '57685676748'
    RelationNeloToMelo:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: NetzlokationZuMesslokation
        from:
          $ref: '#/components/schemas/NeloId'
        to:
          $ref: '#/components/schemas/MeloId'
    ClearingCaseList:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ClearingCase'
        links:
          $ref: '#/components/schemas/ListLinks'
    TrId:
      type: string
      pattern: ^D[A-Z\d]{9}\d$
      description: ID der technischen Ressource.
      examples:
      - D1234848431
    MeteringLocationMember:
      type: object
      required:
      - type
      - meloId
      - metering
      additionalProperties: false
      properties:
        type:
          const: Messlokation
        meloId:
          $ref: '#/components/schemas/MeloId'
        href:
          type: string
          format: uri-reference
        meteringPointOperator:
          $ref: '#/components/schemas/MarketPartnerRef'
        metering:
          $ref: '#/components/schemas/Metering'
    MarketPartnerId:
      type: string
      pattern: ^\d{13}$
      description: Marktpartner-ID.
      examples:
      - '9900987654321'
    FlatRateMetering:
      type: object
      required:
      - type
      additionalProperties: false
      properties:
        type:
          const: pauschal
        description:
          type: string
          description: 'Pauschale Messlokation ohne Zähler. Trägt eine Zählpunktbezeichnung, aber

            keine Messeinrichtung, keine OBIS-Kennzahlen und keine Messwerte.


            Mitteilung Nr. 57 sieht vor, dass künftig jede Marktlokation Strom mindestens

            eine zugeordnete Messlokation aufweist — entweder eine pauschale ohne Zähler

            oder eine gemessene. Dieser Typ macht die Unterscheidung im Schema explizit,

            statt sie einer Bedingung im Anwendungshandbuch zu überlassen.

            '
    ClearingCaseWrite:
      type: object
      required:
      - expected
      - reason
      properties:
        timeSlice:
          type: string
          format: date
          description: Beginn der betroffenen Zeitscheibe.
        observedETag:
          type: string
          description: '`ETag` des Stands, auf den sich der Fall bezieht. Damit ist eindeutig, welchen

            Stand der Eröffner gesehen hat — auch wenn der Verantwortliche zwischenzeitlich

            geändert hat.

            '
        expected:
          $ref: '#/components/schemas/TimeSliceWrite'
        reason:
          type: string
    DayBoundary:
      type: string
      format: date
      description: 'Kalendertag. Der zugehörige Zeitpunkt ist stets der Tagesbeginn 00:00 Uhr

        gesetzlicher deutscher Zeit.


        Anmerkung zur Abweichung von der konsultierten Fassung: Dort wird derselbe

        Sachverhalt als UTC-Zeitstempel mit Regex-Muster übertragen

        (`2023-08-01T22:00:00Z` für den 2. August 2023). Das ist fehleranfällig, weil der

        Zeitzonenversatz zwischen Sommer- und Winterzeit wechselt und ein Leser den

        Kalendertag zurückrechnen muss. Ein Datum ohne Uhrzeit drückt genau das aus, was

        gemeint ist, und ist nicht falsch interpretierbar.

        '
      examples:
      - '2027-10-01'
    BundleMember:
      description: 'Ein Knoten des Lokationsbündels. Der Typ wird über das Feld `type` markiert

        (tagged union). Damit ist für jeden Typ genau festgelegt, welche Felder zulässig

        und welche erforderlich sind — Kombinationen, die es fachlich nicht gibt, sind

        nicht darstellbar.


        Dies ist der in Abschnitt 3.5 der Stellungnahme beschriebene Hebel: Bedingungen,

        die heute als natürlichsprachliche Ad-hoc-Bedingungen im Anwendungshandbuch stehen

        und von jedem Marktpartner eigenständig implementiert werden, wandern in das

        Schema und werden von Standardwerkzeugen geprüft.

        '
      oneOf:
      - $ref: '#/components/schemas/NetworkLocationMember'
      - $ref: '#/components/schemas/MeteringLocationMember'
      - $ref: '#/components/schemas/MarketLocationMember'
      - $ref: '#/components/schemas/TrancheMember'
      - $ref: '#/components/schemas/TechnicalResourceMember'
      - $ref: '#/components/schemas/ControllableResourceMember'
      discriminator:
        propertyName: type
        mapping:
          Netzlokation: '#/components/schemas/NetworkLocationMember'
          Messlokation: '#/components/schemas/MeteringLocationMember'
          Marktlokation: '#/components/schemas/MarketLocationMember'
          Tranche: '#/components/schemas/TrancheMember'
          TechnischeRessource: '#/components/schemas/TechnicalResourceMember'
          SteuerbareRessource: '#/components/schemas/ControllableResourceMember'
    RelationMeloToTr:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: MesslokationZuTechnischerRessource
        from:
          $ref: '#/components/schemas/MeloId'
        to:
          $ref: '#/components/schemas/TrId'
    MarketLocationMember:
      type: object
      required:
      - type
      - maloId
      additionalProperties: false
      properties:
        type:
          const: Marktlokation
        maloId:
          $ref: '#/components/schemas/MaloId'
        href:
          type: string
          format: uri-reference
        supplier:
          $ref: '#/components/schemas/MarketPartnerRef'
        transmissionSystemOperator:
          $ref: '#/components/schemas/MarketPartnerRef'
    ClearingResolution:
      type: object
      required:
      - decisionTree
      - responseCode
      description: 'Der Abschluss des Falls. `decisionTree` und `responseCode` sind unverändert aus der

        bestehenden Regulierung übernommen — die Entscheidungsbaumdiagramme und ihre

        Antwortcodes bleiben gültig und werden hier lediglich an einer Ressource mit

        Zustand geführt statt in einem Aufruf ohne Rückbezug.

        '
      properties:
        decisionTree:
          type: string
          pattern: ^E_\d{4}$
          examples:
          - E_0594
        responseCode:
          type: string
          pattern: ^A[A-Z\d]{2}$
          examples:
          - A10
        reason:
          type: string
          description: 'Freitext. Nur anzugeben, wenn der Antwortcode des Entscheidungsbaumdiagramms

            dies vorsieht.

            '
        correctedBundle:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: 'Bei `beigelegt`: Verweis auf den korrigierten Stand. Der Eröffner kann ihn

            unmittelbar abrufen und prüfen — er muss nicht auf eine gesonderte

            Übermittlung warten.

            '
        resolvedAt:
          type: string
          format: date-time
    RelationMeloToMalo:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: MesslokationZuMarktlokation
        from:
          $ref: '#/components/schemas/MeloId'
        to:
          $ref: '#/components/schemas/MaloId'
    ClearingState:
      type: string
      enum:
      - offen
      - inBearbeitung
      - beigelegt
      - zurueckgewiesen
      - zurueckgezogen
      description: 'Zustand des Clearing-Falls. Dass es diesen Zustand überhaupt gibt, ist der

        wesentliche Unterschied zur konsultierten Fassung: Dort ist das Clearing ein

        Aufruf ohne Vorgangsreferenz, ohne Antwortkanal und ohne definierten Endzustand.

        '
    ClearingCasePatch:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/ClearingState'
        resolution:
          $ref: '#/components/schemas/ClearingResolution'
    RelationMaloToTranche:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: MarktlokationZuTranche
        from:
          $ref: '#/components/schemas/MaloId'
        to:
          $ref: '#/components/schemas/MaloId'
    RelationMaloToTr:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: MarktlokationZuTechnischerRessource
        from:
          $ref: '#/components/schemas/MaloId'
        to:
          $ref: '#/components/schemas/TrId'
    NetworkLocationMember:
      type: object
      required:
      - type
      - neloId
      additionalProperties: false
      properties:
        type:
          const: Netzlokation
        neloId:
          $ref: '#/components/schemas/NeloId'
        href:
          type: string
          format: uri-reference
    SrId:
      type: string
      pattern: ^C[A-Z\d]{9}\d$
      description: ID der steuerbaren Ressource.
      examples:
      - C1234848431
    BundleRelation:
      description: 'Eine gerichtete Kante zwischen zwei Knoten der Zeitscheibe. Quelle und Ziel werden

        über ihre fachliche ID benannt.


        Die zulässigen Typkombinationen sind hier abschließend als `oneOf` festgelegt.

        Sie entsprechen den Zuordnungen der konsultierten Fassung:

        Netzlokation → Messlokation, Messlokation → Messlokation,

        Messlokation → Marktlokation, Messlokation → technische Ressource,

        Marktlokation → technische Ressource, Marktlokation → Tranche.

        '
      oneOf:
      - $ref: '#/components/schemas/RelationNeloToMelo'
      - $ref: '#/components/schemas/RelationMeloToMelo'
      - $ref: '#/components/schemas/RelationMeloToMalo'
      - $ref: '#/components/schemas/RelationMeloToTr'
      - $ref: '#/components/schemas/RelationMaloToTr'
      - $ref: '#/components/schemas/RelationMaloToTranche'
      discriminator:
        propertyName: kind
        mapping:
          NetzlokationZuMesslokation: '#/components/schemas/RelationNeloToMelo'
          MesslokationZuMesslokation: '#/components/schemas/RelationMeloToMelo'
          MesslokationZuMarktlokation: '#/components/schemas/RelationMeloToMalo'
          MesslokationZuTechnischerRessource: '#/components/schemas/RelationMeloToTr'
          MarktlokationZuTechnischerRessource: '#/components/schemas/RelationMaloToTr'
          MarktlokationZuTranche: '#/components/schemas/RelationMaloToTranche'
    TrancheMember:
      type: object
      required:
      - type
      - trancheId
      additionalProperties: false
      description: 'Die Tranche als eigener Knotentyp.


        In der konsultierten Fassung ist die Tranche kein eigenes Objekt, sondern eine

        ID-Liste unter der Marktlokation, die den Datentyp der Marktlokations-ID

        mitbenutzt. Ob eine gegebene elfstellige Ziffernfolge eine Marktlokation oder eine

        Tranche bezeichnet, ergibt sich dort nur aus der Position im Dokument. Als eigener

        Typ ist es eindeutig.

        '
      properties:
        type:
          const: Tranche
        trancheId:
          $ref: '#/components/schemas/MaloId'
        href:
          type: string
          format: uri-reference
        supplier:
          $ref: '#/components/schemas/MarketPartnerRef'
    TimeSliceWrite:
      type: object
      required:
      - validFrom
      - validTo
      - members
      properties:
        validFrom:
          $ref: '#/components/schemas/DayBoundary'
        validTo:
          oneOf:
          - $ref: '#/components/schemas/DayBoundary'
          - type: 'null'
        members:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/BundleMember'
        relations:
          type: array
          items:
            $ref: '#/components/schemas/BundleRelation'
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type: string
          format: uri-reference
          description: URL der referenzierten Ressource.
        title:
          type: string
    RelationMeloToMelo:
      type: object
      required:
      - kind
      - from
      - to
      additionalProperties: false
      properties:
        kind:
          const: MesslokationZuMesslokation
        from:
          $ref: '#/components/schemas/MeloId'
        to:
          $ref: '#/components/schemas/MeloId'
    NeloId:
      type: string
      pattern: ^E[A-Z\d]{9}\d$
      description: Netzlokations-ID.
      examples:
      - E1234848431
    MeloId:
      type: string
      pattern: ^DE\d{11}[A-Z\d]{20}$
      description: Messlokations-ID (Zählpunktbezeichnung).
      examples:
      - DE00014545768S0000000000000003054
    TechnicalResourceMember:
      type: object
      required:
      - type
      - trId
      additionalProperties: false
      properties:
        type:
          const: TechnischeRessource
        trId:
          $ref: '#/components/schemas/TrId'
        href:
          type: string
          format: uri-reference
    ModernMeteringDevice:
      type: object
      required:
      - type
      - obisCodes
      additionalProperties: false
      properties:
        type:
          const: mME
        obisCodes:
          type: array
          minItems: 1
          items:
            type: string
    ListLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Nächste Seite. Fehlt, wenn keine weiteren Elemente vorliegen.
        prev:
          $ref: '#/components/schemas/Link'
  parameters:
    PageSize:
      name: page-size
      in: query
      description: Maximale Anzahl Elemente je Seite.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      description: 'Fortsetzungsmarke aus `links.next` einer vorangegangenen Antwort. Für Clients ist

        der Wert undurchsichtig; aus seiner Struktur darf nicht auf den verwendeten

        Paginierungsmechanismus geschlossen werden.

        '
      schema:
        type: string
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: 'Der zuletzt gelesene `ETag`. Verhindert, dass eine zwischenzeitliche Änderung eines

        anderen Aufrufers unbemerkt überschrieben wird.

        '
      schema:
        type: string
    LocationBundleId:
      name: locationBundleId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/LocationBundleId'
  headers:
    ETag:
      description: Version der Ressource für bedingte Anfragen.
      schema:
        type: string
  responses:
    PreconditionFailed:
      description: 'Der in `If-Match` angegebene `ETag` entspricht nicht dem aktuellen Stand — die

        Ressource wurde zwischenzeitlich geändert.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: 'Authentisiert, aber für die angeforderte Ressource nicht berechtigt. Die

        Berechtigung ergibt sich aus der fachlichen Zuordnung des Marktpartners zu Objekt

        und Zeitraum.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Ressource nicht vorhanden.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: Fehlerhafte Anfrage.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UnprocessableEntity:
      description: 'Syntaktisch gültig, aber fachlich nicht verarbeitbar. `errors` benennt die

        betroffenen Stellen über JSON-Pointer nach RFC 6901.

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0. Die Authentisierung des Clients am Authorization Server erfolgt in der

        Ausbaustufe 1 über das Signaturzertifikat der Smart-Metering-PKI; die Architektur

        ist so angelegt, dass sie später um OpenID Connect und föderierte Identitäten

        (etwa europäische ID-Wallets) erweitert werden kann, ohne die Ressourcen-APIs zu

        ändern.


        Damit werden drei Anforderungen adressiert, die eine ausschließlich

        zertifikatsbasierte Marktpartner-Authentisierung nicht abbilden kann:

        Zugriff von Letztverbrauchern auf ihre eigenen Daten, übertragbare Berechtigungen

        an Dritte und Anschlussfähigkeit an übergreifende Datenräume.

        '
      flows:
        clientCredentials:
          tokenUrl: https://authz.example-netzbetreiber.de/oauth2/token
          scopes:
            lokationsbuendel:lesen: Lokationsbündel und Lokationen lesen
            lokationsbuendel:schreiben: Lokationsbündel ändern (nur verantwortlicher Netzbetreiber)
            clearing:schreiben: Clearing-Fälle eröffnen und fortschreiben
            netzbetreiberwechsel:schreiben: Übergabepakete anfordern
            benachrichtigung:schreiben: Abonnements verwalten
        authorizationCode:
          authorizationUrl: https://authz.example-netzbetreiber.de/oauth2/authorize
          tokenUrl: https://authz.example-netzbetreiber.de/oauth2/token
          scopes:
            lokationsbuendel:lesen: Lokationsbündel und Lokationen lesen
    mtls:
      type: mutualTLS
      description: 'Alternativ zulässig für die reine Marktpartner-zu-Marktpartner-Kommunikation, mit

        Zertifikaten der Smart-Metering-PKI in der Rolle „passiver EMT" gemäß den

        Regelungen zum Übertragungsweg für API-Webdienste.

        '