---
title: "Calculate 15-min Energy Sharing allocation time-series (§ 42c EnWG)"
method: POST
path: "/api/energy-sharing-allocation/allocate"
tags: ["Energy Sharing Allocation"]
---

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

`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

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.

## Query parameters

- `token` string

## Request body

- object
  - `communityId` string: 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.
  - `validationReportId` string: Optional v0.15 validation report UUID — skips redundant generator/consumer validation when set
  - `supersedesAllocationId` string: 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).
  - `correctionReason` string: Required when supersedesAllocationId is set — never an unexplained correction.
  - `generators` object[]: 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.
  - `consumers` object[]: 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.
  - `dateFrom` string, required: Start date (inclusive), ISO-8601 date
  - `dateTo` string, required: End date (inclusive), ISO-8601 date
  - `dataSource` 'forecast' | 'inhouse': Stufe A: synthetic forecast (default); Stufe B: real metering data from inhouse CSV upload
  - `inhouseSourceId` string: datasource-cache sourceId for Stufe B (required when dataSource=inhouse)
  - `includeRedispatchDeduction` boolean: Apply Redispatch 2.0 deductions (affected intervals → generation = 0)
  - `includeConsumptionData` boolean: 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` string: MaStR grid operator ID (SNB...) for redispatch context lookup
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

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

## Other responses

- `202`: REST/Gateway call accepted as async job. Poll /api/jobs/:jobId/status and /api/jobs/:jobId/result.

---

[API](https://skmtc.dev/cernion/apis/cernion-energy-tools-api.md) · [All operations](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/revisions/cdb94473b538?raw)