FIT-Connect 3.0

Inhalt

• Was ist neu?
• Rahmenbedingungen und Planung
• Prozessbasierte Kommunikation
• Migration Guide

Was ist neu?

Mit FIT-Connect 3.0 wird die Kommunikation über einzelne Verwaltungsleistungen hinaus erweitert. Komplexe Verwaltungsprozesse mit mehreren Beteiligten können jetzt besser digital unterstützt werden.

Mehrere Behörden arbeiten zusammen an einem Vorgang

Bisher

Ein Bürger oder Betrieb hat Daten an einen Onlinedienst geschickt, und meistens hat sich genau eine zuständige Behörde darum gekümmert.

Neu

Jetzt können beliebig viele Behörden in demselben Vorgang arbeiten und untereinander Daten austauschen.

Neue Wege für Nachrichten (Prozessnachrichten)

Bisher

Nachrichten wurden meistens nur über einen festen Leistungsschlüssel, eine Art Kennung für eine bestimmte Verwaltungsleistung wie "Gewerbeanmeldung", verschickt.

Neu

Es geht jetzt auch als Prozessnachricht. Die Behörden können sich dabei auf einen gemeinsamen Ablaufplan im BPMN-Format beziehen. BPMN ist eine Art digitales Flussdiagramm, das zeigt, unter welchen Bedingungen welcher Schritt als Nächstes kommt. Dies hilft den Behörden, automatisierte Arbeitsschritte besser und einheitlicher abzustimmen.

Neue Möglichkeiten für Onlinedienste

Onlinedienste erhalten mit der C-Destination einen eigenen Zustellpunkt. Beispielsweise stellt ein/e Bürger/in stellt über einen Onlinedienst einen Antrag. Der Vorgang hat verschiedene technische Zustellpunkte. Typ C ist dabei der Zustellpunkt, über den der Bürger erreichbar ist bzw. seine Antworten erhält.

Unternehmen kommen bald dazu*

Die Technik, damit auch Unternehmen diesen erweiterten Weg nutzen können, ist bereits fertig entwickelt.

*Diese Funktion ist erst zu einem späteren Zeitpunkt verfügbar.

Für zukünftige Prozesse gut aufgestellt

Mit den neuen Möglichkeiten schafft FIT-Connect die Basis für eine flexiblere Kommunikation über komplexe Verwaltungsprozesse hinweg.

Rahmenbedingungen und Planung

Im folgenden Abschnitt finden Sie wichtige Eckdaten rund um FIT-Connect 3.0, von organisatorischen Themen bis hin zu technischen Rahmenbedingungen.

Zeitplan

Für die Bereitstellung von Major Release 3 wurde folgende Termine festgelegt:

• 05. August 2026 - Deployment auf TEST
• 08. Oktober 2026 - Deployment auf STAGE
• 27. Oktober 2026 - Deployment auf PROD

Wichtig:

Zeitgleich mit dem Erscheinen von Major Release 3 werden

• alle API- und Metadatenschema-Versionen 2.x.x abgekündigt. Diese sind damit nur noch ein Jahr gültig.
• alle API- und Metadatenschema-Versionen 1.x.x abgeschaltet.

Um den Betrieb bestehender Anbindungen weiterhin sicherzustellen, ist eine rechtzeitige Migration auf die aktuellen Versionen erforderlich. Darüber hinaus stellt eine frühzeitige Migration sicher, dass bestehende Anbindungen weiterhin stabil betrieben und zukünftige Weiterentwicklungen genutzt werden können.

Weitere Informationen zu den Abkündigungen und Abschaltungen finden Sie am Ende dieser Seite.

Geschätzter Aufwand

Mit Major Release 3 werden Weiterentwicklungen bereitgestellt, die je nach Art der bestehenden Anbindung unterschiedliche Anpassungen erforderlich machen. Um Ihnen eine frühzeitige Planung zu ermöglichen, geben wir nachfolgend eine Orientierung zum voraussichtlichen Aufwand.

Grundsätzlich gilt: Die tatsächlichen Aufwände hängen unter anderem von

• der bestehenden Integrationsarchitektur,
• dem Umfang der genutzten Funktionen
• und den individuellen Gegebenheiten Ihrer Anbindung ab.

Für direkte API-Anbindungen sind die erforderlichen Anpassungen nach aktuellem Kenntnisstand überschaubar. In diesem Fall beschränken sich die erforderlichen Anpassungen in der Regel auf die Schnittstellenänderungen im Major Release 3 und die davon betroffenen Integrationspunkte. Der Umstellungsaufwand hängt davon ab, welche APIs und Funktionen die bestehende Anbindung nutzt und wie diese in den jeweiligen Onlinedienst oder das Verwaltungssystem integriert sind. Es empfiehlt sich daher, die Änderungen anhand der eigenen Implementierung zu prüfen und die betroffenen Komponenten gezielt anzupassen.

Wenn Sie hingegen ein SDK von FIT-Connect einsetzen, ist eine weitergehende technische Umstellung einzuplanen. Dies begründet sich dadurch, dass für Version 3 eine neue SDK-Version mit angepasster Implementierung erforderlich ist.

Support und Einführungstermine

Unser IT-Support steht Ihnen bei Fragen oder zur Unterstützung bei der technischen Umsetzung zur Verfügung. Bei allgemeinen Fragen rund um das Major Release konsultieren Sie gerne unser Anbindungsmanagement.

Zudem sind Sonderveranstaltungen im Nutzenden- und Technikkreis zur Einführung von Release 3 geplant. Die Anmeldungen zu diesen Einführungsterminen erfolgen über die Seite Termine für Kunden.

Technische Details

Release Notes

Informationen zu den technischen Details des Major Releases 3.0 können den zugehörigen Release Notes entnommen werden. Diese sind auf der Seite Changelog einsehbar.

Breaking Changes

Bei Systemen, die auf das Major Release 3.0 migrieren, sind verschiedene Änderungen und Anpassungen erforderlich. Werden diese Änderungen und Anpassungen nicht durchgeführt, ist ein ordnungsgemäßer Betrieb des migrierten Systems nicht möglich.

Details hierzu entnehmen Sie dem Abschnitt Migration Guide.

SDKs

Die aktuellen SDKs von Version 3 können hier eingesehen und heruntergeladen werden:

• Java SDK
• JavaScript SDK
• .NET-SDK

Abkündigung Version 2.x.x

Die 2.x.x-Versionen unserer APIs und des Metadatenschemas werden mit dem Erscheinen von Version 3 abgekündigt. Das Release 2.x wird für eine Übergangsfrist von einem Jahr unterstützt, ist also parallel noch gültig.

Nachfolgend erhalten Sie einen Überblick der davon aktuell betroffenen Versionen.

Hinweis

Hier werden in Kürze die neuesten Informationen verfügbar sein. Die Seite wird regelmäßig aktualisiert.

