Migration-Guide

FIT-Connect hat ein Major Update bekommen und damit stehen die Submission API, Destination API, Routing API und das Metadatenschema in Version 2.0.0 zur Verfügung. Anbindungen können ab sofort auf diese neuen Versionen umgestellt werden. Die 1.x.x-Versionen sind hiermit abgekündigt und werden nur noch ein Jahr zur Verfügung stehen.

Hinweis

Anbindungen müssen innerhalb eines Jahres auf die neuen Versionen umgestellt werden, da sonst bereits bestehende Integrationen nicht mehr funktionieren werden.

Die nachfolgende Anleitung beschreibt die Migration von FIT-Connect Version 1.x.x auf 2.0.0.

Änderungen, die jede bestehende Anbindung betreffen

Submissions ohne Fachdaten

Es ist nicht mehr möglich, Einreichungen (Submissions) ohne Fachdaten zu versenden. Technisch formuliert bedeutet dies, dass das Feld encryptedData des PUT /v2/submissions/{submissionId}-Endpunkts nun verpflichtend ist. Für Fachverfahren ist zu beachten, dass Onlinedienste immer noch Submissions ohne Fachdaten an bestehende Anbindungen senden können, solange diese noch nicht auf die v2-API umgestellt haben.

Webhooks

In den new-events und new-submissions-Webhooks der Submission API wurde das submissionIds-Array als deprecated und optional markiert. Zum jetzigen Zeitpunkt gibt es aber noch keine Änderungen im Verhalten. Implementierungen müssen aber dennoch bereits jetzt dahingehend umgestellt werden, dass Sie das Array submissionIds nicht mehr verarbeiten und stattdessen auf submissions.submissionId zurückgreifen. Dies ist notwendig, da in einem Jahr die Webhooks ohne das genannte Feld versendet werden.

Das forward-submission-Event

Events vom Typ forward-submission werden nicht mehr akzeptiert und können über die Submission API v2 nicht mehr ausgelöst werden. Kommunikationspartner können aberweiterhin solche Events erzeugen, solange diese noch v1-Endpunkte verwenden. Dies ist noch für ein Jahr lang möglich. Ebenso können sich weiterhin historische forward-submission-Events in Event-Logs befinden.

Metadaten

Fachverfahren sollten das Metadatenschema in Version 2.0.0 technisch unterstützen und danach im Self-Service-Portal diese Unterstützung eintragen. Onlinedienste sollten bei entsprechender Indikation der Destination diese neue Version für ihre Einreichungen verwenden, da Metadatenschemata älterer Versionen ebenso als abgekündigt gelten. Davon abgesehen bietet das Metadatenschema 2.0.0 auch inhaltliche Erweiterungen und Vorteile.

Das Metadatenschema wurde modularisiert. Das bedeutet, dass das authenticationInformation-Objekt vollständig entfernt wurde und das additionalReferenceInfo-Objekt keine beliebigen zusätzlichen Felder mehr erlaubt. Stattdessen wurde auf Wurzelebene ein dataSets-Array hinzugefügt. Dieses Array ermöglicht es, je nach Art der Einreichung, auf beliebige (Sub-)Schemata anhand ihrer URL zu verweisen. So kann zum Beispiel das Schema https://raw.githubusercontent.com/Governikus/IdentificationReport/2.0.0/schema/identification-report.json verwendet werden, um die Informationen aus dem vormaligen authenticationInformation-Objekt zu übermitteln. Generell ist die Frage, welche (Sub-)schemata verwendet werden sollen, eine bilaterale Absprache zwischen zwei Kommunikationspartnern. Für die abgesprochenen Schemata sollten dann die entsprechenden versionierten Schema-Dateien auf dem System lokal vorgehalten werden und den URLs zugeordnet sein. Ein dynamisches Nachladen von beliebigen Dateien aus dem Web ist nicht empfohlen.

Außerdem wurde das Feld publicServiceType entfernt. Die Verwaltungsleistung ist bereits seit längerem Teil der Klardaten einer Submission und soll hier nicht mehr redundant spezifiziert werden.

