Energy Sharing Allocation

Calculate 15-min Energy Sharing allocation time-series (§ 42c EnWG)

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.

post/api/energy-sharing-allocation/allocate

Request

  • Base URL: https://api.cernion.de
  • URL: https://api.cernion.de/api/energy-sharing-allocation/allocate
  • Auth: none declared

Query parameters

tokenstring

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.

Request body

communityIdstring

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.

validationReportIdstring

Optional v0.15 validation report UUID — skips redundant generator/consumer validation when set

supersedesAllocationIdstring

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).

correctionReasonstring

Required when supersedesAllocationId is set — never an unexplained correction.

generatorsobject[]

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.

consumersobject[]

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.

dateFromstring required

Start date (inclusive), ISO-8601 date

dateTostring required

End date (inclusive), ISO-8601 date

dataSource'forecast' | 'inhouse'

Stufe A: synthetic forecast (default); Stufe B: real metering data from inhouse CSV upload

inhouseSourceIdstring

datasource-cache sourceId for Stufe B (required when dataSource=inhouse)

includeRedispatchDeductionboolean

Apply Redispatch 2.0 deductions (affected intervals → generation = 0)

includeConsumptionDataboolean

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.

gridOperatorIdstring

MaStR grid operator ID (SNB...) for redispatch context lookup

tokenstring

Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

Example request

{
  "communityId": "ES-2026-001",
  "validationReportId": "a1b2c3d4-...",
  "supersedesAllocationId": "b2c3d4e5-...",
  "correctionReason": "Korrigierte Verbrauchsdaten für Müller (DE000...) nachgemeldet",
  "generators": [
    {
      "mastrNummer": "SEE904837264953",
      "sharePercent": 100
    }
  ],
  "consumers": [
    {
      "maloId": "DE0001234567890123456789012345678",
      "sharePercent": 100,
      "name": "Whg. 1"
    }
  ],
  "dateFrom": "2026-06-01",
  "dateTo": "2026-06-30",
  "inhouseSourceId": "pv-generation-es-2026-001",
  "gridOperatorId": "SNB935578300972"
}

Response

Allocation metadata with per-consumer summaries. Time-series available via /download endpoint.

Changes

No recorded changes to this operation across all 2 revisions of this API.