openapi: 3.0.0
info:
  title: Otark Metering API
  description: API zum Hochladen und Abfragen von 15-Minuten-Messwerten auf der Otark-Plattform — der programmatische Weg anstelle des manuellen CSV-Uploads von Lastgangdateien.
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.com
    description: Produktion
tags:
  - name: Metering points
    description: Messstellen, die im Anlagen-Onboarding angelegt wurden — über die API nur lesbar
  - name: Readings
    description: 15-Minuten-Messwerte je Messstelle
  - name: Imports
    description: CSV-Importe im Format der Lastgangdateien
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: mp_a1b2c3d4
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    FromParam:
      name: from
      in: query
      description: "Filter: interval_start >= diesem Wert (ISO 8601, UTC)"
      schema:
        type: string
        format: date-time
        example: "2026-03-18T12:00:00Z"
    ToParam:
      name: to
      in: query
      description: "Filter: interval_start < diesem Wert (ISO 8601, UTC)"
      schema:
        type: string
        format: date-time
        example: "2026-03-18T13:00:00Z"
  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: mp_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.com/errors/metering_point_not_found
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Metering Point Not Found
        status:
          type: integer
          description: HTTP-Statuscode
          example: 404
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: The requested metering point does not exist or is not assigned to your account.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/metering-points/mp_e4f8a2c6
        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: readings.2.interval_start
        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`, `not_quarter_hour`, `duplicate_interval` oder `validation_failed`"
          example: not_quarter_hour
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: "interval_start must be on a quarter-hour boundary (UTC), received '2026-03-18T12:07:00Z'"
      required:
        - code
        - message
    MeteringPoint:
      type: object
      description: Eine auf der Otark-Plattform registrierte Messstelle. Messstellen entstehen im Anlagen-Onboarding oder beim Einrichten eines Lastgangs — die API legt sie weder an noch ändert sie sie.
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Messstelle
          example: mp_e4f8a2c6
        melo_id:
          type: string
          description: Messlokations-Kennung (MeLo-ID) aus der deutschen Marktkommunikation
          example: DE0009900000000000000000000WEAN01
        malo_id:
          type: string
          description: Marktlokations-Kennung (MaLo-ID) aus der deutschen Marktkommunikation
          example: "41770354291"
        asset_id:
          type: string
          nullable: true
          description: Kennung der zugeordneten Anlage (null bei reinen Verbrauchsmessstellen ohne Anlage, etwa dem Lastgang eines Käufers)
          example: ast_7p2q9r4s
        asset_name:
          type: string
          nullable: true
          description: Anzeigename der zugeordneten Anlage
          example: WEA Nord 1
        direction:
          type: string
          description: Konfigurierte Richtung oder Richtungen des Energieflusses der Messstelle
          enum:
            - production
            - consumption
            - both
          example: production
        interval_minutes:
          type: integer
          description: Länge des Messintervalls in Minuten, immer 15
          example: 15
        status:
          type: string
          description: Status der Messstelle — `pending` bis zum ersten Dateneingang, danach `active`
          enum:
            - pending
            - active
          example: active
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage (UTC)
          example: "2026-01-12T09:00:00Z"
      required:
        - id
        - melo_id
        - malo_id
        - asset_id
        - asset_name
        - direction
        - interval_minutes
        - status
        - created_at
    MeteringPointList:
      type: object
      properties:
        metering_points:
          type: array
          description: Liste der Messstellen
          items:
            $ref: "#/components/schemas/MeteringPoint"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - metering_points
        - pagination
    Reading:
      type: object
      description: Ein einzelner 15-Minuten-Messwert. Messwerte sind durch Intervall und Richtung bestimmt — wird ein Wert für ein bereits vorhandenes Intervall derselben Richtung hochgeladen, überschreibt er den gespeicherten.
      properties:
        interval_start:
          type: string
          format: date-time
          description: Beginn des 15-Minuten-Intervalls (ISO 8601, UTC). Liegt stets auf einer Viertelstundengrenze.
          example: "2026-03-18T12:00:00Z"
        interval_end:
          type: string
          format: date-time
          description: Ende des 15-Minuten-Intervalls (ISO 8601, UTC)
          example: "2026-03-18T12:15:00Z"
        value:
          type: number
          description: Gemessene Energie in kWh (Dezimalzahl)
          example: 4356.742
        direction:
          type: string
          description: Richtung des Energieflusses dieses Messwerts
          enum:
            - production
            - consumption
          example: production
        quality:
          type: string
          description: "Datenqualität des Messwerts: `uploaded` (normale Messung), `forecast` (Werte in der Zukunft) oder `estimated` (geschätzte Werte in der Vergangenheit) — entsprechend den Qualitätskennzeichen U, F und E der CSV-Datei"
          enum:
            - uploaded
            - forecast
            - estimated
          example: uploaded
      required:
        - interval_start
        - interval_end
        - value
        - direction
        - quality
    ReadingList:
      type: object
      properties:
        readings:
          type: array
          description: Liste der Messwerte, aufsteigend nach interval_start sortiert
          items:
            $ref: "#/components/schemas/Reading"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - readings
        - pagination
    ReadingInput:
      type: object
      description: Ein einzelner hochzuladender 15-Minuten-Messwert
      properties:
        interval_start:
          type: string
          format: date-time
          description: Beginn des 15-Minuten-Intervalls (ISO 8601, UTC). Muss auf einer Viertelstundengrenze liegen.
          example: "2026-03-18T12:00:00Z"
        value:
          type: number
          minimum: 0
          description: Gemessene Energie in kWh (Dezimalzahl)
          example: 4356.742
        direction:
          type: string
          description: Richtung des Energieflusses. Pflichtangabe, wenn die Messstelle für beide Richtungen konfiguriert ist; sonst gilt die konfigurierte Richtung.
          enum:
            - production
            - consumption
          example: production
        quality:
          type: string
          description: Datenqualität des Messwerts (Voreinstellung `uploaded`)
          enum:
            - uploaded
            - forecast
            - estimated
          default: uploaded
          example: uploaded
      required:
        - interval_start
        - value
    ReadingBatchRequest:
      type: object
      properties:
        readings:
          type: array
          description: Die hochzuladenden Messwerte. Der Stapel wird als Ganzes verarbeitet — scheitert ein Messwert an der Validierung, wird nichts geschrieben.
          items:
            $ref: "#/components/schemas/ReadingInput"
          minItems: 1
      required:
        - readings
    ReadingBatchResult:
      type: object
      description: Ergebnis eines Stapel-Uploads von Messwerten
      properties:
        metering_point_id:
          type: string
          description: Messstelle, in die die Messwerte geschrieben wurden
          example: mp_e4f8a2c6
        accepted:
          type: integer
          description: Anzahl der geschriebenen Messwerte
          example: 4
        replaced:
          type: integer
          description: Anzahl der Messwerte, die einen vorhandenen Wert desselben Intervalls und derselben Richtung überschrieben haben
          example: 0
      required:
        - metering_point_id
        - accepted
        - replaced
    Import:
      type: object
      description: Ein CSV-Importvorgang. Das Dateiformat folgt der Spezifikation der Lastgangdateien (semikolongetrennt, mit Kopfzeile, ein 15-Minuten-Intervall je Zeile). Eine Datei wird vollständig importiert oder gar nicht — `failed` heißt, dass keine Zeile geschrieben wurde.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Imports
          example: imp_5b9d1c3a
        metering_point_id:
          type: string
          description: Messstelle, in die die Datei importiert wird
          example: mp_e4f8a2c6
        filename:
          type: string
          description: Ursprünglicher Dateiname der hochgeladenen CSV-Datei
          example: wea-nord-1-2026-03-18.csv
        status:
          type: string
          description: "Status des Imports: `pending` (angenommen, noch nicht verarbeitet), `processing`, `completed` (alle Zeilen geschrieben) oder `failed` (keine Zeile geschrieben — siehe `errors`)"
          enum:
            - pending
            - processing
            - completed
            - failed
          example: completed
        rows_total:
          type: integer
          nullable: true
          description: Anzahl der Datenzeilen in der Datei (null, solange die Datei nicht eingelesen ist)
          example: 96
        rows_imported:
          type: integer
          nullable: true
          description: Anzahl der geschriebenen Zeilen — bei Erfolg gleich `rows_total`, bei Fehlschlag 0 (null, solange die Verarbeitung läuft)
          example: 96
        errors:
          type: array
          description: Zeilenbezogene Fehler (nur bei fehlgeschlagenem Import)
          items:
            $ref: "#/components/schemas/ImportRowError"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel des Dateieingangs (UTC)
          example: "2026-03-19T06:30:00Z"
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel des Verarbeitungsendes (null, solange der Import aussteht oder läuft)
          example: "2026-03-19T06:30:12Z"
      required:
        - id
        - metering_point_id
        - filename
        - status
        - rows_total
        - rows_imported
        - created_at
        - completed_at
    ImportRowError:
      type: object
      description: Ein einzelner zeilenbezogener Fehler eines CSV-Imports
      properties:
        row:
          type: integer
          description: Zeilennummer in der CSV-Datei (Zeile 1 ist die Kopfzeile)
          example: 17
        code:
          type: string
          description: "Maschinenlesbarer Fehlercode: `invalid_format`, `invalid_enum_value`, `required`, `value_too_small`, `not_quarter_hour` oder `duplicate_interval`"
          example: invalid_format
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: "Invalid time '25:15' — expected HH:MM"
      required:
        - row
        - code
        - message
  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.com/errors/metering_point_not_found
            title: Messstelle nicht gefunden
            status: 404
            instance: /v1/metering-points/mp_e4f8a2c6
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/metering-points/mp_e4f8a2c6/readings
            errors:
              - field: readings.2.interval_start
                code: not_quarter_hour
                message: "interval_start must be on a quarter-hour boundary (UTC), received '2026-03-18T12:07:00Z'"
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/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.com/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: metering:write. Please create a new API key with the required scopes."
    RateLimited:
      description: Ratenbegrenzung überschritten
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/metering-points:
    get:
      operationId: listMeteringPoints
      summary: Messstellen auflisten
      description: "Die Messstellen des angemeldeten Teilnehmers auflisten. Messstellen entstehen im Anlagen-Onboarding oder beim Einrichten eines Lastgangs — die API legt sie nicht an.\n\nErforderlicher Scope: `metering:read`"
      tags:
        - Metering points
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:read
      parameters:
        - name: asset_id
          in: query
          description: Nach zugeordneter Anlage filtern
          schema:
            type: string
            example: ast_7p2q9r4s
        - name: direction
          in: query
          description: Nach konfigurierter Richtung filtern
          schema:
            type: string
            enum:
              - production
              - consumption
              - both
        - name: status
          in: query
          description: Nach Status der Messstelle filtern
          schema:
            type: string
            enum:
              - pending
              - active
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Messstellen
          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/MeteringPointList"
              example:
                metering_points:
                  - id: mp_e4f8a2c6
                    melo_id: DE0009900000000000000000000WEAN01
                    malo_id: "41770354291"
                    asset_id: ast_7p2q9r4s
                    asset_name: WEA Nord 1
                    direction: production
                    interval_minutes: 15
                    status: active
                    created_at: "2026-01-12T09: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/metering-points/{metering_point_id}:
    get:
      operationId: getMeteringPoint
      summary: Messstelle abrufen
      description: "Eine einzelne Messstelle über ihre Kennung abrufen.\n\nErforderlicher Scope: `metering:read`"
      tags:
        - Metering points
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:read
      parameters:
        - name: metering_point_id
          in: path
          required: true
          description: Kennung der Messstelle
          schema:
            type: string
            example: mp_e4f8a2c6
      responses:
        "200":
          description: Angaben zur Messstelle
          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/MeteringPoint"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/metering-points/{metering_point_id}/readings:
    post:
      operationId: createReadings
      summary: Messwerte hochladen
      description: "15-Minuten-Messwerte einer Messstelle in einer einzigen Anfrage hochladen. Die Zeitstempel sind ISO 8601 in UTC und müssen auf einer Viertelstundengrenze liegen; die Werte sind Dezimalzahlen in kWh. Ein Messwert, der ein bereits vorhandenes Intervall in derselben Richtung trifft, überschreibt den gespeicherten Wert. Der Stapel wird als Ganzes verarbeitet — scheitert ein Messwert an der Validierung, wird nichts geschrieben, und die Antwort führt die Feldfehler auf.\n\nÜber die API hochgeladene Messwerte sind Daten des Teilnehmers und dienen der Anzeige, dem Vergleich und der Planung. Sie ersetzen nicht die Lieferung des Messstellenbetreibers an OES, und granulare Zertifikate entstehen aus ihnen nicht.\n\nErforderlicher Scope: `metering:write`"
      tags:
        - Readings
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:write
      parameters:
        - name: metering_point_id
          in: path
          required: true
          description: Kennung der Messstelle
          schema:
            type: string
            example: mp_e4f8a2c6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReadingBatchRequest"
            example:
              readings:
                - interval_start: "2026-03-18T12:00:00Z"
                  value: 4356.742
                  direction: production
                  quality: uploaded
                - interval_start: "2026-03-18T12:15:00Z"
                  value: 4102.310
                  direction: production
                  quality: uploaded
                - interval_start: "2026-03-18T12:30:00Z"
                  value: 3541.955
                  direction: production
                  quality: uploaded
                - interval_start: "2026-03-18T12:45:00Z"
                  value: 4001.118
                  direction: production
                  quality: uploaded
      responses:
        "200":
          description: Ergebnis des Uploads
          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/ReadingBatchResult"
              example:
                metering_point_id: mp_e4f8a2c6
                accepted: 4
                replaced: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    get:
      operationId: listReadings
      summary: Messwerte auflisten
      description: "Die Messwerte einer Messstelle in einem Zeitfenster auflisten, aufsteigend nach interval_start sortiert. Alle Zeitstempel sind ISO 8601 in UTC; die Werte sind Dezimalzahlen in kWh.\n\nErforderlicher Scope: `metering:read`"
      tags:
        - Readings
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:read
      parameters:
        - name: metering_point_id
          in: path
          required: true
          description: Kennung der Messstelle
          schema:
            type: string
            example: mp_e4f8a2c6
        - $ref: "#/components/parameters/FromParam"
        - $ref: "#/components/parameters/ToParam"
        - name: direction
          in: query
          description: Nach Richtung des Energieflusses filtern
          schema:
            type: string
            enum:
              - production
              - consumption
        - name: quality
          in: query
          description: Nach Datenqualität filtern
          schema:
            type: string
            enum:
              - uploaded
              - forecast
              - estimated
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Messwerte
          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/ReadingList"
              example:
                readings:
                  - interval_start: "2026-03-18T12:00:00Z"
                    interval_end: "2026-03-18T12:15:00Z"
                    value: 4356.742
                    direction: production
                    quality: uploaded
                  - interval_start: "2026-03-18T12:15:00Z"
                    interval_end: "2026-03-18T12:30:00Z"
                    value: 4102.310
                    direction: production
                    quality: uploaded
                  - interval_start: "2026-03-18T12:30:00Z"
                    interval_end: "2026-03-18T12:45:00Z"
                    value: 3541.955
                    direction: production
                    quality: uploaded
                  - interval_start: "2026-03-18T12:45:00Z"
                    interval_end: "2026-03-18T13:00:00Z"
                    value: 4001.118
                    direction: production
                    quality: uploaded
                pagination:
                  limit: 10
                  has_more: false
                  next_cursor: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/metering-points/{metering_point_id}/imports:
    post:
      operationId: createImport
      summary: CSV-Import anlegen
      description: "Eine CSV-Datei mit Messwerten für eine Messstelle hochladen. Das Dateiformat — Spalten, zulässige Einheiten und Wertregeln eingeschlossen — folgt der Spezifikation der Lastgangdateien: semikolongetrennt, mit Kopfzeile, ein 15-Minuten-Intervall je Zeile, eine Messstelle je Datei.\n\nDie Verarbeitung läuft asynchron — die Antwort liefert den Import im Status `pending`; das Ergebnis fragen Sie über den Endpunkt zum Importstatus ab. Eine Datei wird vollständig importiert oder gar nicht.\n\nErforderlicher Scope: `metering:write`"
      tags:
        - Imports
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:write
      parameters:
        - name: metering_point_id
          in: path
          required: true
          description: Kennung der Messstelle
          schema:
            type: string
            example: mp_e4f8a2c6
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Die CSV-Datei (semikolongetrennt, mit Kopfzeile; im Zweifel UTF-8)
              required:
                - file
      responses:
        "200":
          description: Import zur Verarbeitung angenommen
          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/Import"
              example:
                id: imp_5b9d1c3a
                metering_point_id: mp_e4f8a2c6
                filename: wea-nord-1-2026-03-18.csv
                status: pending
                rows_total: null
                rows_imported: null
                created_at: "2026-03-19T06:30:00Z"
                completed_at: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/imports/{import_id}:
    get:
      operationId: getImport
      summary: Importstatus abrufen
      description: "Einen CSV-Import samt Verarbeitungsstatus abrufen. `completed` heißt, dass alle Zeilen geschrieben wurden; `failed` heißt, dass keine Zeile geschrieben wurde und `errors` die Gründe aufführt.\n\nErforderlicher Scope: `metering:read`"
      tags:
        - Imports
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - metering:read
      parameters:
        - name: import_id
          in: path
          required: true
          description: Kennung des Imports
          schema:
            type: string
            example: imp_5b9d1c3a
      responses:
        "200":
          description: Angaben zum Import
          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/Import"
              examples:
                completed:
                  summary: Abgeschlossener Import
                  value:
                    id: imp_5b9d1c3a
                    metering_point_id: mp_e4f8a2c6
                    filename: wea-nord-1-2026-03-18.csv
                    status: completed
                    rows_total: 96
                    rows_imported: 96
                    created_at: "2026-03-19T06:30:00Z"
                    completed_at: "2026-03-19T06:30:12Z"
                failed:
                  summary: Fehlgeschlagener Import (nichts geschrieben)
                  value:
                    id: imp_8a2c4e71
                    metering_point_id: mp_e4f8a2c6
                    filename: wea-nord-1-2026-03-19.csv
                    status: failed
                    rows_total: 96
                    rows_imported: 0
                    errors:
                      - row: 17
                        code: invalid_format
                        message: "Invalid time '25:15' — expected HH:MM"
                    created_at: "2026-03-20T06:30:00Z"
                    completed_at: "2026-03-20T06:30:09Z"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
