Upgrade Datenabholung v31

Allgemein

ELSTER stellt die Datenabholungsprozesse um. Die Anpassungen müssen vor dem 09.06.2025 28.04.2025 umgesetzt werden. Der alte Prozess wird durch eine PostfachAnfrage und Abholung mittels einer neuer Bibliothek Otto ersetzt.

Die Umstellung ist umfangreich. Für Sie ändert sich:

• die Response-Struktur der Auflistung von abholbaren Protokollen

• die Anzahl der aufgelisteten Ergebnisse wurde auf 1.000 Protokolle beschränkt

• die Ergebnisse werden paginiert, ggf. müssen mehrere Requests gesendet werden um die vollständige Liste auszulesen

• die Abholung erfolgt mit einer UUID (die Bestätigung erfolgt unverändert mit der bisher verwendeten ID)

• die Bestätigung der Abholung muss innerhalb von 24 Stunden nach Abholung erfolgen (mehr im ELSTER-Forum)

• bei Fehlern während der Bestätigung wird HTTP Status Code 501 und data.status: error-server-response zurückgegeben

Datenarten

Betroffen von der Umstellung ist die Abholung der Protokolle für LStB und ELO2.

Endpunkte

Betroffen sind Endpunkten list-available-data, single-data-retrieve und single-data-confirm der o. g. Datenarten

Für den Preview wurde ein optionaler Parameter für die Datenabholungsversion hinzugefügt (default ab deric 2.25.0: 31, erlaubt: 19 und 31).

Beispiel (mit Defaultwert für Datenabholung v31):

/v1/lstb/list-available-data

Beispiel (mit expliziter Nennung der Version für Datenabholung v31):

/v1/lstb/list-available-data/31

Beispiel bisher für Datenabholung v19:

/v1/lstb/list-available-data/19

List

Die Filtermöglichkeiten wurden extrem reduziert. Eine gezielte Filterung wird nicht mehr angeboten. Die verfügbaren Filtermöglichkeiten sind nur noch: type, from, till, lastDataId und max (s. Postman).

Das Prinzip ist nun die vollständige Liste abzuholen und auszuwerten (inkl. Metadaten).

Die Anzahl der Ergebnisse in einer Response wurde auf 1.000 reduziert. Es wurde eine Paginierung eingeführt.

Die Struktur der Response hat sich wesentlich geändert (s. Postman).

Für die Abholung wurde bisher der folgende Pfad für dataId ausgelesen:

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

Nun wird es für die dataUuid sein:

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

Und für die dataId nun:

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

Die lastDataId wird (falls mehr als max Ergebnisse verfügbar) im Pfad ausgegeben:

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

Retrieve

Für die Abholung benötigt man die sog. ReferenzId (dataUuid), statt der @attributes.id (dataId). Für Pfade s. oben List.

Confirm

Die Bestätigung muss (zwingend) innerhalb von 24 Std. nach Abholung des Protokolls erfolgen (vgl. Hinweis in Kapitel 5.3.1 von ElsterDatenabholung-V31.0.1.pdf) und ELSTER-Forum.

Die Bestätigung erfolgt unverändert mit der dataId.

Ggf. ändert sich für Fehlerfälle der HTTP Status Code und der Typ der Fehlermeldung. Momentan wird empfohlen den Pfad: data.serverResponsePayload.Nutzdaten.Datenabholung.PostfachBestaetigungAntwort.Bereitstellungen.Bereitstellung[].Rueckgabe.Code != "0" auf Fehlerfälle zu prüfen. "0" bedeutet ohne Fehler.

Mehr Informationen zum ELSTER-Server Bug bei Bestätigung von unbekannten IDs vgl. ELSTER-Forum.