Engrate Lokationen API

openapi: 3.2.0
info:
  title: Netzbetreiber-API (Referenzentwurf) Lokationen 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: Lokationen
  description: Einzelressourcen der referenzierten Netz-, Markt- und Messlokationen.
paths:
  /network-locations/{neloId}:
    parameters:
    - name: neloId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/NeloId'
    get:
      tags:
      - Lokationen
      operationId: getNetworkLocation
      summary: Netzlokation abrufen
      description: 'Die Netzlokation als eigene Ressource. In der konsultierten Fassung ist sie nur

        eine ID innerhalb eines versandten Dokuments und kann nicht abgerufen werden.


        Damit läuft eine Referenz auf eine dem Empfänger unbekannte Netzlokation dort ins

        Leere und führt zur Zurückweisung des gesamten Dokuments. Hier kann der Empfänger

        der Referenz folgen und das Objekt abrufen.'
      responses:
        '200':
          description: Die Netzlokation.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/NetworkLocationDocument'
        '404':
          $ref: '#/components/responses/NotFound'
  /market-locations/{maloId}:
    parameters:
    - name: maloId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/MaloId'
    get:
      tags:
      - Lokationen
      operationId: getMarketLocation
      summary: Marktlokation oder Tranche abrufen
      responses:
        '200':
          description: Die Marktlokation bzw. Tranche.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/MarketLocationDocument'
        '404':
          $ref: '#/components/responses/NotFound'
  /metering-locations/{meloId}:
    parameters:
    - name: meloId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/MeloId'
    get:
      tags:
      - Lokationen
      operationId: getMeteringLocation
      summary: Messlokation abrufen
      responses:
        '200':
          description: Die Messlokation.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/vnd.edi-energy+json:
              schema:
                $ref: '#/components/schemas/MeteringLocationDocument'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    MarketLocationDocument:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - maloId
          properties:
            type:
              type: string
              enum:
              - Marktlokation
              - Tranche
            maloId:
              $ref: '#/components/schemas/MaloId'
            href:
              type: string
              format: uri-reference
            supplier:
              $ref: '#/components/schemas/MarketPartnerRef'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            locationBundles:
              $ref: '#/components/schemas/Link'
    MaloId:
      type: string
      pattern: ^\d{11}$
      description: Identifiziert die Marktlokation oder Tranche.
      examples:
      - '57685676748'
    NetworkLocationDocument:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - neloId
          properties:
            type:
              const: Netzlokation
            neloId:
              $ref: '#/components/schemas/NeloId'
            href:
              type: string
              format: uri-reference
            networkOperator:
              $ref: '#/components/schemas/MarketPartnerRef'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            locationBundles:
              $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
    MeteringLocationDocument:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - meloId
          - metering
          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'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            locationBundles:
              $ref: '#/components/schemas/Link'
    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'
    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.

            '
    NeloId:
      type: string
      pattern: ^E[A-Z\d]{9}\d$
      description: Netzlokations-ID.
      examples:
      - E1234848431
    ModernMeteringDevice:
      type: object
      required:
      - type
      - obisCodes
      additionalProperties: false
      properties:
        type:
          const: mME
        obisCodes:
          type: array
          minItems: 1
          items:
            type: string
    MeloId:
      type: string
      pattern: ^DE\d{11}[A-Z\d]{20}$
      description: Messlokations-ID (Zählpunktbezeichnung).
      examples:
      - DE00014545768S0000000000000003054
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type: string
          format: uri-reference
          description: URL der referenzierten Ressource.
        title:
          type: string
    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
  responses:
    NotFound:
      description: Ressource nicht vorhanden.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  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.

        '