Eine Angabe von contentStructure.data ist nun verpflichtend. Diese Änderung steht in Einklang mit der Entscheidung, Submissions ohne Fachdaten nicht mehr zuzulassen.

Ein boolean-Feld additionalReferenceInfo.zustimmungZumDigitalenBescheid wurde hinzugefügt, um die Zustimmung des Antragsstellers zur elektronischen Bescheidzustellung standardisiert übermitteln zu können.

Ein optionales Feld author wurde auf Wurzelebene hinzugefügt. Mit diesem Feld kann ein absendendes System eine Selbstauskunft geben, die bei der Nachverfolgbarkeit von Fehlern hilfreich sein kann. Es wird empfohlen, hier Werte zu setzen.

Das Feld replyChannel.fink.finkPostfachRef erfordert nun mindestens ein Zeichen, um Verwirrungen frühzeitig vorzubeugen.

Das $schema-Feld ist nun verpflichtend.

Entfernung von destinationParameters aus der Routing API

Aus dem /routes-Endpunkt der Routing API wurden die Felder routes.destinationParameters und routes.destinationParametersSignature entfernt. In den 3.x.x-Versionen der SDKs finden sich die Felder ebenfalls nicht mehr an den entsprechenden Objekten. Die vormals hier enthaltenen Informationen können über die Submission API über GET /destinations/{destinationId} bezogen werden.

Änderungen für Anbindungen mit dem Java SDK

Mit dem Major Release FIT-Connect 2.0.0 wurden sämtliche API-Endpunkte auf die neue Version /v2 umgestellt. Das Java SDK wurde entsprechend angepasst. Damit unterstützt das JAVA SDK nun auch vollständig die neuen FIT-Connect Strukturen und Metadatenmodelle.

Die wichtigste Änderung betrifft die API-Versionierung. Alle relevanten Endpunkte, insbesondere die für Submission, Destination und Routing, verwenden nun die neue Version /v2. Bestehende Methodenaufrufe bleiben weiterhin nutzbar, sofern die aktuelle SDK-Version eingebunden ist. Eine Aktualisierung auf die Version 2.0.0 ist daher erforderlich, um volle Kompatibilität mit der neuen Infrastruktur zu gewährleisten.

Das Java SDK arbeitet nun vollständig mit dem Metadatenschema 2.x. Dieses Schema bildet die Grundlage für eine einheitliche und standardisierte Übertragung von Antragsdaten. Das Schema ist abwärtskompatibel, erfordert jedoch bei der Validierung und Verarbeitung von Metadaten gegebenenfalls kleinere Anpassungen in den referenzierten Schema-URIs.

Ein weiterer Schwerpunkt liegt auf der sicheren Zertifikatsverwaltung. Das SDK unterstützt die neuen FIT-Connect Sicherheitsmechanismen, insbesondere die Verwendung von JSON Web Keys (JWK) und verschlüsselten Schlüsselcontainern. Dadurch wird die Sicherheit der Datenübertragung weiter erhöht.

Zusätzlich wurden Verbesserungen an der Fehlerbehandlung vorgenommen. Exception-Typen wurden vereinheitlicht und um eindeutige Statuscodes ergänzt, um die technische Analyse im Fehlerfall zu erleichtern und die Integration in bestehende Monitoring-Systeme zu verbessern.

Die Version 3.x des JavaSDKs führt Breaking Changes ein die die folgenden Code-Updates erfordern.

1. Klassenumbenennungen

Alte Klasse	Neue Klasse	Package
ServiceType	PublicService	dev.fitko.fitconnect.api.domain.model.submission
StatusEnum	Status	dev.fitko.fitconnect.api.domain.model.destination
DestinationService	Service	dev.fitko.fitconnect.api.domain.model.destination

2. Eigenschaftsumbenennungen

Klasse	Alte Eigenschaft	Neue Eigenschaft
Submission	serviceType	publicService
AnnounceSubmission	serviceType	publicService

3. Entfernte Methoden

Die folgenden Methoden wurden vollständig entfernt:

Attachment.fromString(String content, String mimeType)
Attachment.fromString(String content, String mimeType, String fileName, String description)

4. Collection-Typ-Änderungen