Destination API:

2.0.0-pu, 2.0.0, 2.1.0, 2.2.0, 2.3.0

Submission API:

2.0.0-pu, 2.0.0

Routing API:

2.0.0

Metadatenschema:

2.0.0, 2.1.0

Tipp

Detaillierte Informationen zu aktuellen und bestehenden Abkündigungen sind auf der Seite Abkündigungen einsehbar.

Abschaltung Version 1.x.x

Alle 1.x.x-Versionen unserer APIs und des Metadatenschemas werden mit dem Erscheinen von Version 3 abgeschaltet.

Für die Abschaltung dieser alten Versionen wurde folgender Zeitplan festgelegt:

• 05. August 2026 - Abschaltung auf TEST
• 08. Oktober 2026 - Abschaltung auf STAGE
• 27. Oktober 2026 - Abschaltung auf PROD

Aktuell sind von der Abschaltung die folgenden Versionen betroffen:

Destination API:

• 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.4.0, 1.5.0, 1.6.0, 1.7.0, 1.8.0, 1.9.0, 1.10.0, 1.11.0

Submission API:

• 1.2.1, 1.3.0, 1.4.0, 1.4.1, 1.4.2, 1.5.0, 1.6.0, 1.7.0, 1.8.0, 1.9.0, 1.10.0, 1.11.0, 1.12.0, 1.13.0, 1.14.0

Routing API:

• 1.2.0, 1.3.0

Metadatenschema:

• 1.4.0, 1.5.0, 1.6.0

Prozessbasierte Kommunikation

Hinweis

• Mit dem Major Update von FIT-Connect stehen die Submission API und die Destination API in Version 3.0.0 zur Verfügung.

• Informationen zu allgemeinen Konzeptänderungen und zum Migrationspfad von Version 2.x.x auf 3.0.0 finden Sie im Abschnitt Migration Guide. Hingegen dienen die folgenden Abschnitte dazu, Ihnen die (optionalen) neuen Features zur prozessbasierten Kommunikation vorzustellen.

Motivation

Bei einer Verwaltungsleistung folgt auf die initiale Einreichung (in der Regel ist das ein Antrag) ein Verwaltungsprozess. Dieser Prozess kann entweder innerhalb der zuständigen Behörde stattfinden oder auch andere Behörden sowie Unternehmen einbeziehen.

Wenn man den Digitalisierungsprozess bis zum Ende denkt, muss auch jegliche nachgelagerte Kommunikation berücksichtigt werden. Beispiele dafür sind das Einholen einer Zustimmung von einer (übergeordneten) Behörde, die Abfrage von Auskünften oder das Einholen einer Stellungnahme. Daher ist die Digitalisierung mit der Erfüllung des OZG alleine noch nicht vollständig.

FIT-Connect möchte im Vorgriff auf die zu erwartende Ende-Zu-Ende-Digitalisierung bereits heute das Angebot für die Nutzung als Basisinfrastruktur dahingehend erweitern. Das erklärte Ziel ist, "vor die Welle" zu kommen und damit den Aufwand für alle Beteiligten zu verringern.

Im Detail verfolgt FIT-Connect dabei folgende Ziele:

• Digitalisierung von den gesetzlichen Vorgaben bis hin zum ausführbaren Prozess durchdenken
• Bedürfnisse der Bürger:innen und Unternehmen in den Fokus nehmen
• Alle Akteure, direkt oder mittelbar, verbinden
• Standardisierte Prozesse einfach nachnutzbar machen
• Intuitive Prozessmodifikation und Bereitstellung ermöglichen
• Modularer Prozessaufbau und flexible Adaptierbarkeit unterstützen
• Extrem leichte Anbindung und einheitliche Rollen und Abläufe ermöglichen
• Security First gewährleisten – sowohl für den Datentransfer als auch für die Prozesssteuerung

Der Kern dieses Updates ist es daher, komplexere Prozesse mit mehr als zwei Beteiligten besser zu unterstützen. Fachlich unterstützt FIT-Connect damit nun Folgendes:

• Neben dem von Bürgern oder Unternehmen genutzten Onlinedienst und der verfahrensführenden Behörde können nun eine beliebige Anzahl weiterer Behörden innerhalb eines Vorgangs kommunizieren, sowohl untereinander als auch mit dem Onlinedienst.
• Die Integration von Unternehmen ist bereits technisch umgesetzt, aber noch nicht freigeschaltet.
• Innerhalb eines Vorgangs ist es möglich, Submissions nicht nur per Leistungsschlüssel zu adressieren, sondern alternativ auch per Prozessnachricht. Dies ermöglicht es Behörden, sich auf einen zuvor vereinbarten Prozessstandard (der zum Beispiel via BPMN abgelegt sein kann, aber nicht muss) beim Versand von Nachrichten zu beziehen.

Grundlegendes Konzept

Der Versand von Submissions oder Replies erfolgt nun immer von einer Destination zu einer anderen Destination. Dies ist nötig, um die Prozessteilnehmer besser zu identifizieren. Die verwendeten Clients dienen nur dazu, den Zugang zu diesen Destinations zu ermöglichen, spielen darüber hinaus aber keine Rolle.

Im Rahmen dieses Updates wurden zwei Typen von Destinations eingeführt und eine dritte Destination vorbereitet:

• Typ A (Verwaltungs-Zustellpunkt): raditionelle Zustellpunkte öffentlicher Verwaltungsbehörden, die neben Verwaltungsleistungen jetzt auch Prozessnachrichten unterstützen und, wie gehabt, V-PKI-Zertifikate erfordern. Alle bisherigen Zustellpunkte sind also jetzt vom Typ A.
• Typ C (Onlinedienst-Zustellpunkt): Zustellpunkte für Onlinedienste, ohne Zertifikat. Diese können weder Verwaltungsleistungen noch Prozessnachrichten spezifizieren und sind nur über Replies adressierbar. Nur eine C-Destination kann an einem Vorgang (case) teilnehmen und repräsentiert den Bürger.

Geplant: Typ B – Wirtschafts-Zustellpunkt

Der neue Typ B ist für Unternehmen vorgesehen. Er verwendet ausschließlich Prozessreferenzen, jedoch keine Verwaltungsleistungen. Typ B ist noch nicht verfügbar.

Neue Features im Detail

Erweiterungen des Destination-Schemas

An einer Destination können nun (ob programmatisch per Destination-API V3 oder per Self-Service-Portal) neben Verwaltungsleistungen (publicServices) auch Prozessnachrichten (Process Messages) angegeben werden, die diese Destination empfangen kann und möchte. Es ist also möglich, eine Destination ohne Verwaltungsleistungen zu konfigurieren oder ihr zusätzlich Prozessnachrichten zuzuordnen.

