Vorgangsraum-API

Für die Kommunikation mit dem Vorgangsraum kann ein SOAP Webservice genutzt werden. Dieser dient als Transportmedium für eine Vielzahl von Dateiformaten. Unterstützt werden XÖV Nachrichtenformate wie XBau oder XMeld, aber auch individuell vereinbarte XML Schema zur automatischen Validierung ein- und ausgehender Nachrichten.

Der Vorgangsraum-Webservice bietet drei Methoden

• transmitMessage = Anliefern einer Nachricht inkl. Anlagen
• getMessage = Abholen einer Nachricht inkl. Anlagen
• queryMessages = Abfrage aller noch nicht durch das Fachverfahren abgeholten Nachrichten, bzw. seit dem letzten Abholen neu eingegangen Nachrichten

Zugriff

Ein üblicher Webservice Endpunkt ist wie folgt aufgebaut:

https://domain/ws/vgv/soap/v2.0/?wsdl

Der Zugriff auf den Webservice erfolgt Kanal verschlüsselt via Https. Die Methoden des Webservices können nur mit gültigen Anmeldedaten genutzt werden. Die Zugangsdaten sind als als WS-Security Header (Verfahren basicAuth, Username, PasswordText) mitzusenden.

Um eine performante Übertragung größerer Dateien zu ermöglichen unterstützt der Webservice die SOAP Message Transmission Optimization Mechanism (MTOM) Technologie.

Anlieferung von Nachrichten „transmitMessage“

Das Erzeugen von Nachrichten im Vorgangsraum erfolgt über die SOAP Webservice Methode „transmitMessage“. Diese Methode erwartet als einzige Pflichtparameter die eindeutige ID des Antrags und die Nachricht als XML Datei. Weitere Anlagen können als Anlagen hinzugefügt werden. Darüber hinaus können zusätzliche Parameter wie eine DVDV Kennung für die eindeutige Adressierung übergeben werden (für XÖV Nachrichten nicht notwendig).

Abfrage neuer Nachrichten „queryMessages“

Um eine Liste aller aus Sicht des Fachverfahrens neuen Nachrichten zu ermitteln, ist die Methode „queryMessages“ aufzurufen. Das Ergebnis dieses Aufrufs ist eine Liste aller noch nicht abgeholten Nachrichten (ID‘s). Die Ergebnisliste ist auf maximal 1000 Einträge begrenzt. Mit Hilfe eines Paginierung-Mechanismus können weitere 1000er Blöcke abgefragt werden. Zusätzlich lässt sich die Suche mit Hilfe von Datumsfiltern eingrenzen.

Eine Nachricht abrufen „getMessage“

Das Abrufen von Nachrichten erfolgt mit Hilfe der Methode „getMessage“. Für das Abrufen der Nachricht muss die eindeutige Nachricht ID übergeben werden. Als Ergebnis erhalten Sie die  Nachricht als XML-Datei inklusive aller Dateianlagen. Die Dateianlagen werden ebenfalls mit der MTOM Technologie übertragen. Im gewünschten Ausgabe-Nachrichtenformat sollte  ein eindeutiger Bezug zwischen den übertragenen Anlagen in der Nachricht hergestellt werden können (Beispiel: XBau „referenzPrimaerdokument“). Außerdem können individuelle Anpassungen (z. B. an Dateinamen oder anderen Kennzeichen) im Nachrichten Format vereinbart werden.

Interne Funktion: Quittierung der Abholung

Das Abrufen einer Nachricht via „getMessage“ wird im System vermerkt (quittiert). Wird die Methode „queryMessage“ anschließend aufgerufen, ist die gerade abgeholte Nachricht ID nicht mehr im Ergebnis enthalten.

Kennt das Fachverfahren die Nachrichten ID bereits, kann es die Nachricht jedoch jederzeit via „getMessage“ abholen.

Versionierung

Die Schnittstelle wird versioniert. Es gibt einen Schnittstellenvertrag, eine einmal eingeführte Schnittstelle wird nicht gebrochen. Änderungen an einer Schnittstelle erfordern eine neue Version. Wird eine Version abgekündigt, gilt eine Übergangsfrist von 24 Monaten. Abweichungen vom Schnittstellenvertrag kann es nur durch geänderte gesetzliche Vorgaben geben.

Programmierbeispiele

Code Beispiele sowie lauffähige Demo Client-Implementierungen in verschiedenen  Programmiersprachen wie z.B. Java, C# oder PHP finden Sie unter: https://git.brain-scc.de/vorgangsraum/api
Benötigen Sie darüber hinaus Beispiele in anderen Programmiersprachen, wenden Sie sich gerne an uns.

Testumgebung

Wenn Sie als Fachverfahrenshersteller die Schnittstelle implementieren möchten, dann stellen wir gern einen konkreten Endpunkt zur Verfügung. Kontaktieren Sie uns bitte dazu.

Beispiele für XÖV Nachrichten

Zum Beispiel findet man auf der Projektseite Digitale Baugenehmigung konkrete Beispiele für XBau-Nachrichten.