Cernion Energy Sharing Allocation API

openapi: 3.2.0
info:
  title: Cernion Energy Tools Energy Sharing Allocation API
  version: 0.99.22
  description: 'MicroService Agent System for Energy Markets - REST API with AI integration.


    CERNION_TOKEN: request at https://cernion.de/ or by email: dev@stromdao.com.


    For the public instance at https://api.cernion.de/, create your token at https://cernion.de/cet-token/.'
servers:
- url: https://api.cernion.de
  description: API Server
tags:
- name: Energy Sharing Allocation
  description: 'Deterministic 6-step Energy Sharing allocation engine (v0.16). Computes per-consumer 15-min allocation time-series (§ 12 StromNZV) for § 42c EnWG communities. Stufe A: synthetic forecast via mastr_generation_forecast. Stufe B: real iMSys metering data via inhouse CSV upload. KRITIS-compliant: time-series computed in RAM, only metadata persisted. Interimsprozess operative deadline: 01.06.2026 (§ 20b EnWG).'
paths:
  /api/energy-sharing-allocation/allocate:
    post:
      summary: Calculate 15-min Energy Sharing allocation time-series (§ 42c EnWG)
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_allocate
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Allocation metadata with per-consumer summaries. Time-series available via /download endpoint.
          content:
            application/json:
              example:
                success: true
                id: b2c3d4e5-...
                communityId: ES-2026-001
                dateFrom: '2026-06-01'
                dateTo: '2026-06-07'
                dataSource: forecast
                redispatchApplied: false
                warnings: []
                consumers:
                - maloId: DE0001234567890123456789012345678
                  name: Müller
                  sharePercent: 30
                  totalKWh: 37.62
                  peakKW: 0.84
                  zeroIntervals: 288
                  intervalCount: 672
                - maloId: DE0009876543210987654321098765432
                  name: Schmidt
                  sharePercent: 70
                  totalKWh: 87.78
                  peakKW: 1.96
                  zeroIntervals: 288
                  intervalCount: 672
                summary:
                  totalGenerationKWh: 125.4
                  totalRedispatchDeductionKWh: 0
                  totalNetGenerationKWh: 125.4
                  intervalCount: 672
                  durationMs: 6500
                consumptionStatus:
                - maloId: DE0001234567890123456789012345678
                  found: true
                  intervalCount: 672
                  totalKWh: 41.2
                - maloId: DE0009876543210987654321098765432
                  found: false
                  intervalCount: 0
                  totalKWh: null
        '202':
          description: REST/Gateway call accepted as async job. Poll /api/jobs/:jobId/status and /api/jobs/:jobId/result.
          content:
            application/json:
              example:
                success: true
                jobId: f8d2d8d4-4f22-4a0a-bec7-a9f05ad6b9e6
                status: queued
                statusUrl: /api/jobs/f8d2d8d4-4f22-4a0a-bec7-a9f05ad6b9e6/status
                resultUrl: /api/jobs/f8d2d8d4-4f22-4a0a-bec7-a9f05ad6b9e6/result
      description: 'Executes a deterministic allocation pipeline: input validation → generation time-series fetch (Stufe A: forecast / Stufe B: inhouse metering) → optional EDM consumption-data availability check (#281, includeConsumptionData) → redispatch deduction → allocation arithmetic → summary assembly → PouchDB persist. Returns metadata and per-consumer summaries. Full 15-min time-series is available for download via GET /energy-sharing/allocations/:id/download. Regulatory basis: § 42c EnWG, § 12 StromNZV (Viertelstundenwerte), § 20b EnWG Interimsprozess (operative deadline 01.06.2026). KRITIS constraint: raw generation data is never persisted — only metadata.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dateFrom
              - dateTo
              properties:
                communityId:
                  type: string
                  description: External community ID from VNB. Also used (#285) to resolve generators/consumers automatically from a persisted energy-sharing-community when neither array is provided inline — see generators/consumers below.
                  example: ES-2026-001
                validationReportId:
                  type: string
                  description: Optional v0.15 validation report UUID — skips redundant generator/consumer validation when set
                  example: a1b2c3d4-...
                supersedesAllocationId:
                  type: string
                  description: 'Korrekturlauf (#286): UUID of a prior allocation this run corrects/replaces (e.g. after measured data was corrected). The prior run is marked superseded (never deleted — full audit trail preserved) and linked to this run. Requires correctionReason. Omit for a normal, non-correction run (default behavior).'
                  example: b2c3d4e5-...
                correctionReason:
                  type: string
                  description: Required when supersedesAllocationId is set — never an unexplained correction.
                  example: Korrigierte Verbrauchsdaten für Müller (DE000...) nachgemeldet
                generators:
                  type: array
                  items:
                    type: object
                  description: Generator list with mastrNummer and sharePercent (must sum to 100). Optional (#285) when communityId resolves to a persisted community with active generator members for the requested period — required otherwise.
                  example:
                  - mastrNummer: SEE904837264953
                    sharePercent: 100
                consumers:
                  type: array
                  items:
                    type: object
                  description: Consumer list with maloId, sharePercent (must sum to 100), optional name. Optional (#285) when communityId resolves to a persisted community with active consumer members for the requested period — required otherwise.
                  example:
                  - maloId: DE0001234567890123456789012345678
                    sharePercent: 100
                    name: Whg. 1
                dateFrom:
                  type: string
                  description: Start date (inclusive), ISO-8601 date
                  example: '2026-06-01'
                dateTo:
                  type: string
                  description: End date (inclusive), ISO-8601 date
                  example: '2026-06-30'
                dataSource:
                  type: string
                  enum:
                  - forecast
                  - inhouse
                  default: forecast
                  description: 'Stufe A: synthetic forecast (default); Stufe B: real metering data from inhouse CSV upload'
                inhouseSourceId:
                  type: string
                  description: datasource-cache sourceId for Stufe B (required when dataSource=inhouse)
                  example: pv-generation-es-2026-001
                includeRedispatchDeduction:
                  type: boolean
                  default: true
                  description: Apply Redispatch 2.0 deductions (affected intervals → generation = 0)
                includeConsumptionData:
                  type: boolean
                  default: false
                  description: 'Opt-in (#281): look up each consumer''s EDM consumption timeseries (services/edm.service.js, OBIS 1-0:1.8.0) for the same date range. Does not change the allocation arithmetic — only reports per-consumer data availability via consumptionStatus[] and warnings[]. A consumer without a matching EDM timeseries is reported via ALLOC_CONSUMPTION_DATA_NOT_FOUND, never silently treated as zero.'
                gridOperatorId:
                  type: string
                  description: MaStR grid operator ID (SNB...) for redispatch context lookup
                  example: SNB935578300972
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              Solar community — forecast, 7 days:
                value:
                  communityId: ES-2026-001
                  generators:
                  - mastrNummer: SEE904837264953
                    sharePercent: 100
                  consumers:
                  - maloId: DE0001234567890123456789012345678
                    sharePercent: 30
                    name: Müller
                  - maloId: DE0009876543210987654321098765432
                    sharePercent: 70
                    name: Schmidt
                  dateFrom: '2026-06-01'
                  dateTo: '2026-06-07'
                  dataSource: forecast
                  includeRedispatchDeduction: true
                  gridOperatorId: SNB935578300972
              Inhouse metering data (Stufe B):
                value:
                  communityId: ES-2026-002
                  generators:
                  - mastrNummer: SEE904837264953
                    sharePercent: 100
                  consumers:
                  - maloId: DE0001234567890123456789012345678
                    sharePercent: 50
                    name: Haus A
                  - maloId: DE0009876543210987654321098765432
                    sharePercent: 50
                    name: Haus B
                  dateFrom: '2026-06-01'
                  dateTo: '2026-06-07'
                  dataSource: inhouse
                  inhouseSourceId: pv-generation-es-2026-002
                  includeRedispatchDeduction: false
  /api/energy-sharing-allocation/allocations:
    get:
      summary: List past Energy Sharing allocation records
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_list
      parameters:
      - name: communityId
        in: query
        schema:
          type: string
          example: ES-2026-001
        description: Filter by external community ID
      - name: includeDeleted
        in: query
        schema:
          type: boolean
          default: false
        description: Include soft-deleted records (for audit access)
      - name: includeSuperseded
        in: query
        schema:
          type: boolean
          default: false
        description: Include records that were superseded by a later Korrekturlauf (#286, for audit access)
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Maximum number of results
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          example: eyJvZmZzZXQiOjIwfQ==
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          example: 0
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Paginated list of allocation metadata summaries
          content:
            application/json:
              example:
                count: 1
                allocations:
                - id: '...'
                  communityId: ES-2026-001
                  dateFrom: '2026-06-01'
                  dateTo: '2026-06-07'
                  dataSource: forecast
                  redispatchApplied: false
                  createdAt: 2026-06-01T...
      description: 'Returns allocation metadata records stored in PouchDB, newest first. Soft-deleted records are excluded unless includeDeleted=true. Superseded records (replaced by a later Korrekturlauf, #286) are excluded unless includeSuperseded=true.'
  /api/energy-sharing-allocation/allocations/:id:
    get:
      summary: Get a specific Energy Sharing allocation record by ID
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: b2c3d4e5-...
        description: Allocation UUID
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Full allocation metadata document
        '404':
          description: Allocation not found
      description: Returns the full allocation metadata including per-consumer summaries, warnings, and pipeline metadata. Time-series must be re-fetched via /download.
    delete:
      summary: Soft-delete an Energy Sharing allocation record
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_remove
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Allocation UUID to soft-delete
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Soft-delete confirmed
        '404':
          description: Allocation not found
      description: 'Marks the allocation record as deleted (_deleted: true) without removing it from PouchDB. The record remains accessible for audit purposes via GET /allocations/:id?includeDeleted=true. EU AI Act Art. 12 compliance: deletion is non-destructive.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
  /api/energy-sharing-allocation/allocations/:id/download:
    get:
      summary: Download per-consumer allocation time-series as CSV (EDM-importable)
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_download
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: b2c3d4e5-f6a7-b8c9-d0e1-f2a3b4c5d6e7
        description: Allocation UUID
      - name: maloId
        in: query
        required: true
        schema:
          type: string
          example: DE0001234567890123456789012345678
        description: Consumer MaLo-ID to export
      - name: format
        in: query
        schema:
          type: string
          default: csv
        description: Output format (currently only "csv" supported)
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Semicolon-delimited CSV file, one row per 15-min interval
          content:
            text/csv: {}
        '404':
          description: Allocation not found or maloId not part of this allocation
      description: 'Re-computes the 15-min allocation time-series on demand and returns a semicolon-delimited CSV. One row per 15-min interval. Columns: timestamp;generation_kwh;redispatch_deduction_kwh;net_generation_kwh;allocation_kwh. KRITIS: time-series is never persisted — this endpoint re-runs the computation from stored metadata.'
  /api/energy-sharing-allocation/allocations/:id/billing-report:
    post:
      summary: 'Monthly billing report for an existing allocation (kWh → EUR, #284)'
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_billingReport
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: b2c3d4e5-f6a7-b8c9-d0e1-f2a3b4c5d6e7
        description: Allocation UUID
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Billing report (JSON) or semicolon-delimited CSV export
        '404':
          description: Allocation not found
      description: 'Replays the allocation, fetches each consumer''s EDM consumption timeseries, caps the quota-based allocation at actual consumption (#282), aggregates Restmenge/Überschuss per consumer (#283), and applies `tariffEurPerKWh` to produce a billing report. Only allocatedKWh (internal solar share actually used) is billed — remainderKWh (grid draw) is reported for transparency but never billed here. A consumer with no EDM consumption data for the period gets billingAmountEur: null, never a misleading €0.00.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tariffEurPerKWh
              properties:
                tariffEurPerKWh:
                  type: number
                  description: Internal price per kWh of allocated solar — required input, never a hardcoded default.
                  example: 0.25
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  tariffEurPerKWh: 0.25
  /api/energy-sharing-allocation/annual-billing-report:
    post:
      summary: Annual billing report — sums N monthly allocations per consumer (#284)
      tags:
      - Energy Sharing Allocation
      operationId: energy_sharing_allocation_annualBillingReport
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Annual billing report (JSON) or semicolon-delimited CSV export
        '404':
          description: One of the referenced allocations was not found
      description: Replays and bills each allocation in `allocationIds` (same logic as billingReport, one call per ID) using the same tariffEurPerKWh, then sums the results per consumer. A consumer missing data in some months is summed only over the months that have data — monthsWithData/monthsWithoutData/complete report the coverage transparently, never masking an incomplete year as a complete one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - allocationIds
              - tariffEurPerKWh
              properties:
                allocationIds:
                  type: array
                  items:
                    type: string
                  description: Allocation UUIDs to sum, typically 12 monthly runs.
                  example:
                  - alloc-jan
                  - alloc-feb
                tariffEurPerKWh:
                  type: number
                  example: 0.25
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  allocationIds:
                  - alloc-jan
                  - alloc-feb
                  tariffEurPerKWh: 0.25
components:
  parameters:
    TokenQuery:
      name: token
      in: query
      required: false
      schema:
        type: string
      description: Optional Cernion MCP token as URL query parameter. If provided, it overrides CERNION_TOKEN for this request. Prefer Authorization Bearer header in production to reduce token exposure in URLs/logs.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Optional Cernion MCP token. If not provided, falls back to CERNION_TOKEN from environment. Request token at https://cernion.de/ or by email: dev@stromdao.com.'