das Abrufen veröffentlichter Formulare
das Aufrufen mit vorheriger Befüllung des Formulars (inkl. Weitergabe des AUTH-Niveaus und persönlicher Daten)
das Übermitteln des ausgefüllten Formulars an optiGov

Im Folgenden befinden sich die jeweiligen Leitfäden / Erklärungen für die einzelnen Funktionen und Schritt der Anbindung.

Formulare vom Formularserver abrufen

Es können Formulare von dem Formularserver als Liste abgerufen werden, um diese in optiGov zur Verknüpfung bereitzustellen.

Dabei werden für die jeweiligen Formulare eigene Refernz-Einträge in der Datenbank bei optiGov angelegt, welche anhand einer extern festelgbaren ID (i.d.R. die ID des Formulars auf seiten des Formularservers) geupdated werden kann.

Informationen welche für ein Formular berücksichtigt werden können, beinhalten:

id ID des Formulars auf dem Formularservers - kann identisch bei mehreren Versionen des selben Formulars sein
identifier Dient zur Wiedererkennung dieser eindeutigen Formularversion bei der Synchronisation durch optiGov. Dies kann z.B. eine Versionsnummer, Name, Bezeichner, etc. sein, muss sich aber von allen anderen Einträgen eindeutig unterscheiden und über die Zeit gleich bleiben. Wird dem Nutzer nicht angezeigt.
titel Name es Formulars.
bezeichner Bezeichner (z.B. fachliche Kennzeichnung) zur Wiedererkennung in der Oberfläche von optiGov. Wird dem Nutzer angezeigt.
editor Veröffentlicher oder Autor des Formulars. Wird als “Benutzer” in der Oberfläche angezeigt.
url URL des Formulars.
vertrauensstufe Die benötigte Vertrauensstufe des Formulars. Mögliche Werte sind NONE, LOW und HIGH.

Die Anbindung / Aktualisierung dieser Liste übernimmt an dieser Stelle optiGov. Es wird ein REST-Api-Endpunkt über die GET-Methode aufgerufen, welcher im JSON-Format die o.g. Informationen zur Verfügung stellt.

Dieser REST-Api-Endpunkt ist optiGov mitzuteilen.

Eine Beispiel-Struktur, welche übernommen werden kann ist in der folgenden JSON-Datei zu finden:

formulare.json0.8KB

Antrag Aufrufen und Befüllen

Möchte ein Bürger ein Formular ausfüllen und klickt im optiGov-Bürgerservice auf dieses, stellt optiGov sicher, dass das benötigte Vertrauensniveau nachgewiesen ist und leitet erst anschließend auf das Formular um.

Dabei wird über ein Parameter (i.d.R. jsonwebtoken) ein JSON-Web-Token (kurz JWT) mit übergeben, welches es dem Formularserver ermöglicht, Informationen über den Bürger, wie persönliche Daten und das Authentifizierungsniveau abzufragen. Dabei ist dass JWT von optiGov signiert, um sicherzustellen und auszuschließen, dass Dritte Parteien Daten manipulieren oder Abgreifen können.

Die URL zum abfragen der Bürger-Daten ergibt sich aus der URL der jeweiligen optiGov Instanz der Resource /api/antrag/anfrage. Also z.B. für die Partner-Instanz:

https://partner.optigov.de/api/antrag/anfrage

Dabei ist das erhaltene JWT im Authorization-Header der Anfrage anzugeben.

Eine erfolgreiche Antwort auf diese Anfrage sieht wie im folgenden Beispiel aus. Dabei ist die Struktur immer die selbe und unabhängig davon welches Nutzerkonto (z.B. Servicekonto.NRW, BundID, etc.) verwendet wurde.

{
	"apiVersion" => "1.0",
	"data" => [
	    "meta" => [
	        "returnUrl" => "https://mein-portal.dd/buerger/antraege"
	    ],
	    "buerger" => [
	        "Nachname" => "Mustermann",
	        "Geburtsname" => null,
	        "Vorname" => "Max",
	        "Mittelname" => null,
	        "Adresse" => "Musterstraße 12, 12345 Musterstadt",
	        "AdresseStrasseHnr" => "Musterstraße 12",
	        "AdressePLZ" => 12345,
	        "AdresseOrt" => "Musterstadt",
	        "AdresseStaat" => "Deutschland",
	        "Geburtsdatum" => "2000-07-08",
	        "Nationalitaet" => null,
	        "Titel" => null,
	        "Kuenstlername" => "Maxartist",
	        "AusstellenderStaat" => null,
	        "Pseudonym" => null,
	        "Geburtsort" => "Delbrück",
	        "Dokumentenart" => null,
	        "ErrechneteBenutzerID" => "SERVICEKONTO_ID/BUND_ID",
	        "Anrede" => "Herr",
	        "EMailAdresse" => "max@mustermann.dd",
	        "AuthLevel" => "LOW",
	        "DEMailAdresse" => null,
	        "Mobilnummer" => null,
	        "Doktorgrad" => null,
	    ]
	]
}

Hat die Eigenschaft data.buerger den Wert null, so bedeutet dies, dass sich der Bürger im Vorhinein nicht authentifiziert hat.

Ausgefüllte Formulare an optiGov senden

Nach dem Ausfüllen kann ein Formular (nun Antrag genannt) an optiGov über einen Multipart-POST-Aufruf des REST-Api-Endpunkts /api/antrag/remit/{token} übermittelt werden. Dabei ist {token} das JWT, welches beim Aufruf des Formulars mitgegeben wurde.

Die URL zum Einreichen des Antrags ergibt sich aus der URL der jeweiligen optiGov Instanz. Also z.B. für die Partner-Instanz:

https://partner.optigov.de/api/antrag/remit/{token}

Dem POST-Aufruf können alle verwendeten Dateien angehangen werden. Wie diese übermittelt werden (z.B. Name, Codierung, etc.) ist an optiGov zu kommunizieren, da das entgegennehmen von optiGov implementiert wird.

I.d.R. werden die Dateien nach folgendem Schema benannt, wobei nicht alle Dateien übermittelt werden müssen:

pdf als Name für den ausgefüllten Antrag in PDF-Form
xml als Name für eine maschinenlesbare XML-Datei
json als Name für eine maschinenlesbare JSON-Datei
attachment_x, wobei x hier eine fortlaufende Zahl der Anhänge ist, startend mit 0

Der erfolgreiche Austausch zwischen dem Formularserver und optiGov wird über folgende Antwort bestätigt.

{
	"apiVersion" => "1.0",
	"data" => [
	    "success" => true
	]
}

Sollte das Feld data.success nicht den Wert true besitzen, wid empfohlen den Antrag zu einem späteren Zeitpunkt erneut zu senden.