Backend-API — NB
Das Backend eines NB 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 NB
| Operation | Area | Call | German designation | Sources | Rules NB |
|---|---|---|---|---|---|
| Identification of the MaLo | MaloIdent NB (backend) | POST /identifyMarketlocation | /lesenMaloidentBasis | maco-api.yaml · maloident-netzbetreiber.json · doc.macoapp.de | — |
| Master data of the identified MaLo | MaloIdent NB (backend) | GET /getMaloidentMarketlocation | /lesenMaloidentMarktlokation | maco-api.yaml · maloident-netzbetreiber.json · doc.macoapp.de | — |
| Update process data | Process data NB (backend) | POST /prozessdaten/nb/update | — | maco-api.yaml · doc.macoapp.de | — |
| Create process data | Process data NB (backend) | POST /prozessdaten/nb/create | /erstellenProzessdaten | maco-api.yaml · macoapp-schreiben.json · doc.macoapp.de | — |
Identification of the MaLo
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 /lesenMaloidentBasis | LESEN_MALOIDENT_BASIS | maloident-netzbetreiber.json |
| delivered designation | POST /identifyMarketlocation | LESEN_MALOIDENT_BASIS | doc.macoapp.de |
| naming structured by role | POST /identifyMarketlocation | MALOIDENT_IDENTIFIZIERUNG_DER_MALO | maco-api.yaml |
Role: NB — established by doc.macoapp.de.
Request body: object
Response (200): object
Corresponds in doc.macoapp.de to: “Identification of the MaLo” in the branch “MaloIdent NB (backend)” (identifizierung-der-malo-14666443e0)
Master data of the identified MaLo
Reading the master data of the identified market location for the positive response using LocationId (Parameter1) at the point in time (Parameter2)
| What | Call | Command | Source |
|---|---|---|---|
| German designation | GET /lesenMaloidentMarktlokation | LESEN_MALOIDENT_MARKTLOKATION | maloident-netzbetreiber.json |
| delivered designation | GET /getMaloidentMarketlocation | LESEN_MALOIDENT_MARKTLOKATION | doc.macoapp.de |
| naming structured by role | GET /getMaloidentMarketlocation | MALOIDENT_STAMMDATEN_DER_IDENTIFIZ_MALO | maco-api.yaml |
Role: NB — established by doc.macoapp.de.
| Parameter | City | Mandatory | Meaning |
|---|---|---|---|
| parameter1 | query | yes | Location ID of the market location |
| parameter3 | query | yes | Date (key date) |
Response (200): Marktlokation
Corresponds in doc.macoapp.de to: “Master data of the identified MaLo” in the branch “MaloIdent NB (backend)” (stammdaten-der-identifiz-malo-14666444e0)
Update process data
| What | Call | Command | Source |
|---|---|---|---|
| delivered designation | POST /updateProcessData | AKTUALISIEREN_PROZESSDATEN | doc.macoapp.de |
| naming structured by role | POST /prozessdaten/nb/update | PROZESSDATEN_UPDATE_NB | maco-api.yaml |
Role: NB — 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 NB (backend)” (prozessdaten-aktualiseren-14666382e0)
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/nb/create | PROZESSDATEN_CREATE_NB | maco-api.yaml |
Role: NB — established by doc.macoapp.de and maco-api.yaml.
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 NB (backend)” (prozessdaten-erstellen-14666311e0)
Identical for all roles
No source calls these 32 operations role-bound — a NB provides them just like any other role. The last column counts at how many rules of the NB connector table they are actually called (format version 202604).
| Operation | Area | Call | German designation | Sources | Rules NB |
|---|---|---|---|---|---|
| Read remittance advice | BO4E read (backend) | GET /getAvisBasic | /lesenAvisBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 1 |
| Read calculation formula | BO4E read (backend) | GET /getCalculationFormulaBasic | /lesenBerechnungsformelBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| Read balancing | BO4E read (backend) | GET /getAccountingBasic | /lesenBilanzierungBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 25 |
| 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 | — |
| Read communication details of the service provider | BO4E read (backend) | GET /getCommunicationDataBasic | /lesenKommunikationsdatenBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 2 |
| Read the load curve of a location | BO4E read (backend) | GET /getEnergyAmountLoadCurve | /lesenEnergiemengeLastgang | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| 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 | 10 |
| Read market location | BO4E read (backend) | GET /getMarketLocationBasic | /lesenMarktlokationBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 101 |
| Read metering location | BO4E read (backend) | GET /getMeterLocationBasic | /lesenMesslokationBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 50 |
| 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 | 19 |
| 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 | 10 |
| Read technical resource | BO4E read (backend) | GET /getTechnicalResourceBasic | /lesenTechnischeRessourceBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 10 |
| Read tranche | BO4E read (backend) | GET /getTrancheBasic | /lesenTrancheBasis | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | 15 |
| 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 | 24 |
| Read the meter reading of a location | BO4E read (backend) | GET /getEnergyAmountMeterReading | /lesenEnergiemengeZaehlerstand | maco-api.yaml · macoapp-lesen.json · doc.macoapp.de | — |
| 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.
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.
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.