Engrate Netzbetreiberwechsel API

openapi: 3.2.0
info:
  title: Netzbetreiber-API (Referenzentwurf) Netzbetreiberwechsel 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: Netzbetreiberwechsel
  description: Übergabepaket beim Wechsel des zuständigen Netzbetreibers.
paths:
  /network-operator-change-packages:
    post:
      tags:
      - Netzbetreiberwechsel
      operationId: createNetworkOperatorChangePackage
      summary: Übergabepaket anfordern
      description: 'Fordert das Übergabepaket zu einem Netzbetreiberwechsel an.


        Diese Operation demonstriert den **standardkonformen Umgang mit verzögerten

        Antworten**. Die Zusammenstellung eines Übergabepakets kann umfangreich sein und

        innerhalb eines technischen Timeouts nicht abschließbar. Statt eine Rückrufkonstruktion

        mit selbst geführtem Zustand einzuführen, nutzt dieser Entwurf das in HTTP dafür

        vorgesehene Verfahren:


        1. Der Server antwortet mit `202 Accepted` und dem `Location`-Header auf die URL der

        künftigen Ergebnisressource, dazu `Retry-After` mit dem frühesten sinnvollen

        Abrufzeitpunkt.

        2. Solange das Ergebnis aussteht, antwortet ein `GET` auf diese URL erneut mit `202`

        und aktualisiertem `Retry-After`.

        3. Sobald das Ergebnis vorliegt, gibt derselbe `GET` mit `200` die Ressource zurück.


        Der Aufrufer muss dafür keinen Vorgangszustand vorhalten — die URL **ist** der

        Zustand.'
      security:
      - oauth2:
        - netzbetreiberwechsel:schreiben
      requestBody:
        required: true
        content:
          application/vnd.edi-energy+json:
            schema:
              $ref: '#/components/schemas/NetworkOperatorChangeRequest'
      responses:
        '202':
          description: 'Die Anforderung wurde angenommen. Das Ergebnis wird unter der in `Location`

            genannten URL bereitgestellt.

            '
          headers:
            Location:
              description: URL der Ergebnisressource.
              schema:
                type: string
                format: uri-reference
            Retry-After:
              description: Frühester sinnvoller Abrufzeitpunkt in Sekunden.
              schema:
                type: integer
                minimum: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /network-operator-change-packages/{packageId}:
    parameters:
    - name: packageId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/NetworkOperatorChangePackageId'
    get:
      tags:
      - Netzbetreiberwechsel
      operationId: getNetworkOperatorChangePackage
      summary: Übergabepaket abrufen
      responses:
        '200':
          description: Das vollständige Übergabepaket.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/NetworkOperatorChangePackageDocument'
        '202':
          description: 'Das Paket wird noch zusammengestellt. `Retry-After` nennt den frühesten

            sinnvollen erneuten Abrufzeitpunkt.

            '
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/PendingResult'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    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'
  schemas:
    NetworkOperatorChangeRequest:
      type: object
      required:
      - locationBundleId
      - effectiveFrom
      properties:
        locationBundleId:
          $ref: '#/components/schemas/LocationBundleId'
        effectiveFrom:
          $ref: '#/components/schemas/DayBoundary'
        successorNetworkOperator:
          $ref: '#/components/schemas/MarketPartnerRef'
    PendingResult:
      type: object
      required:
      - status
      properties:
        status:
          const: inArbeit
        expectedAvailableAt:
          type: string
          format: date-time
          description: Voraussichtlicher Zeitpunkt der Bereitstellung.
    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
    NetworkOperatorChangePackageId:
      type: string
      pattern: ^P[A-Z\d]{9}\d$
      examples:
      - P1234848431
    OperatorAssignment:
      type: object
      required:
      - objectType
      - objectId
      properties:
        objectType:
          type: string
          enum:
          - Netzlokation
          - Messlokation
          - Marktlokation
          - Tranche
          - SteuerbareRessource
        objectId:
          type: string
        href:
          type: string
          format: uri-reference
        meteringPointOperator:
          $ref: '#/components/schemas/MarketPartnerRef'
        supplier:
          $ref: '#/components/schemas/MarketPartnerRef'
        transmissionSystemOperator:
          $ref: '#/components/schemas/MarketPartnerRef'
    MarketPartnerId:
      type: string
      pattern: ^\d{13}$
      description: Marktpartner-ID.
      examples:
      - '9900987654321'
    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
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type: string
          format: uri-reference
          description: URL der referenzierten Ressource.
        title:
          type: string
    NetworkOperatorChangePackageDocument:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/NetworkOperatorChangePackage'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            locationBundle:
              $ref: '#/components/schemas/Link'
    NetworkOperatorChangePackage:
      type: object
      required:
      - type
      - packageId
      - effectiveFrom
      - locationBundle
      - assignments
      properties:
        type:
          const: NetzbetreiberwechselPaket
        packageId:
          $ref: '#/components/schemas/NetworkOperatorChangePackageId'
        href:
          type: string
          format: uri-reference
        effectiveFrom:
          $ref: '#/components/schemas/DayBoundary'
        locationBundle:
          $ref: '#/components/schemas/Link'
          description: 'Verweis auf das Bündel statt Einbettung einer Kopie.


            In der konsultierten Fassung wird das vollständige Lokationsbündel in das

            Wechselpaket eingebettet. Damit existieren zwei Kopien desselben Sachverhalts,

            die auseinanderlaufen können — und das Paket mischt zwei Zeitmodelle, weil das

            eingebettete Bündel Zeitscheiben trägt, die Marktpartnerzuordnung des Pakets

            aber ausdrücklich nicht.

            '
        assignments:
          type: array
          description: 'Die Marktpartnerzuordnung zum Wechselzeitpunkt. Als einheitliche Liste über

            alle Objekttypen statt fünf paralleler, gleichartiger Arrays.

            '
          items:
            $ref: '#/components/schemas/OperatorAssignment'
    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'
    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
  headers:
    ETag:
      description: Version der Ressource für bedingte Anfragen.
      schema:
        type: string
  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.

        '