Upgrade Datenabholung v31

Datenabholung v31 will be the only server-side supported version by ELSTER, as of 2025-06-09 2025-04-28.

General

ELSTER is changing the data retrieval processes. The adjustments must be implemented before 2025-06-09 2025-04-28. The old process got replaced by PostfachAnfrage and retrieval using a new library called Otto.

The change is extensive. The following will change for you:

• the response structure of the list of data packages that can be retrieved

• the number of results listed has been limited to 1.000 data packages

• the results are paginated, several requests may have to be sent to read the complete list

• the retrieval is carried out with a UUID (the confirmation is carried out unchanged with the ID used previously)

• the confirmation of the successful retrieval must be made within 24 hours of the retrieval (more in the ELSTER forum)

• on errors during retrieve or confirm HTTP status code 501 and data.status: error-elster-response is being returned

Data types

The change affects the retrieval of Assessment Data (BDÜ) , DIVA and Feedback.

Currently no relevant changes concerning VaSt retrieval process.

Endpoints

Endpoints list, retrieve/single and confirm/single of the above-mentioned data types are affected.

An optional parameter for the data retrieval version has been added (allowed: 19 and 31, currently default to: 19).

Example (with implicit default v19):

/v2/assessment-data/list

Example (with explicit default v19):

/v2/assessment-data/list/19

Example (with explicit v31):

/v2/assessment-data/list/31

List

The filter options have been extremely reduced. Targeted filtering is no longer offered. The only available filter options are: type, dateFrom, dateTill, lastDataId and max (see Postman).

The principle is now to collect and evaluate the complete list (including metadata).

The number of results in a response has been reduced to 1.000. Pagination has been introduced.

The structure of the response has changed significantly (see Postman).

The following path was previously read to get dataId for retrieval:

data.serverResponsePayload.Nutzdaten.Datenabholung
 .Anfrage.Id[]["@attributes"].id

Now it will be for the dataUuid:

data.serverResponsePayload.Nutzdaten.Datenabholung
 .PostfachAnfrageAntwort.DatenartBereitstellung.Bereitstellungen.Bereitstellung[].Datenpaket.ReferenzId

And for the dataId it will be:

data.serverResponsePayload.Nutzdaten.Datenabholung
 .PostfachAnfrageAntwort.DatenartBereitstellung.Bereitstellungen.Bereitstellung[]["@attributes"].id

The lastDataId is being made avaiable in the following path (if more than max results are available):

data.serverResponsePayload.Nutzdaten.Datenabholung
 .PostfachAnfrageAntwort["@attributes"].paginierungLetzteBestId

Retrieve

For retrieval you need the so-called Reference ID (dataUuid) instead of @attributes.id (dataId). For paths see List above.

Confirm

The confirmation must (mandatorily) be made within 24 hours after retrieval of the data pacakge (see note in chapter 5.3.1 of ElsterDatenabholung-V31.0.1.pdf) and ELSTER forum.

The confirmation is being performed unchanged with the dataId.