> ## Documentation Index
> Fetch the complete documentation index at: https://docs.energy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Zuordnungsermächtigung

> Permitting each DSO to let the supplier use the balance group

Running the balance group is not enough: before a supplier may assign a
market location to it, the **BKV must have permitted that** to the
location's Netzbetreiber. MaBiS (ch. 10.2) calls this the
**Zuordnungsermächtigung** — granted *je Zeitreihentyp, Bilanzierungsgebiet,
Bilanzkreis und Lieferant*, valid from a named date. It is required even
when BKV and supplier are the same legal entity, and without it the NB
rejects the supplier's registrations against exactly this check
(GPKE answer code: *"Zuordnungsermächtigung liegt nicht vor"*).

The bridge generates the message and hands it to the **MakoFlow AS4
gateway**, which routes it to the NB. It is a pure permission record —
no market locations, no volumes.

## The message

A fixed-shape UTILMD (AHB Strom ch. 13.5):

|                   | Activation                                                                                        | Deactivation                                    |
| ----------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Prüfidentifikator | **55071**                                                                                         | **55072**                                       |
| Effective date    | `DTM+158` Bilanzierungsbeginn                                                                     | `DTM+159` Bilanzierungsende                     |
| Deadline          | ≥ 1 WT before the first assignment; retroactive to the 1st of the current balancing month allowed | ≥ 5 WT ahead; only to the 1st of a month, 00:00 |

One Vorgang per Zeitreihentyp; each carries the Bilanzierungsgebiet (EIC),
the Bilanzkreis (EIC) and the supplier's MP-ID. Effective dates are
midnight Europe/Berlin, expressed on the wire in UTC as the AHB requires.

## Sending one

The console has a **Zuordnungsermächtigung panel**: pick the Netzbetreiber
(type-to-filter over the official BDEW list, 998 active entries), its
Bilanzierungsgebiet, the Zeitreihentypen (LGS and EGS pre-selected — the
value-based pair), the effective date, then *Vorschau* shows the exact
EDIFACT and *Senden* delivers it after a confirmation. The dropdown data
ships with the service and is regenerated from the published workbook via
`scripts/zuordnung_targets.py --emit-registry`.

The same works over the API. Preview first — the endpoint renders the exact interchange without sending
anything, so the first message to each NB can be read by a human:

```bash theme={null}
curl -X POST "$BASE/v1/process/zuordnungsermaechtigungen/preview" \
  -H "X-API-Key: $PROCESS_KEY" -H "Content-Type: application/json" \
  -d '{
    "receiver_mp_id": "9900987654321",
    "bilanzierungsgebiet_eic": "11YN10000762---6",
    "zeitreihentypen": ["<ZRT code>"],
    "valid_from": "2026-10-01"
  }'
```

The same body on `POST /v1/process/zuordnungsermaechtigungen` builds the
message, delivers it through MakoFlow, appends a `zuordnung_sent` event and
stores the exact interchange in the audit trail under the effective day.
`action: "deactivate"` produces the 55072 counterpart; a deactivation to a
date that is not the 1st of a month is refused.

`bilanzkreis_eic` and `lieferant_mp_id` may be omitted — they default to
the configured balance group of the home control area and the configured
supplier.

## Configuration

| Variable                                  | Meaning                                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BKV_MP_ID`                               | Our MP-ID as BKV — the sender of the message                                                                                                             |
| `LIEFERANT_MP_ID`                         | Default supplier MP-ID being permitted                                                                                                                   |
| `MP_ID_CODE_LIST`                         | `BDEW` (default) or `GLN`. UNB and NAD use different qualifiers for the same list (500/14 vs 293/9); the builder handles both ends                       |
| `UTILMD_VERSION`                          | `S2.1` today; becomes `S2.2` with the 2026-10 market release                                                                                             |
| `MAKOFLOW_BASE_URL`                       | `https://api.makosoftware.de`                                                                                                                            |
| `MAKOFLOW_TOKEN`                          | A long-lived API token, if MakoFlow issued one — used as `Authorization: Bearer` directly and preferred when set                                         |
| `MAKOFLOW_USERNAME` / `MAKOFLOW_PASSWORD` | Alternative: the login flow from the published spec. The API rotates the session token per request; the bridge logs in per send and follows the rotation |

All of these are settable from the console like the other partner
credentials.

## Verification

MakoFlow answering `200` means the gateway **accepted** the message, not
that the NB did. The NB's answer arrives as CONTRL (syntax) and APERAK
(application) messages in MakoFlow — check *received messages* there, or
its `GET /edifact/sent-messages` API. A rejected Ermächtigung surfaces
later as the NB refusing the supplier's registrations, which is the
expensive way to find out.

<Note>
  The generated message is pinned by tests to the AHB segment table —
  qualifiers, timezone rules and the UNB/NAD code-list split included. What
  is **not** yet proven is a live round trip against a real NB; the first
  send should be watched through MakoFlow's portal until the CONTRL comes
  back clean.
</Note>