Destinations können anhand dieser Nachrichten gefunden werden (siehe unten). Statt an Verwaltungsleistungen können Submissions auch an Prozessnachrichten adressiert werden. FIT-Connect validiert bei einem solchen Versand, ob die jeweilige Ziel-Destination die Prozessnachricht unterstützt. Die Art und Weise, wie Sie mit diesen Datenfeldern umgehen und wie Sie Ihre Prozesse modellieren, pflegen und ausführen, können Sie frei gestalten. FIT-Connect gibt hierzu keine Vorgaben.

Das Destination-Schema erhält ein Feld processMessages (mit processModelId, messageId, regions, schemas) mit einer optionalen Liste der von der Destination unterstützten Prozessnachrichten. Diese steht in allen Lese- und Schreib-Endpunkten zur Verfügung. Das Konzept geht davon aus, dass sich die eindeutige ID einer Prozessnachricht aus der eindeutigen ID des Prozessmodells und der innerhalb des Prozessmodells eindeutigen ID der Nachricht ergibt. In BPMN wäre ein MessageFlow die Entsprechung einer Prozessnachricht.

Mehrere Teilnehmer an einem Case

Cases werden nach wie vor an eine A-Destination adressiert. Dazu muss (ob explizit oder implizit) eine Verwaltungsleistung angegeben werden. Ein Vorgang kann mit der API-Version 3 auch mehrere Teilnehmer haben. Dies ist möglich, wenn einer der beiden initialen Teilnehmer eine Submission an eine dritte Destination sendet und dabei die bestehende caseId referenziert wird. Damit wird der dritte Teilnehmer aufgenommen und dazu berechtigt, an die anderen beiden Destinations zu senden.

Jede Kommunikation erfolgt weiterhin nur bilateral. Auch können stets nur solche Events unter GET /v3/cases/{caseId}/events abgefragt werden, die mit den eigenen Destinations in Verbindung stehen.

Neuer Endpunkt POST /v3/cases

Ein neuer Endpunkt POST /v3/cases ermöglicht es, einen Vorgang explizit anzulegen, ohne gleichzeitig eine Einreichung zu erstellen. Voraussetzung ist die Adressierung an eine gültige A-Destination mit passender Verwaltungsleistung, um so den Bezug des Vorgangs zu einer Verwaltungsleistung zu gewährleisten. Es ist damit möglich, dass ein Onlinedienst einen Vorgang bei einer Verwaltungsbehörde anlegt, aber im Zusammenhang mit dieser soll zunächst eine andere Behörde die Einreichung bearbeiten.

Prozessbasierter Nachrichtenversand

Submissions

Submissions können in Version 3 optional ein processMessage-Objekt (bestehend aus processModelId und messageId) enthalten, um einen Prozessbezug herzustellen. Diese Einreichungsart setzt voraus, dass die Ziel-Destination die entsprechende Prozessnachricht in ihrem processMessages-Feld konfiguriert hat. Auch in Antworten (Replies) kann eine processMessage angegeben werden. Replies können dabei weiterhin nur an Destinations vom Typ C gesendet werden.

Das Feld caseId auf der Wurzelebene des POST /v3/submissions-Requests wurde entfernt und durch ein case-Objekt ersetzt. Zur Referenzierung eines bestehenden Vorgangs wird case.caseId verwendet.

Zur gleichzeitigen Eröffnung eines neuen Vorgangs können case.destinationId und case.publicService angegeben werden — dies ist jedoch ausschließlich in Kombination mit einer processMessage auf Wurzelebene erlaubt, nicht mit einem publicService auf Wurzelebene.

Verweis auf bestehenden Vorgang

