# Backend-API — LF

Das Backend eines LF bedient zwei Gruppen von Aufrufen. Die erste gilt nur für diese Rolle; die zweite ist für LF, NB und MSB wortgleich dieselbe.

## Only for LF

| Operation | Area | Call | German designation | Sources | Rules LF |
|---|---|---|---|---|---|
| Identification of a market location | MaloIdent LF (backend) | `POST /inbound` | `/core/inbound` | maco-api.yaml · maloident-macoapp.json · doc.macoapp.de | — |
| Update process data | MaloIdent LF (backend) | `POST /updateProcessData` | — | maco-api.yaml · doc.macoapp.de | — |
| Update process data | Process data LF (backend) | `POST /prozessdaten/lf/update` | — | maco-api.yaml · doc.macoapp.de | — |
| Create process data | Process data LF (backend) | `POST /prozessdaten/lf/create` | `/erstellenProzessdaten` | maco-api.yaml · macoapp-schreiben.json · doc.macoapp.de | — |

### Identification of a market location

Triggers the MaloIdent APP to send a MaloIdent request to the grid operator via the API web service. The request is identified by the event name **START_MALOIDENT**. In addition, a unique ID **prozessId** from the backend must be passed along, by which the later response from the grid operator can be handed back to the backend.

| What | Call | Command | Source |
|---|---|---|---|
| German designation | `POST /core/inbound` | `START_MALOIDENT` | `maloident-macoapp.json` |
| delivered designation | `POST /inbound` | `START_MALOIDENT` | `doc.macoapp.de` |
| naming structured by role | `POST /inbound` | `MALOIDENT_IDENTIFIKATION_EINER_MARKTLOKATION` | `maco-api.yaml` |

**Role:** LF — established by doc.macoapp.de.

**Request body:** `object`

**Response (200):** `object`

*Corresponds in doc.macoapp.de to:* “Identification of a market location” in the branch “MaloIdent LF (backend)” (`identifikation-einer-marktlokation-16024919e0`)

### Update process data

| What | Call | Command | Source |
|---|---|---|---|
| delivered designation | `POST /updateProcessData` | `AKTUALISIEREN_PROZESSDATEN` | `doc.macoapp.de` |
| naming structured by role | `POST /updateProcessData` | `MALOIDENT_PROZESSDATEN_AKTUALISIEREN` | `maco-api.yaml` |

**Role:** LF — established by doc.macoapp.de.

**Request body:** `object`

**Response (200):** `object`

*Corresponds in doc.macoapp.de to:* “Update process data” in the branch “MaloIdent LF (backend)” (`prozessdaten-aktualisieren-15106071e0`)

### Update process data

| What | Call | Command | Source |
|---|---|---|---|
| delivered designation | `POST /updateProcessData` | `AKTUALISIEREN_PROZESSDATEN` | `doc.macoapp.de` |
| naming structured by role | `POST /prozessdaten/lf/update` | `PROZESSDATEN_UPDATE_LF` | `maco-api.yaml` |

**Role:** LF — established by doc.macoapp.de and maco-api.yaml.

**Request body:** `ProcessData`

**Response (200):** `object`

*Corresponds in doc.macoapp.de to:* “Update process data” in the branch “Process data LF (backend)” (`prozessdaten-aktualiseren-14017182e0`)

### Create process data

Posting of data from market processes in the backend

| What | Call | Command | Source |
|---|---|---|---|
| German designation | `POST /erstellenProzessdaten` | `ERSTELLEN_PROZESSDATEN` | `macoapp-schreiben.json` |
| delivered designation | `POST /createProcessData` | `ERSTELLEN_PROZESSDATEN` | `doc.macoapp.de` |
| naming structured by role | `POST /prozessdaten/lf/create` | `PROZESSDATEN_CREATE_LF` | `maco-api.yaml` |

**Role:** LF — established by doc.macoapp.de and maco-api.yaml.

:::note{title="Three names for one call"}

The three sources name this call differently. Binding for the BPMN diagrams of this documentation is the German name: the diagrams are labelled with it.

:::

**Request body:** `ProcessData`