Klasse	Eigenschaft	Alter Typ	Neuer Typ
SubmissionsForPickup	submissions	Set<SubmissionForPickup>	List<SubmissionForPickup>

5. Entfernte Felder

Klasse	Entferntes Feld
Submission	callback
Route	destinationParameters
Route	destinationParametersSignature

Weitere Informationen und Hinweise zur Integration finden Sie auf der Seite zum Java SDK.

Änderungen für Anbindungen mit dem .NET SDK

Mit der Veröffentlichung des FIT-Connect .NET SDK 3.0.0 am 27. Oktober 2025 wurde die Kompatibilität mit der FIT-Connect API Version 2.0 eingeführt. Diese Veröffentlichung ist Teil des ersten jährlichen Major Releases und bildet den Grundstein für die zukünftige Weiterentwicklung und Vereinheitlichung der API-Strukturen.

Das Update umfasst eine vollständige Migration aller API-Endpunkte auf die Version /v2. Dazu gehören insbesondere die Schnittstellen für Submission, Destination und Routing. Diese Migration wird durch die aktualisierten SDK-Clients automatisch umgesetzt. Entwickler:innen müssen daher keine manuellen Anpassungen im Anwendungscode vornehmen, da die Umstellung von den neuen Clients vollständig abgedeckt wird.

Ein wichtiger Bestandteil dieses Releases ist die Anpassung von Klassen und Eigenschaften. Das bisherige Property serviceType wurde in den Klassen Submission, AnnounceSubmission, SendableSubmission und SendableEncryptedSubmission in publicService umbenannt. Darüber hinaus wurde der Datentyp der Sammlung SubmissionsForPickup.submissions von Set<SubmissionForPickup> in List<SubmissionForPickup> geändert, um eine bessere Kompatibilität und eine konsistentere Verarbeitung zu ermöglichen.

Im Rahmen der Bereinigung wurden zudem nicht mehr benötigte Funktionen entfernt. Dazu zählen die callback-Property in der Klasse Submission sowie sämtliche Methoden Attachment.fromString(...), die bereits in der Version 2.x als veraltet gekennzeichnet waren. Diese Änderungen verbessern die Übersichtlichkeit des SDKs und reduzieren potenzielle Fehlerquellen.

Das Update führt außerdem eine erneute Validierung auf Basis von URN-Schemata ein, um eine verbesserte Datenkonformität sicherzustellen. Gleichzeitig wurden verschiedene Abhängigkeiten aktualisiert, darunter Testcontainers-dotnet auf Version 4.8.1 und WireMock.Net auf Version 1.15.0, wodurch Stabilität und Testabdeckung weiter verbessert wurden.

Für die Nutzung des SDKs ist es erforderlich, auf die Version 3.0.0 zu aktualisieren. Im Anschluss sollten Entwickler:innen prüfen, ob in ihren Anwendungen veraltete Methoden wie Attachment.fromString verwendet werden, und gegebenenfalls Anpassungen vornehmen. Ebenso sollte ein Testlauf in der FIT-Connect-Testumgebung durchgeführt werden, um die reibungslose Kommunikation mit den /v2-Endpunkten sicherzustellen. Optional kann auch überprüft werden, ob die neue Property publicService korrekt genutzt wird.

Weitere Informationen und technische Details finden Sie im Changelog des .NET SDKs.

Änderungen für Anbindungen ohne SDK

Basis-URLs und Pfade

Für API-Requests sind die Basis-URLs, die auf der Seite Betriebs-Umgebungen der FIT-Connect Infrastruktur beschrieben sind zu verwenden. (Die v1-API ist derzeit noch auf einigen bereits abgekündigten Domains wie submission-api-prod.fit-connect.niedersachsen.de verfügbar, aber die v2-APIs werden auf diesen Domains nicht zur Verfügung gestellt.) Zu beachten ist auch, dass alle Request-Pfade nun /v2 beinhalten, wie in den API-Specs beschrieben. Ein valider Request-Pfad, um in der produktiven Umgebung Submissions abzuholen, wäre also https://prod.fit-connect.fitko.net/submission-api/v2/submissions.