{
  "case": {
    "caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Eröffnung eines neuen Vorgangs (nur mit processMessage)

{
  "processMessage": { "processModelId": "...", "messageId": "..." },
  "case": {
    "destinationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "publicService": {
      "identifier": "urn:de:fim:leika:leistung:99108034179000"
    }
  }
}

Replies

Mit Version 3 können Replies nun ebenfalls Prozessnachrichten referenzieren. Darüber hinaus kann im Rückkanal-Datensatz in den Metadaten spezifiziert werden, welche Prozessantworten die C-Destination empfangen kann, die eine Submission versendet.

Routing

Bisher gab es zwei Möglichkeiten, den Ziel-Zustellpunkt für das Senden eine Submission festzulegen:

• Eine beim Sender (Onlinedienst) fest konfigurierte DestinationID
• Die Ermittlung des Zustellpunktes anhand von Leistungsschlüssel und Region über den Routingdienst

In Abhängigkeit der fachlichen Rahmenbedingungen stehen nun weitere Möglichkeiten zur Verfügung, die genutzt werden können:

Neuer Such-Endpunkt

In der Submission API v3 steht ein neuer, öffentlich zugänglicher Such-Endpunkt zur Verfügung, der keine Authentifizierung erfordert:

• GET /v3/search-destinations/by-process-message: Suche von Zustellpunkten anhand von processModelId, messageId und Region. Dieser Endpunkt dient dazu, prozessbasierte Workflows zu ermöglichen.

Absender-Destination

In Version 3 der Submission-API besitzt jede Submission nun eine Absender-Destination. Der Empfänger kann diese persistieren und für die Adressierung von Submissions oder Replies verwenden, die er zu einem späteren Zeitpunkt im Prozess an diesen Teilnehmer senden muss.

Dataset process

In diesem Datensatz kann ein Sender dem Empfänger Informationen über Zustellpunkte und deren Verwendung als Adressat zukünftiger im Rahmen des Vorgangs zu sendender Prozessnachrichten mitteilen.

Beispiel

Der folgende Beispielprozess dient alleine der Veranschaulichung. Er hat keinen Bezug zu einem realen Verwaltungsprozess einer realen Verwaltungsleistung.

Senden und Empfangen der Prozessnachrichten (MessageFlows)

Für das Senden muss zuvor der Ziel-Zustellpunkt festgelegt werden. Je nach dem fachlichen Kontext gibt es dafür folgende Optionen:

• Eine fest konfigurierte ID eines Zustellpunktes, z. B. wenn es für eine Instanz bzw. einen Mandanten eines Fachverfahrens in jedem Fall nur eine Möglichkeit gibt
• Eine in den Metadaten einer zuvor zu diesem Vorgang empfangenen Prozessnachricht enthaltene Zustellpunkt-ID - im Dataset reply-channel oder im Dataset process
• Die ID des Absender-Zustellpunktes einer zuvor zu diesem Vorgang empfangenen Prozessnachricht
• Ein über den Routingdienst anhand von Leistung und Region ermittelter Zustellpunkt
• Ein über den neuen Suchendpunkt anhand von processModelId, messageId und Region ermittelter Zustellpunkt

Der Empfänger einer Prozessnachricht muss also in der Regel zum Vorgang (Case - caseId) der Nachricht die ID des Absender-Zustellpunktes und die ggf. in den Metadaten enthaltenen routing-relevanten Informationen persistieren, um diese beim Senden einer Prozessnachricht zum selben Vorgang verwenden zu können. Die caseId muss in jedem Fall gespeichert werden, da nur sie die Zuordnung später empfangener Prozessnachrichten zu dem Vorgang bzw. zur eigenen Prozessinstanz ermöglicht.

1 Anzeige

Die erste Nachricht, die zu einem Vorgang gesendet wird. Der Sender, hier ein Onlinedienst, ermittelt den Zustellpunkt der zuständigen Behörde. Einmal anhand von Leistung und Region über die klassische Routing-API, um für die Erstellung des Vorgangs (case) den Bezug zu einer Verwaltungsleistung herzustellen. Und einmal anhand von ProzessmodelID und MessageID über den neuen Suchendpunkt. Der Zustellpunkt der unteren Behörde muss also sowohl die Leistung als auch die Prozessnachricht unterstützen. Er sendet im Dataset reply-channel die Informationen zu:

• 2 Nachforderung zur Nachreichung
• 8 Empfangsbestätigung
• 4 Rückmeldung

2 Nachforderung zur Nachreichung

Der Sender hat zuvor "1 Anzeige" oder "3 Nachreichung" erhalten. Dabei wurde im Dataset reply-channel übermittelt, wie die Adressierung für "2 Nachforderung zur Nachreichung" erfolgt. Dort sind ebenfalls die Schlüssel für die Verschlüsselung der Nachricht enthalten. Da es sich beim Empfänger um einen Onlinedienst mit einer C-Destination handelt, wird hier keine Submission, sondern ein Reply gesendet.

3 Nachreichung

Der Sender kann den Absender-Zustellpunkt der zuvor empfangenen Nachricht "2 Nachforderung zur Nachreichung" für die Adressierung verwenden. Er sendet im Dataset reply-channel die Informationen zu:

• 2 Nachforderung zur Nachreichung
• 8 Empfangsbestätigung
• 4 Rückmeldung

4 Rückmeldung

Der Sender hat zuvor "1 Anzeige" oder "3 Nachreichung" erhalten. Dabei wurde im reply-channel-Dataset übermittelt, wie die Adressierung erfolgt. Dort sind ebenfalls die Schlüssel für die Verschlüsselung der Nachricht enthalten. Da es sich beim Empfänger um einen Onlinedienst mit einer C-Destination handelt, wird hier keine Submission, sondern ein Reply gesendet. Wenn der Zustellpunkt der "Fachbehörde" für den Onlinedienst zum Senden von "6 Einwendungen" nicht eindeutig per Such-Abfrage anhand von processModelId, messageId ermittelbar ist, schickt der Sender im Dataset process die nötigen Informationen mit.

5 Weitergeleitete Anzeige

Sofern es für den Sender nicht nur eine Möglichkeit gibt und deswegen die ID eines Ziel-Zustellpunktes fest konfiguriert wurde, ermittelt er den Empfänger anhand von processModelId, messageId und Region über den Suchendpunkt. Dies ist die erste Prozessnachricht, die die "Fachbehörde" erhält. Dadurch, dass das "Ordnungsamt" diese Nachricht an den Zustellpunkt der "Fachbehörde" sendet, wird dieser Zustellpunkt am Vorgang (case) beteiligt und somit dazu berechtigt, selbst weitere Prozessnachrichten zu diesem Vorgang zu senden.

6 Einwendungen

Der Sender verwendet den Suchendpunkt, um den Zustellpunkt des Empfängers zu ermitteln, sofern dieser eindeutig zu ermitteln ist. Ansonsten hat er zusammen mit "4 Rückmeldung" im Dataset process die nötigen Informationen erhalten. Er sendet im Dataset reply-channel die Informationen zu:

• 7 Rückmeldung zu Einwendungen

7 Rückmeldung zu Einwendungen

Der Sender kann den Absender-Zustellpunkt der zuvor empfangenen Nachricht "6 Einwendungen" für die Adressierung verwenden. Den Schlüssel entnimmt er dem mit "6 Einwendungen" erhaltenen Dataset reply-channel. Da es sich beim Empfänger um einen Onlinedienst mit einer C-Destination handelt, wird hier keine Submission, sondern ein Reply gesendet.

8 Empfangsbestätigung

Der Sender hat zuvor "1 Anzeige" oder "3 Nachreichung" erhalten. Dabei wurde im Dataset reply-channel übermittelt, wie die Adressierung erfolgt. Dort sind ebenfalls die Schlüssel für die Verschlüsselung der Nachricht enthalten. Da es sich beim Empfänger um einen Onlinedienst mit einer C-Destination handelt, wird hier keine Submission, sondern ein Reply gesendet.

9 Zustimmung

Der Sender kann den Absender-Zustellpunkt der zuvor empfangenen Nachricht "5 Weitergeleitete Anzeige" für die Adressierung verwenden.

10 Untersagung

Der Sender kann den Absender-Zustellpunkt der zuvor empfangenen Nachricht "5 Weitergeleitete Anzeige" für die Adressierung verwenden.

Alternative: Unternehmenssoftware statt Onlinedienst

Ein Onlinedienst wird von vielen natürlichen und/oder juristischen Personen genutzt. Um eine Ende-zu-Ende-Verschlüsselung für jeden einzelnen Nutzer zu gewährleisten, wird mit der C-Destination eine vorgangs- oder nutzerspezifische Verschlüsselung verwendet. Prozessnachrichten an den Onlinedienst werden daher als Antwort (Reply) gesendet.

Ein Antrag könnte jedoch auch direkt aus der Software eines spezifischen Unternehmens gesendet werden. Da diese Software ausschließlich von einer juristischen Person genutzt wird, kann sie eine B-Destination mit dem in der Destination hinterlegten Schlüssel verwenden. Prozessnachrichten an eine B-Destination werden als Einreichung (Submission) gesendet.

Videodemonstration

Unser Tipp

Das folgende Video zeigt Ihnen eine Demonstration mit drei verschiedenen Fachverfahren, die jeweils unterschiedliche Prozess-Engines verwenden:

Video:   Prozessunterstützung mit FIT-Connect

Migration Guide

Der folgende Abschnitt beschreibt die Migration von API Version 2.x.x auf 3.0.0.

Mit dem Major Update von FIT-Connect stehen die Submission API, die Destination API und das Metadatenschema in Version 3.0.0 zur Verfügung. Anbindungen können ab sofort auf diese neuen Versionen umgestellt werden. Die 2.x.x-Versionen sind hierdurch abgekündigt und werden nur noch ein Jahr zur Verfügung stehen.

Wichtig

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

Die nachfolgende Dokumentation beschreibt die Migration von FIT-Connect Version 2.x.x auf 3.0.0.

Grundsätzliche Konzeptänderungen

Ziel der API-Version 3 ist es, stärker eine prozessbasierte Kommunikation mit mehreren Teilnehmern innerhalb eines Vorgangs (case) zu ermöglichen. Dazu ist es notwendig, jeden Versand von Nachrichten immer nur von einer Destination zu einer Destination zu erlauben.

Im Rahmen dieses Updates werden zwei Typen von Destinations eingeführt und ein dritter Destination-Typ vorbereitet:

• Typ A (Verwaltungs-Zustellpunkt): Traditionelle Zustellpunkte öffentlicher Verwaltungsbehörden, die neben Verwaltungsleistungen jetzt auch Prozessnachrichten unterstützen und, wie gehabt, V-PKI-Zertifikate erfordern. Alle bisherigen Zustellpunkte sind also jetzt vom Typ A.
• Typ C (Onlinedienst-Zustellpunkt): Zustellpunkte für Onlinedienste. Zu jedem Onlinedienst-Client wird automatisch eine C-Destination erzeugt und zugewiesen. Diese Destinations können nicht wie Destinations vom Typ A adressiert werden; nur Replies können an sie gesendet werden. Dennoch müssen Onlinedienste die ID ihrer C-Destination kennen, um sie beim Versand anzugeben. Die C-Destination wird damit zum eigentlichen Absender des Antrags. Mit welchem zugewiesenen Client Onlinedienste Submissions senden oder Replies empfangen, ist zweitrangig. Die C-Destination ermöglicht es Onlinediensten außerdem, eine Callback-URL zu konfigurieren und Kontaktdaten anzugeben.

Geplant: Typ B – Wirtschafts-Zustellpunkt

Der neue Typ B ist für Unternehmen vorgesehen. Er verwendet ausschließlich Prozessreferenzen, jedoch keine Verwaltungsleistungen. Typ B ist noch nicht verfügbar.

Destinations vom Typ C sind in der API-Version 2 nicht sichtbar. Bei Einreichungen aus einer veralteten API-Version wird die C-Destination-ID automatisch inferiert und eingesetzt, solange nur eine einzige Destination mit dem Client verbunden ist. Eine Kommunikation zwischen Nutzern der API-Versionen 2 und 3 ist also problemlos möglich.

Wie Sie die neuen Features zur prozessbasierten Kommunikation mit mehreren Parteien verwenden, erläutern wir im Abschnitt Prozessbasierte Kommunikation. Hingegen beschreiben die folgenden Abschnitte, wie Sie bestehende Workflows und Integrationen auf Basis der neuen API-Version weiterbetreiben können.

Keine Unterschiede mehr bei den Clients (Zugangsdaten)

Da nun auch Sender-Clients (Onlinedienste) mit einem Zustellpunkt verbunden sein müssen, wurde die Unterscheidung der bisherigen Client-Typen aufgelöst. Welche Rolle ein Client spielen kann, hängt also allein davon ab, mit welchen Zustellpunkten er verbunden ist.

Anstelle von Sender-Clients (Onlinedienst) und Subscriber-Clients (Verwaltungssystem) gibt es nur noch allgemeine Zugangsdaten. Jeder Client verfügt über die Berechtigung zum Senden und zum Empfangen. Darüber hinaus kann ein Client dazu berechtigt werden, die ihm zugeordneten Zustellpunkte per Destination-API zu verwalten oder sogar neue, von ihm dann verwaltete Zustellpunkte per API anzulegen.

Änderungen, die jede bestehende Anbindung betreffen

fromDestinationId als Pflichtfeld

In Version 3 ist das Feld fromDestinationId in allen Requests für Einreichungen, Antworten und Vorgänge verpflichtend. Es gibt an, von welcher Destination die jeweilige Aktion ausgeht. Nur Clients, denen die verwendete fromDestinationId zugeordnet ist, dürfen die entsprechenden Endpunkte nutzen. Für Onlinedienste bedeutet das konkret, dass sie im Self-Service-Portal die ID der zu ihrem Onlinedienst zugeordneten C-Destination nachschlagen und in ihre Konfiguration aufnehmen müssen.

Callbacks auf Destination-Ebene

Case-Callbacks wurden in Version 3 vollständig entfernt. Die Endpunkte PUT /v3/cases/{caseId}/callback und DELETE /v3/cases/{caseId}/callback stehen nicht länger zur Verfügung. Onlinedienste konfigurieren ihre Callback-URLs künftig direkt einmalig an ihrer C-Destination. Ereignis-Callbacks werden an die Callback-URL der jeweiligen fromDestinationId (bei für Sender relevanten Ereignissen) bzw. toDestinationId (bei für Empfänger relevanten Ereignissen) zugestellt.

Das callback-Objekt wurde vollständig aus Einreichungs-Requests und -Responses der Submission API entfernt. Betroffen sind Requests und Responses der Endpunkte POST /v3/submissions, PUT /v3/submissions/{id} und GET /v3/submissions/{id}.

Entfernung der bisherigen Limits-Endpunkte

Die Endpunkte GET /v3/destinations/{destinationId}/limits und GET /v3/cases/{caseId}/limits wurden entfernt und durch den neuen Endpunkt GET /v3/limits/{fromDestinationId}/{toDestinationId} ersetzt.

Der neue Endpunkt benötigt keine Authentifizierung, verwendet zwei Pfadparameter (Absender- und Empfänger-Destination) und liefert eine vereinfachte Struktur ohne Trennung in Submission- und Reply-Limits. Attachment-Limits werden nun pro Destination konfiguriert, da Sender in Version 3 stets über eine Destination-Identität verfügen. Die bisherigen client-basierten Limits entfallen.

Strenge LeiKa-Validierung

In Version 3 werden Einreichungen abgelehnt, wenn der angegebene publicService.identifier nicht mit einer der Verwaltungsleistungen übereinstimmt, die an der Ziel-Destination konfiguriert sind. Diese Prüfung war in Version 1 und 2 nicht aktiv. Integrationen, die bisher nicht valide Leistungsschlüssel übertragen haben, müssen die übergebenen Werte korrigieren, bevor sie auf Version 3 migrieren.

Sortierung von GET /v3/submissions

GET /v3/submissions gibt Einreichungen nun nach dem Zeitpunkt der letzten Statusänderung (stateChangedAt) sortiert zurück — statt wie bisher nach Destination gruppiert. Die älteste Einreichung steht somit an erster Stelle der Liste.

Neue optionale Filterparameter

In Version 3 stehen die folgenden neuen Filterparameter zur Verfügung:

• GET /v3/submissions: Filterbar nach publicService. Das Feld publicService wird entsprechend auch in der Response zurückgegeben.
• GET /v3/replies: Filterbar nach destinationId.
• GET /v3/cases/{caseId}/events: Filterbar nach submissionId, replyId und Eventtyp.

Metadaten

Fachverfahren sollten das Metadatenschema in Version 3.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 ebenfalls als abgekündigt gelten.

Darüber hinaus bietet das Metadatenschema 3.0.0 auch inhaltliche Erweiterungen und Verbesserungen.

Das Metadatenschema ist bereits seit Version 2 modularisiert. Neu in Version 3.0.0 ist, dass Angaben zu Rückkanälen nicht mehr im Schema selbst, sondern als Dataset angegeben werden müssen.

Dataset reply-channel 1.0.0

Rückkanal-Dataset 1.0.0

Dieses Dataset ersetzt das bisherige replyChannel-Objekt auf der Wurzelebene des Metadatenschemas. Es können nun mehrere Rückkanäle angegeben und — zusätzlich zu den bekannten Kanaldaten — auch Routing-Daten für die prozessbasierte Kommunikation mitgeliefert werden.

Der fitConnect Rückkanal wurde dahingehend modifiziert, dass anstelle der Property processStandards das Tupel aus supportedSchemas und destinationId tritt, um die zu verwendende Destination-ID und die unterstützten Schemas im Falle einer Antwort angeben zu können. Die im fitConnect Rückkanal angegebene destinationId muss der destinationId des Onlinedienstes entsprechen, da nur an diesen Antworten (replys) gesendet werden können.

Das optionale Array messages kann dazu genutzt werden, um Prozessnachrichten auf Rückkanäle zu mappen.

Dataset process 1.0.0

Prozess-Dataset 1.0.0

Dieses neue Dataset dient dazu, Routing-Daten für die prozessbasierte Kommunikation bei Submissions mitzuliefern. Details hierzu finden Sie im Abschnitt Prozessbasierte Kommunikation. Ein Anwendungsfall wäre beispielsweise, wenn es für eine Rolle in einem konkreten Vorgang mehrere Möglichkeiten gibt und eine dieser Möglichkeiten bereits als Teilnehmer ausgewählt wurde.

Mit dem Dataset process kann die Information über diesen Teilnehmer an andere Teilnehmer weitergegeben werden. Dies ist erforderlich, da eine Routing- bzw. Such-Abfrage mehrere Treffer ergeben würde.

Routing

Es ist keine Routing API v3 vorgesehen; stattdessen wurde die Routing API von Version 2.0.0 auf Version 2.1.0 aktualisiert.

Die neue Routing API 2.1.0 gibt zusätzlich die folgenden Informationen aus:

Feld	Beschreibung
(Zuständige) Organisation: kennzeichenOeffentlichAnzeigen	Gibt an, ob der Onlinedienst die Daten der Organisationseinheit anzeigen darf.
(Zuständige) Organisation: zustaendigkeitskriterium	Bei Mehrfachzuständigkeit kann der Onlinedienst ggf. auf ein gepflegtes Unterscheidungsmerkmal zurückgreifen.
(Zuständige) Organisation: destinationShortName	Fehler behoben: Dieses Feld gibt nun korrekt die Kurzbezeichnung der Organisationseinheit aus (und nicht die Kurzbeschreibung).
Leistung: kennzeichenFormularSchriftformerfordernis	Gibt an, ob der Onlinedienst die Schriftformerfordernis digital abbilden muss.

hinweis

Der Routingdienst befüllt die neuen Felder nur dann, wenn die entsprechenden Daten im jeweiligen Landesredaktionssystem eingepflegt wurden.

Änderungen für Anbindungen mit dem Java SDK

FIT-Connect 3.0.0 wird ab dem Java SDK 4.0.0 unterstützt. Das SDK ist modular aufgebaut und erscheint unter der Group-ID dev.fitko.fitconnect (mindestens sdk-client, bei Bedarf zbp-client, cli und das bom). Es ersetzt das bisherige Artefakt dev.fitko.fitconnect.sdk:client (3.x), das weiterhin über die API-Version 2 kommuniziert. Das neue SDK nutzt ausschließlich die /v3-Endpunkte, eine Umstellung der Basis-URLs ist nicht nötig. Vorausgesetzt wird Java 21.

<dependency>
  <groupId>dev.fitko.fitconnect</groupId>
  <artifactId>sdk-client</artifactId>
  <version>4.0.0</version>
</dependency>

Neben der API-Umstellung hat sich auch die Programmierschnittstelle des SDK geändert: ein Einstiegspunkt FitConnectSdk statt ClientFactory und ApplicationConfig, Rollen-Clients OnlineService/Organisation statt SenderClient/SubscriberClient, die Builder OutgoingSubmission.to(…) und OutgoingReply.answering(…) statt SendableSubmission/SendableReply. Jede Änderung mit Code-Gegenüberstellung 3.x → 4.0 finden Sie in der Migrationsanleitung im Repository, eine Übersicht unter Changelog & Migration, die vollständige API im Spickzettel (Java).

Drei Änderungen, die der Compiler nicht meldet

• Kein Auto-Reject mehr: enableAutoReject ist entfallen, das SDK lehnt nie von sich aus ab. Prüfen Sie nach receive(…) den Prüfbericht mit received.acceptable() und rufen Sie ausdrücklich accept(…) oder reject(…) auf, sonst bleiben fehlerhafte Einreichungen unbeantwortet. Hintergrund: Konzept: Der Prüfbericht.
• Paging-Reihenfolge: Aus (limit, offset) wird (offset, limit), etwa bei cases().list(offset, limit) und awaitingReplies(offset, limit). Beide Parameter sind int, vertauschte Werte kompilieren weiterhin.
• AuthenticationTags erwartet jetzt zuerst metadata, dann data (new AuthenticationTags(metadataTag, dataTag, attachmentTags)).

Eine Zugangsdatenquelle mit eigener Destination-ID

Analog zur Auflösung der Client-Typen gibt es in der Konfiguration nur noch einen Block credentials statt senderConfig und subscriberConfig. Private Schlüssel stehen nicht mehr in der YAML-Datei, sondern werden im Code übergeben. Die ID der eigenen Destination – bei Onlinediensten die ID der C-Destination aus dem Self-Service-Portal – nennen Sie beim Erzeugen des Rollen-Clients. Das SDK setzt sie als fromDestinationId in jeden Request:

credentials:
  clientId: "…"
  clientSecret: "…"

environment: "TEST"

var sdk = FitConnectSdk.fromConfigYaml(Path.of("fitconnect.yaml"));

var svc = sdk.onlineService(MY_DESTINATION_ID);                        // Typ C → OnlineService
var amt = sdk.organisation(MY_DESTINATION_ID,                          // Typ A/B → Organisation
    new DestinationKeys(decryptionKey, signingKey));

Beim Erzeugen prüft das SDK, ob die Destination existiert und ihr Typ zur Rolle passt: Eine unbekannte ID führt zu einer RestApiException, ein anderer Typ zu einer FitConnectConfigurationException. Onlinedienste, die Antworten lesen, übergeben zusätzlich ihre Rückkanal-Schlüssel als ReplyKeys. OnlineService kann keine Antworten senden, Organisation keine empfangen; ein Verwaltungssystem, das bisher mit dem SenderClient selbst Einreichungen verschickt hat, ruft dafür jetzt amt.send(submission) auf.

Änderungen der API-Version 3 im SDK

Änderung	Umsetzung im Java SDK
fromDestinationId als Pflichtfeld	Wird automatisch aus der Destination-ID gesetzt, die Sie onlineService(…) bzw. organisation(…) übergeben (siehe oben).
Callbacks auf Destination-Ebene	setCallback(…) am Builder ist entfallen, Anträge tragen keine Callback-Angaben mehr. Callback-URL und -Secret pflegen Sie an der eigenen Destination: im Self-Service-Portal oder (mit Scope manage-destinations) über sdk.manage().destinations().patchDestination(destinationId, DestinationPatch.builder().callback(new Callback(callbackUri, secret)).build()). Eingehende Callbacks prüfen Sie weiterhin mit CallbackValidationUtil.validateCallback(…), siehe Callbacks validieren.
Neuer Limits-Endpunkt	Kein Handlungsbedarf: Vor dem Versand fragt das SDK GET /v3/limits/{fromDestinationId}/{toDestinationId} ab und richtet die Chunk-Größe der Anhänge daran aus. Die Limits der eigenen Destination verwalten Sie mit sdk.manage().destinations().getAttachmentLimits(…) bzw. requestLimitChange(…).
Strenge LeiKa-Validierung	Das SDK prüft schon vor dem Versand, ob die Ziel-Destination die Leistung anbietet, und wirft andernfalls eine FitConnectSenderException. Ermitteln Sie Empfänger am besten über sdk.directory().forService(leikaKey, serviceName, ars) und übergeben Sie das Ergebnis mit OutgoingSubmission.to(participant), dann passen Destination und Leistung zusammen (siehe Empfänger finden). Kennen Sie die Destination-ID bereits, bauen Sie den Empfänger mit Participant.of(destinationId, Addressing.toService(leikaUrn, serviceName)).
Sortierung von GET /v3/submissions	awaitingSubmissions() liefert die Einreichungen in dieser Reihenfolge, die älteste zuerst – und zwar über alle Seiten hinweg; awaitingSubmissions(offset, limit) holt eine einzelne Seite.
Metadatenschema 3.0.0	preferMetadataVersion(…) und setMetadataVersion(…) sind entfallen: Das SDK sendet die höchste Version, die Destination und SDK gemeinsam unterstützen (2.0.0, 2.1.0 oder 3.0.0). Gibt es keine gemeinsame Version, bricht der Versand mit einer FitConnectSenderException ab. Fachverfahren tragen die Unterstützung von 3.0.0 nach der Umstellung auf das neue SDK im Self-Service-Portal ein.
Dataset reply-channel	setReplyChannel(ReplyChannels.fitConnect(replyPublicKey, supportedSchemas)) erzeugt das Dataset; supportedSchemas ist eine List<DataSetSchema> aus Schema-URI und MIME-Typ. Eine destinationId geben Sie nicht mehr an, das SDK trägt die eigene ein. Mehrere Rückkanäle (ReplyChannels.of(…)) und setReplyChannelMessages(…) sind nur mit Metadaten 3.x möglich. Empfänger lesen den Rückkanal unabhängig von der Metadaten-Version mit ReplyChannelResolver.resolve(received.getMetadata()); OutgoingReply.answering(received) übernimmt den Antwortschlüssel direkt aus der Einreichung.
Dataset process	Wird nicht automatisch erzeugt. Bauen Sie es bei Bedarf mit DataSets.of(schemaUri, "application/json", description, payload) und übergeben Sie es mit setDataSets(List.of(…)). Beim Empfang finden Sie es in received.getMetadata(), bei Metadaten 3.x als MetadataV3 mit getDataSets().
allowedSenderDestinations	new SenderAccess(true, List.of(), Set.of(senderDestinationId)) im Feld senderAccessRestricted beim Anlegen (createDestination) oder Ändern (patchDestination) einer Destination, siehe Zustellpunkte verwalten. Die Komponente allowedSenders ist als @Deprecated markiert.

Weitere Informationen finden Sie im Changelog des Java SDK und in den Beispielprojekten.

Änderungen für Anbindungen mit dem .NET SDK

FIT-Connect 3.0.0 wird ab dem .NET SDK 4.0.0 unterstützt. Es besteht aus den NuGet-Paketen Fitko.FitConnect.* (mindestens Fitko.FitConnect.Client) und ersetzt das bisherige Paket FitConnect (3.x). Dieses kommuniziert weiterhin über die API-Version 2. Das neue SDK nutzt ausschließlich die /v3-Endpunkte, eine Umstellung der Basis-URLs ist nicht nötig.

Neben der API-Umstellung hat sich auch die Programmierschnittstelle des SDK geändert: Registrierung per Dependency Injection, Rollen-Clients statt SenderService/ReceiverService, neue Builder-API. Eine Übersicht dieser Änderungen finden Sie unter Changelog & Migration, die vollständige API im Spickzettel (.NET).

Eine Zugangsdatenquelle mit eigener Destination-ID

Analog zur Auflösung der Client-Typen gibt es in der Konfiguration nur noch einen Abschnitt Client statt Sender und Receiver. Dort tragen Sie die ID Ihrer eigenen Destination ein, Onlinedienste also die ID ihrer C-Destination aus dem Self-Service-Portal. Das SDK setzt sie als fromDestinationId in jeden Request:

{
  "FitConnect": {
    "EnvironmentTag": "TEST",
    "Client": {
      "ClientId": "…",
      "ClientSecret": "…",
      "DestinationId": "<ID der eigenen Destination>",
      "DecryptionKeys": ["…"],
      "SignatureKey": "…"
    }
  }
}

services.AddFitConnect(FitConnectRole.OnlineService);   // Typ C → IOnlineServiceClient
services.AddFitConnect(FitConnectRole.Organisation);    // Typ A/B → IOrganisationClient

Beim Start des Hosts prüft das SDK, ob die konfigurierte Destination existiert und ihr Typ zur deklarierten Rolle passt. Andernfalls bricht der Start mit einer FitConnectConfigurationException ab.

Änderungen der API-Version 3 im SDK

Änderung	Umsetzung im .NET SDK
fromDestinationId als Pflichtfeld	Wird automatisch aus Client.DestinationId gesetzt (siehe oben).
Callbacks auf Destination-Ebene	Anträge tragen keine Callback-Angaben mehr. Callback-URL und -Secret pflegen Sie an der eigenen Destination: im Self-Service-Portal oder (mit Scope manage-destinations) über client.Manage().Destinations.UpdateDestination(…) mit Callback = new Callback(url, secret). Eingehende Callbacks prüfen Sie mit CallbackValidationUtil.ValidateCallback(…), siehe Callbacks validieren.
Neuer Limits-Endpunkt	Kein Handlungsbedarf: Vor dem Versand fragt das SDK GET /v3/limits/{fromDestinationId}/{toDestinationId} ab, passt die Chunk-Größe der Anhänge an und bricht bei überschrittenem Limit mit einer FitConnectSenderException ab. Die Limits der eigenen Destination verwalten Sie mit client.Manage().Destinations.GetAttachmentLimits(…) bzw. RequestLimitChange(…).
Strenge LeiKa-Validierung	Das SDK prüft schon vor dem Versand, ob die Ziel-Destination die Leistung anbietet, und wirft andernfalls eine FitConnectSenderException. Ermitteln Sie Empfänger am besten über client.Directory.ForService(…) und übergeben Sie das Ergebnis mit WithRecipient(participant), dann passen Destination und Leistung zusammen.
Sortierung von GET /v3/submissions	FetchAvailableSubmissions() liefert die Einreichungen in dieser Reihenfolge, die älteste zuerst.
Metadatenschema 3.0.0	WithMetadataVersion(…) ist optional und nur eine Präferenz: Das SDK sendet die höchste Version, die Destination und SDK gemeinsam unterstützen (2.0.0, 2.1.0 oder 3.0.0). Fachverfahren tragen die Unterstützung von 3.0.0 nach der Umstellung auf das neue SDK im Self-Service-Portal ein.
Dataset reply-channel	WithReplyChannel(ReplyChannel.OfFitConnect(publicKey, supportedSchemas)) erzeugt das Dataset. Eine destinationId geben Sie nicht mehr an, das SDK verwendet Client.DestinationId. Mehrere Rückkanäle sind nur mit Metadaten 3.x möglich. Empfänger lesen den Rückkanal mit received.GetReplyChannel().
Dataset process	Wird nicht automatisch erzeugt. Fügen Sie es bei Bedarf mit WithDataSet(new ProcessDataSet([…]).ToDataSet()) hinzu und lesen Sie es beim Empfang mit ProcessDataSet.FromDataSet(…).
allowedSenderDestinations	new SenderAccessRestricted(enabled: true, allowedSenderDestinations: [senderDestinationId]) beim Anlegen (CreateDestination) oder Ändern (PatchDestination) einer Destination. AllowedSenders ist als [Obsolete] markiert.

Weitere Informationen finden Sie im Changelog des .NET SDK und in den Beispielprojekten.

Änderungen für Anbindungen ohne SDK

Basis-URLs und Pfade

Verwenden Sie dieselben Basis-URLs wie für Ihre Requests der API-Version v2 — mit dem Unterschied, dass das Pfad-Präfix nun /v3 lautet.

Weitere Änderungen für Nutzer der Destination-API

Verpflichtende Angabe von Destination-Typen

Beim Anlegen einer Destination ist nun ein Pflichtfeld type anzugeben. Als mögliche Werte kommen A und C in Betracht (siehe oben). Da Destinations vom Typ C keine Verwaltungsleistungen oder öffentliche Schlüssel unterstützen, sind die Felder publicServices und encryptionKid keine Pflichtfelder mehr. Beachten Sie beim Abruf von Destinations, dass diese Felder bei C-Destinations auch fehlen.

Zeitstempel updatedAt

updatedAt ist der Zeitstempel der letzten Änderung der Destination. Dieser wird sowohl in der Einzel-Ressource (GET /v3/destinations/{id}) als auch in der Listenansicht (GET /v3/destinations) zurückgegeben.

Authentifizierung beim Abruf von Destinations

In Version 2 lieferte GET /v2/destinations/{id} der Destination-API öffentliche Destination-Daten auch ohne Authentifizierung zurück.

Dieses Verhalten entfällt in Version 3: GET /v3/destinations/{id} gibt ausschließlich vollständige Destination-Daten an authentifizierte und autorisierte Clients zurück.

Unauthentifizierte oder unautorisierte Zugriffe werden mit HTTP 403 abgewiesen.

Die für den Versand von Submissions an eine Destination erforderlichen Daten können weiterhin ohne Authentifizierung über GET /v3/destinations/{id} der Submission-API abgerufen werden. Dort werden grundsätzlich nur die öffentlichen Destination-Daten zurückgegeben. Durch diese Maßnahme werden die beiden APIs stärker auf ihren jeweiligen Verwendungszweck ausgerichtet.

allowedSenders (Client-IDs) wird durch allowedSenderDestinations (Destination-IDs) abgelöst

Wer bisher senderAccessRestricted.allowedSenders verwendet hat, um eingehende Einreichungen auf bestimmte Absender zu beschränken, muss diese Konfiguration auf das neue Feld senderAccessRestricted.allowedSenderDestinations migrieren.

Was sich geändert hat:

• Es gibt nun zwei parallele Listen: Die bestehende Client-Liste (allowedSenders) und die neue Destination-Liste (allowedSenderDestinations).
• Eingehende Sendungen werden akzeptiert, wenn der Absender auf einer der beiden Listen steht.
• Über Version 3 lässt sich allowedSenderDestinations vollständig lesen und schreiben (POST/PUT/PATCH).
• Über Version 3 lässt sich allowedSenders nur noch lesen und vorhandene Einträge entfernen — das Hinzufügen neuer Client-IDs ist in Version 3 nicht länger möglich.
• Das Feld allowedSenders ist in der API-Dokumentation als deprecated markiert.
• Beide Listen werden in der API-Version V3 zurückgegeben.

Was zu tun ist:

Tragen Sie zukünftige Absenderbeschränkungen über allowedSenderDestinations ein, indem Sie die Destination-ID des sendenden Systems (nicht mehr die Client-ID) verwenden. Die Destination-ID muss ihr Kommunikationspartner mitteilen.

In den meisten Fällen wird es sich dabei um die C-Destination eines Onlinedienstes handeln. Es ist aber durchaus möglich, dass ein Verwaltungssystem mit einer A-Destination als Sender auftritt.

Bestehende Einträge in allowedSenders bleiben bis zu einem gesondert kommunizierten Stichtag gültig. Sie sollten die Einträge jedoch zeitnah in allowedSenderDestinations überführen und anschließend aus allowedSenders entfernen.

Hinweis

Die allowedSenders-Liste (Client-IDs) wird zu einem späteren Zeitpunkt vollständig abgekündigt und geleert. Alle Konfigurationen müssen bis dahin auf allowedSenderDestinations (Destination-IDs) umgestellt sein.