**Response (200):** `object`

*Corresponds in doc.macoapp.de to:* “Create process data” in the branch “Process data LF (backend)” (`prozessdaten-erstellen-14017183e0`)

## Identical for all roles

No source calls these 32 operations role-bound — a LF provides them just like any other role. The last column counts at how many rules of the LF connector table they are actually called (format version 202604).

| Operation | Area | Call | German designation | Sources | Rules LF |
|---|---|---|---|---|---|
| Read remittance advice | BO4E read (backend) | `GET /getAvisBasic` | `/lesenAvisBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read calculation formula | BO4E read (backend) | `GET /getCalculationFormulaBasic` | `/lesenBerechnungsformelBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 1 |
| Read balancing | BO4E read (backend) | `GET /getAccountingBasic` | `/lesenBilanzierungBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 13 |
| Read energy supply contract | BO4E read (backend) | `GET /getEnergySupplyContractBasic` | `/lesenEnergieliefervertragBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read energy quantities from billing context | BO4E read (backend) | `GET /getEnergyAmount` | `/lesenEnergiemengeEnergiemenge` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 2 |
| Read communication details of the service provider | BO4E read (backend) | `GET /getCommunicationDataBasic` | `/lesenKommunikationsdatenBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read the load curve of a location | BO4E read (backend) | `GET /getEnergyAmountLoadCurve` | `/lesenEnergiemengeLastgang` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 2 |
| Read power curve definition | BO4E read (backend) | `GET /getDefinitionPerformance` | — | doc.macoapp.de | — |
| Read location bundle | BO4E read (backend) | `GET /getLocationBundleBasic` | `/lesenLokationsbundBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 2 |
| Read market location | BO4E read (backend) | `GET /getMarketLocationBasic` | `/lesenMarktlokationBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 65 |
| Read metering location | BO4E read (backend) | `GET /getMeterLocationBasic` | `/lesenMesslokationBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 18 |
| Read metering point operation contract | BO4E read (backend) | `GET /getMeasuringPointOperationContractBasic` | `/lesenMessstellenbetriebsvertragBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read grid location | BO4E read (backend) | `GET /getGridLocationBasic` | `/lesenNetzlokationBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 15 |
| Read grid usage contract | BO4E read (backend) | `GET /getGridUsageContractBasic` | `/lesenNetznutzungsvertragBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read price sheet | BO4E read (backend) | `GET /getPriceSheetBasic` | — | maco-api.yaml · doc.macoapp.de | 1 |
| Read switching time definition | BO4E read (backend) | `GET /getDefinitionSwitch` | — | doc.macoapp.de | — |
| Read controllable resource | BO4E read (backend) | `GET /getControllableResourceBasic` | `/lesenSteuerbareRessourceBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 4 |
| Read technical resource | BO4E read (backend) | `GET /getTechnicalResourceBasic` | `/lesenTechnischeRessourceBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 3 |
| Read tranche | BO4E read (backend) | `GET /getTrancheBasic` | `/lesenTrancheBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 12 |
| Read metering time definition | BO4E read (backend) | `GET /getDefinitionCounting` | — | doc.macoapp.de | — |
| Read meter | BO4E read (backend) | `GET /getCounterBasic` | `/lesenZaehlerBasis` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 14 |
| Read the meter reading of a location | BO4E read (backend) | `GET /getEnergyAmountMeterReading` | `/lesenEnergiemengeZaehlerstand` | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 2 |
| Receipt of a market message | MCS receipt | `POST /receive` | — | maco-api.yaml | — |
| Read sender data | Obsolete | `GET /lesenMarktteilnehmerAbsender` | `/lesenMarktteilnehmerAbsender` | maco-api.yaml · macoapp-lesen.json | — |
| Read recipient data | Obsolete | `GET /lesenMarktteilnehmerEmpfaenger` | `/lesenMarktteilnehmerEmpfaenger` | maco-api.yaml · macoapp-lesen.json | — |
| Determine the usage period of a market location | Obsolete | `GET /getMarketlokationAllocationPeriod` | — | maco-api.yaml | — |
| Read allocation authorization (UNKNOWN) | Process data | `POST /prozessdaten/unknown/update` | — | maco-api.yaml | — |
| Read allocation authorization | Read process data (backend) | `GET /getAllocationAuthorization` | — | doc.macoapp.de | — |
| LESEN_MARKTLOKATION_VERWENDUNGSZEITRAUM | only macoapp-lesen.json | `GET /lesenMarktlokationVerwendungszeitraum` | `/lesenMarktlokationVerwendungszeitraum` | macoapp-lesen.json | — |
| AKTUALISIEREN_MDOC_BASIS | only macoapp-schreiben.json | `POST /aktualisierenMdocBasis` | `/aktualisierenMdocBasis` | macoapp-schreiben.json | — |
| ERSTELLEN_PROZESSDATEN_MALOIDENTANTWORT_NEGATIV | only maloident-lieferant.json | `POST /erstellenProzessdatenMaloidentantwortNegativ` | `/erstellenProzessdatenMaloidentantwortNegativ` | maloident-lieferant.json | — |
| ERSTELLEN_PROZESSDATEN_MALOIDENTANTWORT_POSITIV | only maloident-lieferant.json | `POST /erstellenProzessdatenMaloidentantwortPositiv` | `/erstellenProzessdatenMaloidentantwortPositiv` | maloident-lieferant.json | — |