In den v2-APIs sind alle Request-Pfade grundsätzlich nur noch ohne Trailing-Slash zulässig. Das bedeutet, dass https://prod.fit-connect.fitko.net/submission-api/v2/submissions korrekt ist, nicht jedoch https://prod.fit-connect.fitko.net/submission-api/v2/submissions/!

Verbot der Verwendung des JWE "zip" Headers

Die Verwendung des JWE "zip" Headers ist aufgrund von Sicherheitsbedenken nicht empfohlen (siehe RFC 8725, Sec. 3.6). Mit FIT-Connect 2.0 ist die Verwendung dieses Header nun explizit verboten, d.h. JWEs mit gefülltem "zip" Header werden abgelehnt. Dies betrifft den Upload sämtliche JWEs, sowohl Anhänge als auch Fach- und Metadaten von Submissions und Replies.

Umbenennung von serviceType und services

In den Request- und Response-Bodies der Submission API wurde das serviceType-Objekt in publicService umbenannt. Dies betrifft die Endpunkte:

• POST /v2/submissions
• PUT /v2/submissions/{id}
• GET /v2/submissions/{id}

Im Response-Body der Submission API wurde services in publicServices umbenannt. Dies betrifft den Endpunkt GET /v2/destinations/{id}.

In den Request- und Response-Bodies der Destination API wurde das services-Array in publicServices umbenannt. Dies betrifft die Endpunkte:

• POST /v2/destinations
• PUT /v2/destinations/{id}
• PATCH /v2/destinations/{id}
• GET /v2/destinations/{id}
• GET /v2/destinations

Diese Umbenennung soll zu einer besseren Verständlichkeit der Felder führen, welche ja eine Verwaltungsleistung repräsentieren.

replyChannels auf Wurzelebene

Im Response-Body des GET /v2/submissions/{id}-Endpunkts der Submission API wurde bisher ein replyChannels-Objekt auf Wurzelebene zurückgeben. Das Feld wurde schon vor einiger Zeit abgekündigt und ist nun vollständig entfernt worden. replyChannels sind jetzt nur noch unterhalb des publicServices-Arrays zu finden.

In der Destination API ist eine analoge Änderung in den folgenden Request- und Response-Bodies zu beachten:

• POST /v2/destinations
• PUT /v2/destinations/{id}
• PATCH /v2/destinations/{id}
• GET /v2/destinations/{id}
• GET /v2/destinations

Status-Codes und Header

Der PUT /v2/submissions/{id}-Endpunkt der Submission API gibt im Erfolgsfall nun HTTP 200 zurück (statt wie zuvor 202). Zwecks Konformität mit dem HTTP-Standard geben die Endpunkte POST /v2/replies und POST /v2/submissions jetzt einen Location-Header mit relativer URL zur angelegten Ressource zurück. Diese Header muss aber nicht ausgewertet werden.

Abruf von Destinations über die Submission API

In der Submission API können über GET /v2/destinations/{id} ohne Authentifizierung die öffentlichen Informationen eines Zustellpunkts abgeholt werden. Daran ändert sich nichts. Die v1-API hatte aber die zusätzliche Eigenschaft, bei entsprechender Autorisierung des anfragenden Clients, zusätzlich private Felder zurückzugeben (name, possibleNextStatus, contactInformation, callback, senderAccessRestricted). Dies ist nun nicht mehr der Fall.

Die Änderung erfolgt, um die beiden APIs klar nach Anwendungsfällen zu trennen:

• Die Submission API ist für das tägliche Geschäft rund um Einreichungen.
• Die Destination API ist für die optionale programmatische Verwaltung von Zustellpunkten.

Das jwk.use-Feld

In beiden APIs wurde das Feld use aus dem Response-Body von GET /v2/destinations/{id}/keys/{id} entfernt. In der Destination API wurde zusätzlich das Feld keys.use aus GET /v1/destinations/{destinationId}/keys entfernt. Das Feld enthält bereits in der v1-Version ausschließlich den Wert null. (Inhaltlich wird für die Unterscheidung von Schlüsseltypen nach wie vor das Feld key_ops verwendet.)

Das callback-Feld

In der Submission API wurde das Feld callback aus dem Response-Body von PUT /v2/submissions/{id} entfernt.