> For the complete documentation index, see [llms.txt](https://za.docs.rechtlogisch.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://za.docs.rechtlogisch.de/beta/general/upgrade-datenabholung-v31.md).

# Upgrade Datenabholung v31

{% hint style="danger" %}
Datenabholung v31 will be the only server-side supported version by ELSTER, as of **2025-06-09** ~~2025-04-28~~.
{% endhint %}

## 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](https://forum.elster.de/herstellerforum/forum/eric/daten%C3%BCbertragung-mit-eric/153628-datenabholung-v31-hinweis-bzgl-sperrung-bei-fehlender-postfachbestaetigung#post153834))
* 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`.

{% hint style="info" %}
Currently no relevant changes concerning VaSt retrieval process.
{% endhint %}

## 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 (currently allowed: `31` and therefore default).

Example (with implicit default v31):

```
/v2/assessment-data/list
```

Example (with explicit default v31):

```
/v2/assessment-data/list/31
```

Example (with explicit v19, deprecated):

```
/v2/assessment-data/list/19
```

### 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](/beta/api/postman.md)).

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](/beta/api/postman.md)).

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](#list) above.

### Confirm

{% hint style="warning" %}
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](/beta/retrieval.md)) and [ELSTER forum](https://forum.elster.de/herstellerforum/forum/eric/daten%C3%BCbertragung-mit-eric/153628-datenabholung-v31-hinweis-bzgl-sperrung-bei-fehlender-postfachbestaetigung#post153834).
{% endhint %}

The confirmation is being performed unchanged with the `dataId`.