## Errors and retry

The sixth of the questions that these pages have triggered: what happens when your backend answers a callback with an error.

### What your backend responds

The specification knows exactly three responses, and it knows them for `createProcessData` and `updateProcessData` alike — measured across all three roles and both format versions:

| Code | Meaning | Body |
|---|---|---|
| `200` | accepted | **none** — “200 ok” means no body |
| `400` | the request is invalid | `ProblemDetails` according to RFC 9457 |
| `422` | the request is understood but cannot be processed for business reasons | `ProblemDetails` according to RFC 9457 |

All 24 error responses of the six catalogs carry `ProblemDetails`; the media type remains `application/json`.

### Whether the MACO repeats APP

**Not when writing to the backend.** Measured on 05.09.2026 against the wiring of the connector flow: only the **transport error** (connection not established, timeout) leads into the retry there, and at most three times. A **5xx** and a **4xx** response go into error handling without a retry.

:::caution{title="Here the measurement differs from the verbal information"}

Information from operations: “three retries on 5xx”. According to this measurement this applies to the **reading** call into the backend — there the 5xx response explicitly runs into the same retry as the transport error, three times as well. For the **writing** call, that is for `createProcessData` and `updateProcessData`, it does not.

The reading flow is at the same time the counter-check: the same evaluation finds the repetition relationship there, so the absence in the writing flow is a measured difference and not a blind probe.

**Anyone relying on a retry is planning for one that does not exist here.** Until this has been cross-checked against the running instance, the measurement stands.

:::

### What happens instead

What an error triggers is configured **per check identifier and per interface**. The decision is recorded in the connector table `S_NACHRICHTEN_KONNEKTOR` of the process repositories, in the column „Behaviour if error from API“.

| Value | Effect | How often it is actually set |
|---|---|---|
| `IGNORIEREN` | the process continues | 9 837 rules |
| `AUFGABE-SB` | a task for clerical processing is created | 3 364 rules |
| `AUFGABE-PC` | a task for process control is created | 25 rules |
| `ABBRECHEN` | the process aborts | **0 rules** — the value is permitted and is not used anywhere |

Measured across the 15 connector tables of the three roles and all versions. That `ABBRECHEN` appears in the value list therefore only says that it would be possible; it is set on not a single rule. Whatever is not ignored becomes a **task**.

The task appears in the **Klaerfallmonitor** of the user interface (`/clearcaseMonitorOpen`, group “Sachbearbeitung”), where a human decides on it — repeat, abort or finish. The abort is therefore a case handler's choice inside the task and not a default of the table.

:::note{title="Visibility of the error response"}

The error response is visible on the transaction. Information from operations, not verified against the running instance. The link to the transaction is described under [Keys and mapping](/en/schnittstellen/schluessel).

:::