Download

SZR Onlineschnittstelle

🟢 TLP:GREEN Das Dokument darf innerhalb der Organisation und an Partner frei weitergegeben werden, aber nicht veröffentlicht werden.

Erzeugt am: . Die jeweils aktuellste Fassung ist hier verfügbar.

Allgemeines

Das SZR ist ein Web-Front-End zum Zentralen Melderegister (ZMR) und Ergänzungsregister natürlicher Personen (ERnP), um bereichsspezifische Personenkennzeichen (bPK) berechnen zu können.
Um Zugriff darauf zu erhalten, muss man im BMI-Portal für die jeweilige Umgebung des SZR berechtigt sein und die passenden Rollen für die jeweilige Operation haben.

Es wird eine moderne JSON HTTP/REST API angeboten, als auch eine legacy SOAP API angeboten, welche keine neuen Features mehr erhalten wird. Neue SZR Benutzer werden ausschließlich auf der REST API angebunden.

Es erfolgt keine Speicherung personenbezogener Daten in der Anwendung, sondern es wird mit personenbezogenen Daten lediglich eine Suche im ZMR und ERnP gemacht. Wenn diese Suche ein eindeutiges Ergebnis liefert, so wird die Stammzahl der gefundenen Identität anhand ihrer Basiszahl im ZMR oder ERnP berechnet und daraus ein oder mehrere bPKs abgeleitet.

Ansprechpartner

Verantwortlich für das SZR und ERnP

Stammzahlenregisterbehörde

Zuständigkeiten:

Technischer Ansprechpartner beim technischen Dienstleister

Bundesministerium für Inneres
Sektion IV – IT und Service
Direktion für Digitale Services
Abteilung 11 – IKT Anwendungen
Referat b – Verwaltungsanwendungen

Zuständigkeiten:

Rechtliche Grundlagen

Als Rechtsgrundlage dient das E-Government-Gesetz in Verbindung mit der Stammzahlenregisterbehördenverordnung sowie der Ergänzungsregisterverordnung in den jeweils gültigen Fassungen.

Voraussetzung für die technische Freischaltung des Webservices in einer bestimmten Rolle ist ein genehmigter Antrag auf Ausstattung einer Datenverarbeitung mit bPK.

Ein Antrag auf bPK-Ausstattung kann jederzeit online erfolgen. Dazu muss man sich mittels eID unter folgendem Link einloggen: BürgerPortal.

Sollte kein eID bzw. kein Äquivalent zur Verfügung stehen, kann ein Antrag ebenso per Mail an bmi-ikt-szr-postfach@bmi.gv.at übermittelt werden.

Dazu sind entsprechende Formulare für bPK und vbPK unter folgendem Link vorhanden: Formulare Stammzahlenregisterbehoerde.

Fragen zur Antragstellung sind in diesem Fall ebenso an bmi-ikt-szr-postfach@bmi.gv.at zu richten.

Am Ende des Antragsprozesses wird das BMI per Mail über den genehmigten Antrag informiert und es folgt die technische Umsetzung.

Nutzungsbedingungen

Grundsätzlich dürfen Abfragen nur sequentiell und nicht parallel abgesetzt werden, um die Last aus SZR Sicht berechenbar zu halten.

Es sollten immer listenbasierte Operationen wie bpk/suche (REST) oder GetBpks (SOAP) genutzt werden, da die gesamte Ausstattung dann nur einen Bruchteil der Zeit einer Ausstattung mit der Einzeloperation GetBpk in Anspruch nimmt.

Es ist typischerweise optimal 100 Suchdaten pro Request zu schicken:

Umfangreiche Ausstattungen

Für größere Mengen an auszustattenden Daten (mehrere 10.000 bPK in einem kurzen Zeitraum) ist immer eine koordinierte Vorgehensweise erforderlich. Dazu bitte den oben erwähnten technischen Ansprechpartner kontaktieren.

Vorab: Normalerweise sind solche Abfragen Mo-Fr 17 Uhr bis 6 Uhr früh bzw Sa-So ganztags durchzuführen. Gegebenenfalls ist eine asynchrone BATCH-Verarbeitung in einfacher tabellarischer Form (Comma Separated File) ein geeigneteres Mittel für diesen Usecase.

Verwendung von Testidentitäten

Aufgrund des unverhältnismäßig hohen Administrationsaufwandes individualisierter Testidentitäten in der Produktivumgebung werden grundsätzlich keine Testidentitäten auf User-Wunsch erzeugt.

Es existieren definierte Testidentitäten in allen Betriebsumgebungen, welche in der Datei testdaten.csv im Schnittstellenpaket enthalten sind. Anhand dieser bereitgestellten Identitäten können User alle gängigen Usecases im Zuge der Implementierung testen.

Achtung: Diese Personen sind nur für lesende Tests gedacht und dürfen unter keinen Umständen geändert werden! Es sollten bei neuen Personen nie ähnliche Namen vergeben werden, damit sich das Testverhalten (z.B. Ergebnislisten bei Suchen) mit diesen Personen nicht unerwartet ändert.

Support Anfragen

Insbesondere technischer Support kann nur gewährleistet werden, wenn bei der Problem Meldung zumindest der HTTP Request Inhalt/Payload (besser auch HTTP Header und URL), die betroffene Betriebsumgebung und der exakte Anfragezeitpunkt mitgeteilt werden.
HTTP Response Informationen sind ebenfalls hilfreich (zur Überprüfung ob der so aus dem SZR rausgegeben wurde oder z.B. am Weg über diverse HTTP Proxy oder Portal Server verändert wurde).

Sollten diese Informationen nicht bereitgestellt werden können oder stattdessen lediglich Screenshots von Fehlermeldungen, Code-Auszüge und dergleichen aus den User-eigenen Implementierungen übermittelt werden, kann Support nur sehr eingeschränkt angeboten werden.

Verbindlichkeit

Durch Implementierung bzw. Anbindung an die SZR-Schnittstelle und Partizipation im Portalverbund stimmt die jeweilige Organisationseinheit in fachlicher Hinsicht und Softwareentwickler sowie Softwaretester im entsprechenden Ausmaß, den oben beschriebenen Nutzungsbedingungen zu.

Sollte grobes Zuwiderhandeln in einem Ausmaß festgestellt werden, welches den reibungslosen Betrieb des SZR und nachgelagerter Systeme entgegensteht, so wird dieser Umstand dem Verantwortlichen für das SZR zur weiteren geeigneten Veranlassung zur Kenntnis gebracht.

Zugriff über den Portalverbund

Das SZR ist ein Webservice hinter dem BMI Portal, weshalb Abfragen über den Portalverbund gemacht werden müssen. Weiterführende Informationen.

Für den Zugriff muss man im BMI-Portal für die jeweilige Umgebung des SZR berechtigt sein und die passenden Rollen für die jeweilige Operation haben.

URL

Nachdem das SZR über das Portal aufgerufen wird ist die Zusammensetzung der URL dynamisch. Grundsätzlich sieht die URL so aus:

URL Bestandteile

PVP Header

Das SZR erfordert als Portalapplikation die typischen PVP Header + Chained PVP Header des Ursprungsusers.
Die Funktionsweise von PVP kann in der PVP 1.9 Dokumentation nachgelesen werden

Die Toplevel PVP Header werden normalerweise vom Portal angehängt, bei dem sich die Clientapplikation via Client-Zertifikat authentifiziert hat. Sobald ein Request im Portal ankommt, hängt es automatisch die zum Zertifikat hinterlegten PVP Header der Clientapplikation an den Request an und leitet ihn weiter.

Die Chained PVP Header müssen hingegen auf jeden Fall von der Clientapplikation selbst mitgeschickt werden (weil das Portal nicht weiß, wer der Ursprungsuser des jeweiligen Requests war).

PVP Chained Header

Laut Portal Verbund Protokoll ist es wichtig den Ursprungsuser zu erkennen und durch die gesamte Aufrufkette an Applikationen durchzureichen, damit auch die letzte Applikation in der Kette weiß, welcher menschliche User den Request ursprünglich ausgelöst hat.

Daher muss die Clientapplikation (welche das SZR aufruft) die PVP Daten des Ursprungsusers an das SZR weiterleiten. Wenn die Clientapplikation selbst hinter dem Portal liegt, sollten die PVP Daten des Ursprungsusers ebenfalls in Form von eingehenden PVP Headern vorliegen welche an den SZR Request angehängt werden können. Das jeweilige Portal leitet dann den untersten PVP User in der Chain an das SZR weiter.

Möglicherweise ist ein Transformationsschritt nötig, damit die Clientapplikation die eingehenden Daten an das SZR weiterleiten kann:

Die Daten des Ursprungsusers (=die PVP Chain) sind für das SZR besonders wichtig, weil damit das dahinterliegende Register (ERnP oder ZMR) protokolliert, wer schlussendlich die Suche bzw Operation abgesetzt hat.

Beispiele für das Weiterleiten der Chain sind weiter unten in dieser Dokumentation.

bPK Konzept

Eine bPK (bereichsspezifische Personenkennzeichen) ist eine eindeutige Identifikation für eine Person und einen Bereich.

Um eine bPK zu berechnen, wird eine Anfrage an das SZR übermittelt, welches mit den angegebenen Suchdaten eine Suche im ZMR und im ERnP durchführt.
Führt diese Suche zu einem eindeutigen Ergebnis, wird die Basiszahl (= ZMR-Zahl bei ZMR Personen und Ordnungsnummer bei ERnP Personen) der Person zu einer bereichsunabhängigen Stammzahl verschlüsselt und anschließend um den Bereich ergänzt und mittels mathematischer Einwegfunktion (Hashfunktion) zur bPK umgewandelt. Daraus ergibt sich, dass eine bPK nicht auf eine Person rückführbar ist.

Außerdem können bPKs auch verschlüsselt (als vbPK) beim SZR abgefragt werden. Das macht man normalerweise, wenn man nicht selbst mit der bPK arbeitet, sondern diese an einen Dritten weiterleitet. Die Verschlüsselung erfolgt mit dem öffentlichen Schlüssel (Zertifikat) der Empfängerapplikation. Nur diese ist mit Ihrem privaten Key in der Lage die vbPK zu entschlüsseln, um dann das unverschlüsselte bPK zu erhalten.

Achtung: bPKs aus der Produktions-Umgebung unterscheiden sich immer von bPKs anderer Umgebungen, selbst wenn sie zur exakt gleichen Person ausgestellt werden. Darum spricht man hier von PROD-bPKs und in anderen Umgebungen (e, t, a, b) von TEST-bPKs

VKZ

Das Verwaltungskennzeichen (kurz: VKZ) ist ein, einer Organisationseinheit der öffentlichen Verwaltung zugeordnetes, eindeutiges Identifikationszeichen.

Bereich

Nach einem genehmigten Antrag auf Erstausstattung mit bPKs durch die Stammzahlenregisterbehörde wird im Stammzahlenregister für ein bestimmtes Verwaltungskennzeichen (VKZ) die Abfrage einer unverschlüsselten bPK des der Datenanwendung zugeordneten Bereichs lt. Bereichsabgrenzungsverordnung ermöglicht.
Das SZR prüft, ob das VKZ für den gewünschten Bereich die bPK anfragen darf.

Eine unverschlüsselte bPK bleibt für eine Person innerhalb eines Verwaltungsbereiches immer gleich und ist immer 28 Zeichen lang. Unverschlüsselte bPK dienen wie bereits erwähnt, der Speicherung und Verwendung bei der ausgestatteten Organisation und sind nicht dafür vorgesehen, an Dritte weitergegeben zu werden (um sie beispielsweise als „gemeinsamen Identifier“ zu verwenden).

Details über die Berechnung einer bPK können unter folgendem Link nachgelesen werden: Bereichsspezifische Personenkennzeichen (bPK)

Bereichskennung

Eine bPK gehört immer zu einem Bereich der via Bereichskennung eindeutig identifiziert werden kann.
Die Bereichskennung gibt es als Langform inkl Präfix (z.B. urn:publicid:gv.at:cdid+ZP oder urn:publicid:gv.at:ecdid+BBA-STA+AS) oder als Kurzform (z.B. ZP oder BBA-STA+AS)

Präfix einer nicht privaten Bereichskennung

urn:publicid:gv.at:cdid+

Bsp: urn:publicid:gv.at:cdid+ZP für den Bereich "zur Person"

Präfix einer privaten Bereichskennung

urn:publicid:gv.at:wbpk+

Zusammen mit der Registerkennung und der Registernummer (z.B. Firmenbuchnummer) ergibt sich die vollständige Bereichsangabe.

Bsp: urn:publicid:gv.at:wbpk+XFN+1234i für das Firmenbuch oder urn:publicid:gv.at:wbpk+XZVR+1234 für das Vereinsregister

Präfix einer verschlüsselten Bereichskennung

urn:publicid:gv.at:ecdid+ bzw. urn:publicid:gv.at:ewbpk+

Der Präfix entspricht der jeweiligen unverschlüsselten Variante, hat aber ein e vorangestellt.

Nach dem Präfix folgt das Verwaltungskennzeichen (VKZ) und der Bereich. Als Trennzeichen dient dabei jeweils ein + (Plus).

Bsp: urn:publicid:gv.at:ecdid+BBA-STA+AS für eine verschlüsselte bPK der Statistik Austria mit dem VKZ BBA-STA und dem Bereich AS für Amtliche Statistik oder urn:publicid:gv.at:ewbpk+XFN-12345i+XFN+12345i für eine verschlüsselte wbpk

Achtung: Fragt man über SOAP verschlüsselte Bereiche ab, nutzt man das <Target> Element, welches das Ziel-VKZ und den Ziel-Bereich mit unverschlüsseltem Bereichspräfix spezifiziert! An anderen Stellen (z.B. im SOAP Response oder bei vBpks als Identification) wird jedoch wie üblich das verschlüsselte Präfix genutzt

Verschlüsselte bPKs (vbPK)

Verschlüsselte bPKs sind ohne Entschlüsselung nicht direkt verwendbar. Sie werden abgefragt und später an ein Ziel (z.B. eine andere Organisation) weitergeleitet, wo sie entschlüsselt und verwendet werden können.

Fragt man eine bestimmte VKZ+Bereich Kombination vom SZR mehrfach ab, kommt immer eine andere vbPK zurück, selbst wenn nach der Entschlüsselung dieselbe bPK enthalten ist.

Es handelt sich daher um eine Transportverschlüsselung, die sicherstellt, dass nur das Ziel mit der vbPK als Identifier arbeiten kann, nicht jedoch die Organisation welche die vbPK vom SZR erhalten hat

Damit das SZR bPKs für eine bestimmte Kombination aus VKZ und Bereich verschlüsseln kann, muss im SZR zuvor ein entsprechendes Verschlüsselungszertifikat für diese Kombination hinterlegt worden sein.

Achtung: Das VKZ als Teil eines "verschlüsselten Bereichs" ist somit essentiell, weil es festlegt, wer der Empfänger der vbPK ist. Nur dieser kann die vbPK auch entschlüsseln. Spricht man von einer "verschlüsselten ZP bPK" ist die Aussage somit unvollständig. Korrekt wäre "die für BMI verschlüsselte ZP bPK" oder "die verschlüsselte BMI+ZP bPK"

Schlüssellänge des Zertifikats

Die Verschlüsselung von bPKs passiert mittels RSA-Verfahren mit OAEP-Padding.

Neue Zertifikate müssen nach Stand der Technik als 4096bit Public-Zertifikat im PEM-Format erstellt werden und anschließend als Textdatei via Mail an bmi-ikt-szr-postfach@bmi.gv.at übermittelt werden.

Sofern Schlüsselmaterial bereits länger im SZR gespeichert ist, ist davon auszugehen, dass zum Hinterlegungszeitpunkt der Schlüssel mit einer Länge dem damaligen Stand der Technik entsprechend hinterlegt wurde (Mindestlänge sind 1024bit). Auf diesen Umstand sollte aus technischer Perspektive frühzeitig Rücksicht genommen werden.

Die Länge einer vbPK ist abhängig vom verwendeten Schlüssel.

Bestandteile einer entschlüsselten vbPK

Sobald man eine vbPK entschlüsselt bekommt man z.B. folgendes Ergebnis:
V1::urn:publicid:gv.at:cdid+T1::MxK82jxY9+vZg/25J44lMNg+FJY=::2025-02-25T14:12:44
oder allgemeiner gesagt
V1::<Bereich>::<bPK>::<Verschlüsselungszeitpunkt>

Dabei handelt es sich um einen String der mehrere Bestandteile enthält, die mit :: getrennt werden

Achtung: Wie erwähnt sind 2 abgefragte vbPKs niemals gleich. Das liegt einerseits daran, dass der Verschlüsselungszeitpunkt in der vbPK enthalten ist, anderseits daran, dass das OAEP-Padding blockorientiert arbeitet und fehlende Zeichen auf die Blocklänge durch zufällig Werte auffüllt.

Java Beispielcode um vbPKs zu entschlüsseln

Als Orientierungshilfe ist hier ein Java-Beispielcode wie vom SZR gelieferte vbPKs typischerweise entschlüsselt werden können:

KeyStore keystore = KeyStore.getInstance("JKS");
try (InputStream stream = new FileInputStream("C:/fremdbpks.jks")) { // Pfad zu JKS mit dem Key zum Entschlüsseln
    keystore.load(stream, "kspw".toCharArray()); // kspw muss durch das Keystore Passwort ersetzt werden
}
PrivateKey key = KeyFactory.getInstance("RSA").generatePrivate(new PKCS8EncodedKeySpec(keystore.getKey("alias", "pw".toCharArray()).getEncoded())); // alias ist der Alias des Keys im Keystore und pw das Passwort
Cipher ci = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
ci.init(Cipher.DECRYPT_MODE, key);
String vbpk = "fvm+zz/XXu5KzRz3d7IdQc5RNqICQYI9qg...4kCYkr53HTWWrKF2Q==";
String bpk = new String(ci.doFinal(Base64.getDecoder().decode(vbpk)), StandardCharsets.UTF_8);

Beispielsuche + Ergebnisse

Fragt man z.B. mit folgenden Personendaten:

bPK BF-FO (28 Zeichen)
wGZUpYj8rz7XNxVCYtDlN0lK24Y=
vbPK BBA-STA+AS (172 Zeichen)
R4LUrsRoiWqIsMAYDnbsMxo528R3U87Aa80+KcOWHsEphcx3OOXlEaO034RsQBLLJFR+dM1bWhityc/8QBtD59BwXnY0NxFs0go0Uy+cx0GmGNY1lQVg24cu40azxtQ9VAil4Z+EmRLoyjz9ASkDcQxkGY1FukB3maJl3qw6B2M=
Beispiel einer anderen vbpk mit 4096bit Key (684 Zeichen)
wW00S7Biy23G31pE3dDjfQ8sjDdDJ1NgrKTgwQ+tJnLKph/pxKd0xmhxLlN/3qCpivqBwo93cHeL37fIq/rwVQV2q4Th/QziOOF/kcEUbSVEmjon4naXTm8OythtKg1JAs/23dqhpfuLW8P4nhsVQlFGvzGKsFB2FaaJJHk9NeCpoNhfx3L0V+17mJOuR+X0l+1bTyFBeFLbdE69QeCeVLtj5wUPiWW/LqOL62kjOgEp6XdwZsDT+WyUqcx18bpcjG5vOMjH671G5sqK6fVbZxyJY3GHsS3UBLtwn8KPxivKbAZq1PDVCXHqQS7mwJoRo5m18k7kFomNLGVDs0JePXAXhy7+Ewh29PlvzdwNuZr/aMZ/0/L5mzS8v/pOFwBIAj12fGdbNd6dZ7pcTYQLHIatJCJmnHCq/h8hP6MAzmgh/IihZbbkU6u9xxe6skqyR1LGOeDWwTGSUuUp9Om8p8dwGBYv5FQlEGjFx0m8H86w2qgpQLS5uNXUdrSTKHO0TI5vUgg9q7L4Xy3EVMQfWZJkZil+TyhWrEAMQ+tEE+0XDHY1glNhbHMrsLxVvRsrUBmtlRYzOy5+nLFX4MQGBOuelJJqaoT2ospdI0nTG0DYLL3SIdietymzHSz5OiftUI0pCiTqJFasX9AFygzxs0bHQddXrQLcC3oEv7l4H3Y=

bPKs bei Kitfällen (=zusammengeführte Personen)

Normalerweise ändert sich die bPK einer Person nicht, weil sie auf ihrer ZMR-Zahl bzw Ordnungsnummer basiert und diese unveränderbar ist.

Allerdings bieten das ZMR und ERnP eine Funktion um 2 Personen zusammenzuführen (=zu kitten). Das kann z.B. aufgrund der Bereinigung einer Doppelanlage sein.
Dabei wird eine Person (=Quellperson) auf eine andere Person (=Zielperson) zusammengeführt. Die Zielperson kann danach als Quellperson weiterer Kit-Operationen dienen.

Sucht man danach im SZR mit Daten der Quellperson, wird diese gefunden und über die Kitverfolgung zur finalen Zielperson verfolgt für die dann bPKs berechnet und ausgeliefert werden. Diese unterscheiden sich von bPKs der Quellperson nach der eigentlich gesucht wurde.

Beispiel eines zeitlichen Ablaufs:

  1. Am 3.3. liefert das SZR zur gesuchten Person eine bPK
  2. Am 5.3. wird diese Person im ZMR auf eine andere Person zusammengeführt
  3. Am 10.3. wird die SZR Abfrage mit identen Suchdaten vom 3.3. durchgeführt, liefert jetzt eine andere bPK wie am 3.3. (nämlich die der Zielperson)

bPK als Identification

Schickt man eine bPK der Quellperson als Identification, funktioniert das weiterhin und auch hier gehören die vom SZR returnierten bPKs zur Zielperson.
D.h. wenn man eine bPK als Identification schickt, kann im Response eine andere bPK (die der Zielperson) stehen.

Schnittstellendokumentation

Im Folgenden werden allgemeine Schnittstellen-Konzepte erklärt.
Zusätzlich kann ein Schnittstellenpaket angefordert werden, welches eine technische Schnittstellendokumentation enthält.

Achtung: Die SZR Version ist nicht an die Version (=Erstellungszeitpunkt) dieser Dokumentation oder des Schnittstellenpakets gekoppelt.

Indem man sich an die folgenden Best Practices für Clients hält, stellt man sicher, dass fast alle SZR Releases keine Auswirkung auf den eigenen Client haben und dieser unverändert weiter läuft.

Rückwärtskompatibilität

Grundsätzlich werden Schnittstellenänderungen im SZR sofern es möglich ist, immer rückwärtskompatibel gestaltet. Neue Funktionen/Inhalte werden daher gegebenenfalls hinter neue optionale Request Parameter gelegt, sodass sie nur bei Bedarf abgefragt werden.

Die häufigste rückwärtskompatible Änderung, ist das Hinzufügen neuer Felder im Response. Daher ist wichtig, dass Clients Responses nicht zu strikt parsen und unbekannte Felder ignorieren!

Falls z.B. aufgrund gesetzlicher Anforderungen wie der Meldegesetznovelle doch rückwärtsinkompatible Änderungen nötig werden, wird das rechtzeitig über den SZR RSS Feed angekündigt und diese Dokumentation angepasst.

Best Practices für Clients

Wichtig für die Stabilität von Clients ist, dass sie sich an Postel’s Law (=Robustness Principle) halten:
Be conservative in what you do, be liberal in what you accept from others

Anders gesagt: Bei Requests an das SZR möglichst strikt an die SZR API Spec halten, Responses aber möglichst tolerant parsen.

Somit vermeidet man proaktiv Probleme durch zukünftige SZR Anpassungen und stellt sicher, dass auch Clients die aus veralteten OpenAPI Specs generiert wurden, problemlos weiter funktionieren.

Die Umsetzung der Meldegesetznovelle zeigt Beispiele, wieso eine tolerante Responseverarbeitung sinnvoll ist:

  1. neue Geschlecht-Werte für die existierende Geschlecht-Enum: Das SZR bildet enums in Responses immer als string ab (wegen der Erweiterbarkeit). Clients müssen die Werte fehlertolerant parsen, d.h. auch heute invalide Werte müssen verarbeitet werden. Siehe Abschnitt Enumerations
  2. neue Felder wie "Sonstiger Name": Clients müssen unbekannte Felder im Response ignorieren, damit es keine Probleme gibt wenn das SZR die Schnittstelle erweitert.
  3. Felder die von Einzelelementen zu Listen werden wie Anschrift: XML hat den Vorteil, dass eine Liste mit 1 Element genauso aussieht wie ein einzelnes Element. Bei JSON kommen in dem Fall Array-Klammern hinzu was nicht rückwärtskompatibel ist. Daher empfiehlt es sich bei Jackson DeserializationFeature.UNWRAP_SINGLE_VALUE_ARRAYS zu aktivieren. Dadurch wird ein Array mit 1 Element so behandelt wie ein Element ohne Array-Klammern. Das SZR kann dann in einer Übergangsphase garantieren, dass die Liste nur 1 Element enthält, was Clients Zeit zur Umstellung gibt. Der umgekehrte Fall (Listen zu Einzelelement) erfordert die Aktivierung von DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY. Dann gibt es kein Problem, falls im JSON Array-Klammern fehlen.

Zusätzlich sind folgende Regeln sinnvoll für die Robustheit von Clients:

Enumerations

Im SZR werden echte enumerations nur genutzt, wenn sie ausschließlich in Requests vorkommen. Sobald eine enum im Response vorkommt, wird sie immer als String abgebildet (man kann nie 100%ig garantieren dass keine neuen Werte dazukommen).

Wichtig ist, dass Clients, welche die enum Werte verarbeiten, auch mit heute noch unbekannten Werten umgehen können (also z.B. nicht abstürzen weil ein heute noch unbekanntes Geschlecht retour kommt)

In der OpenAPI Dokumentation werden solche enums als x-extensible-enum abgebildet (ist eine relativ verbreitete OpenAPI Extension für den Usecase). Bsp:

"geschlecht" : {
  "type" : "string",
  "x-extensible-enum" : [ "Männlich", "Weiblich", "Unbekannt", "Inter", "Divers", "Offen", "Keine Angabe" ]
},

REST als Alternative zu SOAP

Weil SOAP APIs nicht mehr dem aktuellen Stand der Technik entsprechen, bietet das SZR auch eine moderne REST API an.

Folgende Verbesserungen wurden umgesetzt:

  1. SOAP + XML wird durch HTTP + JSON ersetzt. Damit wird der HTTP Payload viel kompakter und damit performanter. Potentielle Probleme durch wechselnde Namespaces werden umgangen und der Payload wird besser für Menschen lesbar.
  2. Das PVP Handling bzw Chaining ist ohne SOAP einfacher, weil man mit simplen HTTP Headern arbeitet anstatt komplexe PVP SOAP XML Strukturen verarbeiten zu müssen
  3. Statt der englischsprachigen Feldnamen werden die üblichen deutschen Begriffe verwendet (z.B. Gemeinde statt Municipality). Es gibt auch keine Übersetzung von Feldinhalten mehr (z.B. male vs männlich)
  4. Die JSON Struktur und Feldnamen sind an das ERnP angelehnt, wodurch insbesondere SZR Nutzer die gleichzeitig ERnP Nutzer sind, von der bekannten Datenstruktur profitieren (natürlich ist das Format nicht 1zu1 gleich, aber überall wo es möglich und sinnvoll ist)

Aufgrund der umfangreichen, listenbasierten Suchdaten, nutzt die REST API für die /bpk/suche Operation HTTP POST.
HTTP GET würde keinen Payload ermöglichen und wäre daher nicht praktikabel.

HTTP Header

Folgende Header können für Metadaten im Rahmen von REST API Aufrufen genutzt werden

Request-Header

Neben den zuvor erwähnten PVP HTTP Headern für die Token-Chain, können folgende 2 Header geschickt werden, um mögliche Fehleranalysen zu vereinfachen:

Response-Header

Der Response liefert einige nützliche SZR-spezifische HTTP Header:

Operationen

Das REST OpenAPI File bietet genau 1 Operation welche die PVP Rolle SZR-BPK-Abfrage benötigt.

Das SZR.wsdl listet einige Operationen auf, wovon jedoch meist nur folgende 3 relevant sind:

Anfrageinformationen

Das SZR darf eine bPK zu einer Person nur dann ausliefern, wenn diese eindeutig identifiziert wurde.
Zur Identifizierung einer Person müssen Vorname und Familienname, sowie ein 3. Kriterium (siehe Tabelle unten) übermittelt werden.

Aus technischen Gründen wird empfohlen ein möglichst eindeutiges 3. Kriterium zu wählen. Eine gute Wahl ist das Geburtsdatum, eine schlechte Wahl ist das Geschlecht.

Achtung: Sofern vorhanden sollte das Geburtsdatum immer mitgeschickt werden, auch im Falle der Suche mit bPK als Identification.

Tabellarische Übersicht der Anfragekriterien

Folgende Tabelle beschreibt die relevanten Personendaten-Felder in verschiedenen SZR APIs (REST, SOAP, BPK Batch).
Hinter Anschrift kann neben einer ERnP Anschrift auch eine ZMR Meldung stecken.

Die Spalte Information ergänzt relevante Informationen zum Feld im Rahmen des Suchablaufs:

Beschreibung Feldname in REST API Feldname in SOAP API (SZR.wsdl) BPK Batch Spalte Information
Familienname familienname Person.Name.FamilyName NACHNAME suchbar, Pflichtfeld für Suche
Vorname vorname Person.Name.GivenName VORNAME suchbar, Pflichtfeld für Suche
Name vor Ehe nameVorEhe Person.AlternativeName.FamilyName NAME_VOR_ERSTER_EHE suchbar
Sonstiger Name Person.AlternativeName.SonstigerName SONSTIGER_NAME nur für Insert
Geburtsdatum geburtsdatum Person.DateOfBirth GEBDATUM suchbar, 3. Suchkriterium (auch wenn teilbefüllt)
Geburtsort geburtsort Person.PlaceOfBirth GEBORT suchbar, 3. Suchkriterium
Geburtsstaat geburtsstaat.isoCode3/name (/ bedeutet und/oder) Person.CountryOfBirth GEBSTAAT suchbar (ISO3 oder Name), 3. Suchkriterium
Geschlecht geschlecht Person.Sex GESCHLECHT suchbar, 3. Suchkriterium
Staatsangehörigkeit geburtsstaat Person.Nationality STAATSANGEHÖRIGKEIT suchbar (ISO3 oder Name), 3. Suchkriterium
Anschrift ISO3 Code anschrift.staat.isoCode3/name RegularDomicile.StateCode3 ANSCHRIFTSSTAAT suchbar
Anschrift Gemeinde anschrift.gemeinde RegularDomicile.Municipality GEMEINDENAME suchbar, 3. Suchkriterium
Anschrift Ort(schaft) anschrift.ort RegularDomicile.Locality ORT suchbar, 3. Suchkriterium
Anschrift Postleitzahl anschrift.postleitzahl RegularDomicile.PostalCode PLZ suchbar, 3. Suchkriterium
Anschrift Straße anschrift.strasse RegularDomicile.DeliveryAddress.StreetName STRASSE suchbar, 3. Suchkriterium
Anschrift Hausnummer anschrift.hausnummer RegularDomicile.DeliveryAddress.BuildingNumber HAUSNR suchbar, 3. Suchkriterium
Anschrift Stiege anschrift.stiege RegularDomicile.DeliveryAddress.Unit STIEGE suchbar, 3. Suchkriterium
Anschrift Tür anschrift.tuer RegularDomicile.DeliveryAddress.DoorNumber TÜR suchbar, 3. Suchkriterium
Anschrift Adresszusatz RegularDomicile.DeliveryAddress.AddressLine nur für Insert
Reisedokument Nummer reisedokument.nummer TravelDocument.DocumentNumber DOKUMENTENNR suchbar, kein Mehrfachtrefferkrit
Reisedokument Art reisedokument.art TravelDocument.DocumentType DOKUMENTART suchbar, kein Mehrfachtrefferkrit
Reisedok.Ausstelldatum reisedokument.ausgestelltVon.datum TravelDocument.IssueDate AUSSTELLUNGSDATUM suchbar, kein Mehrfachtrefferkrit
Reisedok.Ausstellbehörde reisedokument.ausgestelltVon.behoerde TravelDocument.IssuingAuthority AUSSTELLUNGSBEHÖRDE suchbar, kein Mehrfachtrefferkrit
Reisedok.Ausstellstaat reisedokument.ausgestelltVon.staat.isoCode3/name TravelDocument.IssuingCountry AUSSTELLUNGSSTAAT suchbar, kein Mehrfachtrefferkrit
ID der Person id.type+value (beide Pflicht) Person.Identification.Value+Type (beide Pflicht) ID_BPK_<BEREICH> suchbar, 3. Suchkriterium

Namenssuche

Doppelnamen wie „Karl-Heinz“ gelten als ein Vorname. Mehrfachnamen wie „Karl Heinz“ gelten als zwei Vornamen.

Beispiel: Es gibt im ZMR „Hans“ „Hans Peter“, „Hans-Peter“ und „Hans Peter Josef“

Hier die gefundenen Personen, wenn jeweils der linke Wert gesucht wird:

Teilbefülltes Geburtsdatum

Beim Geburtsdatum besteht die Möglichkeit, nur mit Jahr oder nur mit Jahr und Monat anstelle eines vollständigen Datums zu suchen.

Bei SOAP Requests oder dem BPK Batch kann in dem Fall der Tag bzw. das Monat weggelassen oder mit 00 befüllt werden.


Die REST API hat separate JSON Felder für jahr, monat, tag. Weiß man den Tag bzw Monat nicht, lässt man die Felder einfach weg. Ein Feld mit 0 befüllen ist nicht erlaubt! Bsp: statt 1980-01-00 schickt man folgendes JSON:

"geburtsdatum": {
  "jahr": 1980,
  "monat": 1
}

Häufige Gründe für Nicht-Treffer

Personendaten im Ergebnis

Das SZR-Webservice liefert bei privaten Organisationen in keinem Fall Personendaten. Bei behördlichen Nutzern können Personendaten retour kommen, sofern die Suche kein eindeutiges Ergebnis, aber auch nicht mehr als 3 Treffer liefern würde.

Fehlerbehandlung

REST

Die REST API nutzt die üblichen HTTP Statuscodes (4xx für Client-Fehler, 5xx für Server-Fehler) und teilt sich die SZR spezifischen Fehlercodes mit der SOAP API.

Bsp wenn das JSON im Request invalide ist, wird HTTP Status 400 und SZR F438 returniert:

{
  "type": "urn:SZR:F468",
  "title": "HTTP payload invalid",
  "status": 400,
  "errors": [
    {
      "detail": "Unrecognized field 'vorname', not marked as ignorable at [line: 9, column: 8]",
      "pointer": "/suchdaten/0/vorname"
    }
  ]
}

Das JSON Format entspricht Problem JSON (RFC 9457) mit folgenden Regeln:

  1. type ist der SZR Fehlercode zur eindeutigen Identifizierung in Form eines URN (Uniform Resource Name)
  2. title ist der Fehlertext
  3. status dupliziert den vom SZR returnierten HTTP Status (falls ein Portal etc den Status nachträglich ändert, kann man hier den vom SZR returnierten Status sehen)
  4. errors ist ein optionales Array mit Details zum aufgetretenen Fehler.
    1. details eine genaue Beschreibung des aufgetretenen Fehlers
    2. Eines der folgenden Felder: pointer, parameter, header
      1. pointer ist ein JSON Pointer der auf die Stelle im Request JSON zeigt wo der Fehler aufgetreten ist
      2. parameter wird bei fehlerhaften URL Parmetern genutzt und beschreibt den Parameter-Namen
      3. header wird bei fehlerhaften HTTP Headern genutzt und beschreibt den Namen des Headers

SOAP

Das SZR hält sich an die SOAP Spezifikation für die Übertragung von SOAP über HTTP, welche vorsieht, dass jeder erfolgreiche Response den HTTP Statuscode 200 und jeder fehlerhafte Response den HTTP Statuscode 500 hat.

Im Inhalt der Fehlermeldung steht der SZR spezifischen Fehlercode und eine Nachricht die beschreibt, was passiert ist.

Bsp: wenn die Operation GetBPK zu den Personen-Suchdaten niemanden findet, wird HTTP Status 500 und SZR F230 "No person matched" returniert.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault xmlns:p344="urn:SZRServices">
         <faultcode>p344:F230</faultcode>
         <faultstring>No person matched</faultstring>
         <faultactor>urn:SZRServices</faultactor>
         <detail/>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Die XML-Struktur ist für alle Fehler gleich, wobei sich faultcode und faultstring je nach Fehlersituation ändern.

Der Part <faultactor>urn:SZRServices</faultactor> weist darauf hin, dass der Fehler vom SZR erzeugt wurde und nicht z.B. von einem Portalserver am Weg ins SZR.

Zum Vergleich, so würde z.B. ein Portalfehler beim Zugriff auf eine SOAP Schnittstelle aussehen, wenn man das Client-Certificate nicht korrekt konfiguriert hat:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:pvp="http://egov.gv.at/pvp1.xsd">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>pvp:F401</faultcode>
      <faultstring>Unauthorized (401) {0} (STP: )</faultstring>
      <faultactor>http://egov.gv.at/pvp1.xsd</faultactor>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

Der Aufbau ist sehr ähnlich, jedoch deutet <faultactor>http://egov.gv.at/pvp1.xsd</faultactor> in dem Fall auf das Portal hin. So ein Request kommt gar nicht bis ins SZR durch.

Achtung: manche Fehlercodes wie F445 gibt es sowohl im SZR als auch im Portal, daher muss unbedingt auf den faultactor geachtet werden! Die häufigisten Portalfehler sind:

SZR Fehlercodes

Folgende Fehlercodes werden vom SZR genutzt. Steht daneben (pro Person), wird der Fehlercode bei Listenoperationen beim jeweiligen Listenelement eingehängt anstatt den gesamten Response zu einem Fehler zu machen (Bsp dazu siehe weiter unten)

Schnittstellenpaket

Das Schnittstellenpaket enthält diverse Dateien:

REST

OpenAPI Specification

Die OpenAPI Specification ist ein Standard um HTTP REST APIs zu beschreiben (grob vergleichbar mit einem WSDL für SOAP APIs).

Falls Sie im Portal entsprechend berechtigt sind, kann für das SZR eine aktuelle OpenAPI Spezifikation mit HTTP GET auf [Portal-Domain]/at.gv.bmi.sz2-n-[Umgebung]/szr/rest/api/openapi/openapi.json abgerufen werden.

Aus diesem File kann man direkt Client Code generieren, siehe https://swagger.io/tools/swagger-codegen/ oder https://github.com/openapitools/openapi-generator

Eine mögliche Konfiguration um mit maven einen Java Client zu generieren, der Requests via Java11 HTTP Client schickt:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.15.0</version> <!-- mit der Version getestet, wenn möglich letzte Version nutzen -->
    <executions>
        <execution>
            <goals><goal>generate</goal></goals>
            <phase>generate-sources</phase>
            <configuration> <!-- siehe https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin -->
                <inputSpecRootDirectory>DIR_MIT_OPENAPI_FILE</inputSpecRootDirectory>
                <generatorName>java</generatorName>
                <output>${project.basedir}/src/generated/openapi</output>
                <configOptions> <!-- ggf können je nach Applikation weitere Settings sinnvoll sein siehe Doku -->
                    <useTags>true</useTags>
                    <disallowAdditionalPropertiesIfNotPresent>false</disallowAdditionalPropertiesIfNotPresent> <!-- lt Doku ist false korrekt und true nur aus rückwärtskompat der default -->
                    <hideGenerationTimestamp>true</hideGenerationTimestamp>
                    <library>native</library>
                    <openApiNullable>false</openApiNullable>
                    <useEnumCaseInsensitive>true</useEnumCaseInsensitive>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Achtung: In dem Fall wird Code generiert, der aus dem Response mit new String(byte[]) Strings erzeugt. Wenn im Response Sonderzeichen wie Umlaute enthalten sind funktioniert das nur korrekt sofern das Default Encoding des Systems auf UTF-8 gestellt ist (ist seit Java18 der Default). Vmtl ist das aktuell ein Bug im Codegenerator (korrekt wäre hier beim String immer explizit UTF-8 zu spezifieren).

Hinweis zur Rückwärtskompatibilität

Im Gegensatz zur Schnittstelle selbst, kann sich die Kombination OpenAPI File + Generatorplugin womöglich öfters rückwärtsinkompatibel ändern. Bsp:

SOAP

Die SOAP API wird über ein WSDL spezifiziert, welches genutzt werden kann um Teile eines SZR Clients zu generieren.
Zum Beispiel kann für Java die Apache CXF Hilfsmittel wsdl-to-java bzw mit Maven maven-cxf-codegen-plugin-wsdl-to-java nutzen.

Beispiele

REST

Weiterleiten der PVP Chain

Das folgende Beispiel bezieht sich nur auf PVP Header. In echten Requests würde man natürlich auch die in dieser Dokumentation beschriebenen SZR spezifischen Client-Header sowie Accept, Content-Type, ... Header schicken.

Für ein korrektes PVP Chaining müssen diese HTTP Header (=PVP Daten des Ursprungsusers) 1zu1 beim SZR Request mitgeschickt werden (die Werte a, b, c, ... sind natürlich nur simple Ersatzwerte für echte PVP Daten eines Users):

X-AUTHENTICATE-participantId: a
X-AUTHENTICATE-gvOuDomain: b
X-AUTHENTICATE-userId: c
X-AUTHENTICATE-cn: d
X-AUTHENTICATE-gvOuId: e
X-AUTHENTICATE-ou: f
X-AUTHENTICATE-gvGid: g
X-AUTHENTICATE-mail: h
X-AUTHENTICATE-gvSecClass: 2
X-Version: 1.8

Wenn diese Header im Portal ankommen, werden sie zu PVP-Chain-Headern umgewandelt (erkennbar am X-01- Prefix).

Außerdem ermittelt das Portal anhand des ebenfalls mitzuschickenden Client Zertifikats die PVP Daten und die möglichen Rollen der Clientapplikation (die Werte clientAppParticipantid, ... stehen stellvertretend für die im Portal hinterlegten Daten der Clientapplikation)

Schlussendlich kommen folgende PVP Header im SZR an, womit der Ursprungsuser bekannt ist und korrekt protokolliert (bzw an Folgeregister wie das ZMR weitergeleitet) werden kann.

X-AUTHENTICATE-participantId: clientAppParticipantid
X-AUTHENTICATE-gvOuDomain: clientAppGvOuDomain
X-AUTHENTICATE-userId: clientAppUserId
X-AUTHENTICATE-cn: clientAppCn
X-AUTHENTICATE-gvOuId:clientAppGvOuId
X-AUTHENTICATE-ou: clientAppOu
X-AUTHORIZE-roles: szr-bpk-abfrage
X-AUTHENTICATE-gvSecClass: 2
X-Version: 1.8
X-01-AUTHENTICATE-participantId: a
X-01-AUTHENTICATE-gvOuDomain: b
X-01-AUTHENTICATE-userId: c
X-01-AUTHENTICATE-cn: d
X-01-AUTHENTICATE-gvOuId: e
X-01-AUTHENTICATE-ou: f
X-01-AUTHENTICATE-gvGid: g
X-01-AUTHENTICATE-mail: h
X-01-AUTHENTICATE-gvSecClass: 2
X-01-Version: 1.8

bpk/suche mit wbpk und Identification

Folgende Abfrage:

Request

URL z.B. für A-Umgebung at.gv.bmi.sz2-n-a/szr/rest/api/bpk/suche
PVP und andere Header werden zwecks Übersicht weggelassen sind aber nötig

{
  "suchdaten": [
    {
      "id": {
        "type": "BMI+ZP",
        "value": "f4zoq1hBc0TIR/mkTqjQVFja6ao9UAN4HFzeSFiwSNWLMaJQuFQDGLIoq4KLgrs7CH1uHXLDz41KIIt80YrtmQbS38AFanvE49KLjpk/QG6708iKqJEy4iX9BAcoZLL3ShzQe9mhrMC3EwS6oHiFSgmi3TY6drXDJ3yKa23sEPI="
      },
      "personendaten": {
        "familienname": "XXXMuster",
        "vorname": "XXXMax xxx",
        "geburtsdatum": {
          "jahr": 1980,
          "monat": 1,
          "tag": 1
        }
      }
    }
  ],
  "vkz": "XFN-12345i",
  "bereich": [
    "XFN+12345i", "XFN-12345i+XFN+12345i"
  ]
}

Im Response sieht man, dass die angeforderte unverschlüsselte wbPK WqKkLhjamiurkTBTiEEeYzhVQp4= ist und die verschlüsselte wbPK mAouBFZ8uMT3Jdfz76Bb...YMCA==

Response
{
  "ergebnis": [
    {
      "bpks": {
        "XFN+12345i": "WqKkLhjamiurkTBTiEEeYzhVQp4=",
        "XFN-12345i+XFN+12345i": "mAouBFZ8uMT3Jdfz7Tr6Bb31bbO3ee/qx8L4Bd76eMF59IsrBCP28h0s7IvdBuVL0tVCrs6N3wx7zKEWKeLJyT0I0xX6I96Iryjpni5pOdF/7QDDGzzBTYEKsF/xc/rJV6QZtPQoYHd/tMjbhsBjXWR7N9IfCeck4szl47kkbWPKo0jDsTRZjoPVOFiORmRJtJZiSlZCFg89QtAl/YKraHCXCMuf3vVzR2+LHl9g1+gxGYEhYv9lY/QCO4zeJcWM02dAGkqSr4g0PuDh30ChwMQyEZEJrHrUd4i4gxVesB8pLiwYa1XfHPcPvwotxWKl//8AA8wM8tLer4AMq8YMCA=="
      }
    }
  ]
}

bpk/suche mit ListMultiplePersons und AddGeprueftInfo und bpk Response

Dieses Beispiel zeigt 2 Optionen für behördliche Benutzer (werden via URL Parameter spezifiziert):

Wie man im Beispiel sieht: Wenn die Person eindeutig identifiziert werden kann, bekommt man nur die bPK(s) aber keine Personendaten. Die Geprüft Info steht trotzdem im Response.

Das Beispiel zeigt auch die gleichzeitige Suche nach 2 Personen.
Nachdem es eine Listenabfrage ist, dürfen personenbezogene Fehler nicht den gesamten Response zu einem Fehler machen, daher werden Fehler die mit den jeweiligen Suchdaten zu tun haben im jeweiligen Listenelement als fault returniert.

Request

URL z.B. für A-Umgebung at.gv.bmi.sz2-n-a/szr/rest/api/bpk/suche?ListMultiplePersons=true&AddGeprueftInfo=true
PVP und andere Header werden zwecks Übersicht weggelassen sind aber nötig

{
  "suchdaten": [
    {
      "id": {
        "type": "BMI+ZP",
        "value": "f4zoq1hBc0TIR/mkTqjQVFja6ao9UAN4HFzeSFiwSNWLMaJQuFQDGLIoq4KLgrs7CH1uHXLDz41KIIt80YrtmQbS38AFanvE49KLjpk/QG6708iKqJEy4iX9BAcoZLL3ShzQe9mhrMC3EwS6oHiFSgmi3TY6drXDJ3yKa23sEPI="
      },
      "personendaten": {
        "familienname": "XXXMuster",
        "vorname": "XXXMax xxx",
        "geburtsdatum": {
          "jahr": 1980,
          "monat": 1,
          "tag": 1
        }
      }
    }, {
      "personendaten": {
        "familienname": "GIBTS",
        "vorname": "NICHT",
        "geburtsdatum": {
          "jahr": 1980,
          "monat": 1,
          "tag": 1
        }
      }
    }
  ],
  "vkz": "BMI",
  "bereich": [
    "TEST", "BMI+ZP"
  ]
}
Response
{
  "ergebnis": [
    {
      "bpks": {
        "TEST": "MplDSk8IKQ7vYLl6w5RYDDz6F/o=",
        "BMI+ZP": "SdovTTl8bxIbAWZxl1QN5E58efS3xNgo7bq6zgFPcslYKgQCmGiHKAiaTBEnLx/Ou3LH0AwFklRLvQGtG4EbJmAXEEpG+QBCwEohiGSX9zjxDLhidjGj8BNeVV+BAK4xh6bu77Nn72TWy2Guw2QNu8eJ9Can80c4746ljgAR/Vw="
      }
    },
    {
      "fault": {
        "type": "urn:SZR:F230",
        "title": "No person matched"
      }
    }
  ]
}

bpk/suche mit ListMultiplePersons und Personenliste Response

Modifiziert man die Suchdaten, sodass mehrere Personen dazu passen, bekommt man als behördlicher Nutzer bis zu 3 Treffer retour. In dem Fall bekommt man jedoch keine bPKs (die gäbe es nur bei eindeutigen Treffern). Mit den Personendaten kann man eine Folgesuche zusammenstellen, die eindeutig wird.

Wären es jedoch mehr als 3 Treffer, würde man den Fault F231 bekommen.

Request

URL z.B. für A-Umgebung at.gv.bmi.sz2-n-a/szr/rest/api/bpk/suche?ListMultiplePersons=true
PVP und andere Header werden zwecks Übersicht weggelassen sind aber nötig

{
  "suchdaten": [
    {
      "personendaten": {
        "familienname": "XXXSZR",
        "vorname": "XXXTest",
        "geburtsdatum": {
          "jahr": 1960
        }
      }
    }
  ],
  "vkz": "BMI",
  "bereich": [
    "TEST"
  ]
}
Response
{
  "ergebnis": [
    {
      "personen": [
        {
          "register": "ZMR",
          "personendaten": {
            "familienname": "XXXSZR",
            "vorname": "XXXTest",
            "geburtsdatum": {
              "jahr": 1960,
              "monat": 4,
              "tag": 4
            },
            "geburtsort": "Wien",
            "geburtsstaat": {
              "isoCode3": "AUT",
              "name": "Österreich"
            },
            "geschlecht": "Männlich"
          },
          "anschrift": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              },
              "gemeinde": "Testgemeinde 09988",
              "strasse": "Testgasse 8 Adamweg",
              "ort": "Testort 8 B",
              "postleitzahl": "0088",
              "hausnummer": "104",
              "stiege": "A",
              "tuer": "13"
            }
          ],
          "staatsangehoerigkeit": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              }
            }
          ]
        },
        {
          "register": "ZMR",
          "personendaten": {
            "familienname": "XXXSZR",
            "vorname": "XXXTest",
            "geburtsdatum": {
              "jahr": 1960,
              "monat": 2,
              "tag": 2
            },
            "geburtsort": "Wien",
            "geburtsstaat": {
              "isoCode3": "AUT",
              "name": "Österreich"
            },
            "geschlecht": "Männlich"
          },
          "anschrift": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              },
              "gemeinde": "Testgemeinde 09988",
              "strasse": "Testgasse 8 Adamweg",
              "ort": "Testort 8 A",
              "postleitzahl": "0088",
              "hausnummer": "Gruppe",
              "stiege": "117",
              "tuer": "4"
            }
          ],
          "staatsangehoerigkeit": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              }
            }
          ]
        },
        {
          "register": "ZMR",
          "personendaten": {
            "familienname": "XXXSZR",
            "vorname": "XXXTest",
            "geburtsdatum": {
              "jahr": 1960,
              "monat": 2,
              "tag": 2
            },
            "geburtsort": "Wien",
            "geburtsstaat": {
              "isoCode3": "AUT",
              "name": "Österreich"
            },
            "geschlecht": "Männlich"
          },
          "anschrift": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              },
              "gemeinde": "Testgemeinde 09988",
              "strasse": "Teststraße 8 Bertaweg",
              "ort": "Testort 8 A",
              "postleitzahl": "0088",
              "hausnummer": "Ladenzeile"
            }
          ],
          "staatsangehoerigkeit": [
            {
              "staat": {
                "isoCode3": "AUT",
                "name": "Österreich"
              }
            }
          ]
        }
      ]
    }
  ]
}

SOAP

Weiterleiten der PVP Chain

In diesem Bsp wären die PVP Daten des Ursprungsusers folgende (natürlich sind die Werte a, b, c, ... nur simple Ersatzwerte für echte PVP Daten eines Users):

<pvpToken version="1.9">
  <authenticate>
    <participantId>a</participantId>
    <gvOuDomain>b</gvOuDomain>
    <userPrincipal>
      <userId>c</userId>
      <cn>d</cn>
      <gvOuId>e</gvOuId>
      <ou>f</ou>
      <gvSecClass>2</gvSecClass>
      <gvGid>g</gvGid>
    </userPrincipal>
  </authenticate>
</pvpToken>

Der Block muss korrekterweise im SOAP Header des SZR Requests stehen, damit das SZR bzw ERNP/ZMR korrekt protokollieren können, an wen die bPK schlussendlich übermittelt wird:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <ns4:Security xmlns="http://egov.gv.at/pvp1.xsd" xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
      <pvpToken version="1.9">
        <authenticate>
          <participantId>a</participantId>
          <gvOuDomain>b</gvOuDomain>
          <userPrincipal>
            <userId>c</userId>
            <cn>d</cn>
            <gvOuId>e</gvOuId>
            <ou>f</ou>
            <gvSecClass>2</gvSecClass>
            <gvGid>g</gvGid>
          </userPrincipal>
        </authenticate>
      </pvpToken>
    </ns4:Security>
  </S:Header>
  <S:Body>
    <ns3:GetBPK xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns3="urn:SZRServices">
      <ns3:PersonInfo>
        <ns3:Person>
          <ns2:Name>
            <ns2:GivenName>test</ns2:GivenName>
            <ns2:FamilyName>test</ns2:FamilyName>
          </ns2:Name>
          <ns2:DateOfBirth>1990-01-01</ns2:DateOfBirth>
        </ns3:Person>
      </ns3:PersonInfo>
      <ns3:BereichsKennung>urn:publicid:gv.at:cdid+TEST</ns3:BereichsKennung>
      <ns3:VKZ>BMI</ns3:VKZ>
    </ns3:GetBPK>
  </S:Body>
</S:Envelope>

Der Request geht über das Portal ins SZR und würde z.B. folgendermaßen im SZR ankommen.

Statt clientAppParticipantid würde die im Portal hinterlegte ParticipantId der Clientapplikation die auf das SZR zugreift stehen (genauso auch userId, ...)

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <ns4:Security xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
      <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">
        <authenticate>
          <participantId>clientAppParticipantid</participantId>
          <gvOuDomain>clientAppGvOuDomain</gvOuDomain>
          <systemPrincipal>
            <userId>clientAppUserId</userId>
            <cn>clientAppCn</cn>
            <gvOuId>clientAppGvOuId</gvOuId>
            <ou>clientAppOu</ou>
          </systemPrincipal>
        </authenticate>
        <authorize>
          <role value="szr-bpk-abfrage"/>
        </authorize>
        <pvpChainedToken version="1.9">
          <authenticate>
            <participantId>a</participantId>
            <gvOuDomain>b</gvOuDomain>
            <userPrincipal>
              <userId>c</userId>
              <cn>d</cn>
              <gvOuId>e</gvOuId>
              <ou>f</ou>
              <gvSecClass>2</gvSecClass>
              <gvGid>g</gvGid>
            </userPrincipal>
          </authenticate>
        </pvpChainedToken>
      </pvpToken>
    </ns4:Security>
  </S:Header>
  <S:Body>
    <ns3:GetBPK xmlns:ns3="urn:SZRServices" xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#">
      <ns3:PersonInfo>
        <ns3:Person>
          <ns2:Name>
            <ns2:GivenName>test</ns2:GivenName>
            <ns2:FamilyName>test</ns2:FamilyName>
          </ns2:Name>
          <ns2:DateOfBirth>1990-01-01</ns2:DateOfBirth>
        </ns3:Person>
      </ns3:PersonInfo>
      <ns3:BereichsKennung>urn:publicid:gv.at:cdid+TEST</ns3:BereichsKennung>
      <ns3:VKZ>BMI</ns3:VKZ>
    </ns3:GetBPK>
  </S:Body>
</S:Envelope>

GetBPK mit wbpk und Identification

Folgende Abfrage:

Request

Zwecks Übersicht wird hier in den Beispielen der SOAP Header inkl PVP Chain etc entfernt

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>... </S:Header>
  <S:Body>
    <GetBPK xmlns="urn:SZRServices" xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#">
      <PersonInfo>
        <Person>
          <ns2:Identification>
            <ns2:Value>f4zoq1hBc0TIR/mkTqjQVFja6ao9UAN4HFzeSFiwSNWLMaJQuFQDGLIoq4KLgrs7CH1uHXLDz41KIIt80YrtmQbS38AFanvE49KLjpk/QG6708iKqJEy4iX9BAcoZLL3ShzQe9mhrMC3EwS6oHiFSgmi3TY6drXDJ3yKa23sEPI=</ns2:Value>
            <ns2:Type>urn:publicid:gv.at:ecdid+BMI+ZP</ns2:Type>
          </ns2:Identification>
          <ns2:Name>
            <ns2:GivenName>XXXMax xxx</ns2:GivenName>
            <ns2:FamilyName>XXXMuster</ns2:FamilyName>
          </ns2:Name>
          <ns2:DateOfBirth>1980-01-01</ns2:DateOfBirth>
        </Person>
      </PersonInfo>
      <BereichsKennung>urn:publicid:gv.at:wbpk+XFN+12345i</BereichsKennung>
      <VKZ>XFN-12345i</VKZ>
      <Target>
        <BereichsKennung>urn:publicid:gv.at:wbpk+XFN+12345i</BereichsKennung>
        <VKZ>XFN-12345i</VKZ>
      </Target>
    </GetBPK>
  </S:Body>
</S:Envelope>
Response

Im Response sieht man, dass die angeforderte unverschlüsselte wbPK WqKkLhjamiurkTBTiEEeYzhVQp4= ist und die verschlüsselte wbPK nJBWSRKHL7Ga1YXca1g...k3akog==

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns2="urn:SZRServices">
   <soapenv:Body>
      <ns2:GetBPKResponse xmlns:ns3="http://egov.gv.at/pvp1.xsd" xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
         <ns2:GetBPKReturn>WqKkLhjamiurkTBTiEEeYzhVQp4=</ns2:GetBPKReturn>
         <ns2:FremdBPK>
            <ns2:BereichsKennung>urn:publicid:gv.at:ewbpk+XFN-12345i+XFN+12345i</ns2:BereichsKennung>
            <ns2:FremdBPK>nJBWSRKHL7Ga1YXca1gxyG0zzaAsIaulVx0YSuckVXAh5x7BXU9U9stYi4LfAotBQH8dGmWkExpuJVB36SkrFW7aAk6rgZHlvZ53DMgyfWlVxGs7wg6xQpcONKbw0l/sfHMqcZUNFtnaDD8jZnJeX7nc+y/CxB1VreHx6tdpJvo2aXi1f8Jg+d1NXWpss3/NGzzM7dHjte/jfNyBoSRg5tmkVueU335al8xjYCk90JVA/U58PFz6O0CQVwz6tmNW6pqQaGpdh1Ir5O3vztbLvZtqjpmOEp0ESyH2xDOBCIBWfTTuku/P1EkQXwIZbkMpxMbOPyXrVSWWP1fLk3akog==</ns2:FremdBPK>
         </ns2:FremdBPK>
      </ns2:GetBPKResponse>
   </soapenv:Body>
</soapenv:Envelope>

GetBPK mit ListMultiplePersons und AddGeprueftInfo und bPk Response

Dieses Beispiel zeigt 2 Optionen für behördliche Benutzer:

Wie oben erwähnt ist folgender Request nur für behördliche Organisationen relevant. Private bekommen nie Personendaten und können die Option <ListMultiplePersons> gar nicht nutzen.

Request

Zwecks Übersicht wird hier in den Beispielen der SOAP Header inkl PVP Chain etc entfernt

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>...</S:Header>
   <S:Body>
      <GetBPK xmlns="urn:SZRServices" xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#">
  <PersonInfo>
    <Person>
      <ns2:Name>
        <ns2:GivenName>XXXMax xxx</ns2:GivenName>
        <ns2:FamilyName>XXXMuster</ns2:FamilyName>
      </ns2:Name>
      <ns2:DateOfBirth>1980-01-01</ns2:DateOfBirth>
    </Person>
  </PersonInfo>
  <BereichsKennung>urn:publicid:gv.at:cdid+TEST</BereichsKennung>
  <VKZ>BMI</VKZ>
  <Target>
    <BereichsKennung>urn:publicid:gv.at:cdid+ZP</BereichsKennung>
    <VKZ>BMI</VKZ>
  </Target>
  <Target>
    <BereichsKennung>urn:publicid:gv.at:cdid+T1</BereichsKennung>
    <VKZ>BMI</VKZ>
  </Target>
  <ListMultiplePersons>true</ListMultiplePersons>
  <AddGeprueftInfo>true</AddGeprueftInfo>
</GetBPK>
   </S:Body>
</S:Envelope>
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns2="urn:SZRServices">
  <soapenv:Body>
    <ns3:GetBPKResponse xmlns:ns0="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns3="urn:SZRServices">
      <ns3:GetBPKReturn>MplDSk8IKQ7vYLl6w5RYDDz6F/o=</ns3:GetBPKReturn>
      <ns3:FremdBPK>
        <ns3:BereichsKennung>urn:publicid:gv.at:ecdid+BMI+ZP</ns3:BereichsKennung>
        <ns3:FremdBPK>FrdnVY17rBIRZ31UnCPZkQW0nONvfWeuM8roAU1m3s69SU/sCorabEI/49UePFen8XHN7NlAh4jdj7hBw2t+IvWU+mKO6qePyRVpEkUDk6pK9Bz/vNIuQxr+XgUQ7+dJPs+zCBnifF+TbTwGCs4nZsOHU2HfeLDH97tHCxZ6I3A=</ns3:FremdBPK>
      </ns3:FremdBPK>
      <ns3:FremdBPK>
        <ns3:BereichsKennung>urn:publicid:gv.at:ecdid+BMI+T1</ns3:BereichsKennung>
        <ns3:FremdBPK>fkV2HNm7ROS1iWh+tr1ByG1avtvOjC5c/GngnbyDTQdNn8KjzE0vX/geyAaYV5xLnOeX/Ci7tzqYHMrzqAYhgeuHgRAb699srWFOXzmk4mp3c2UmWLxolrItQ1ukMu4ITujJapUyyFGvG/sncZZ6i96sUNKQ/fOwApJC9N1oA/QHdekEnZkPiK3Pkhw+lrLA2bvVXwWEbwusdLfI8Dm2mgh8WTCL5e023g7EQt7PliKvLwY5eJaQDRcnXhA3OL3dZeR8fAeQ/i144EfjXdgfOMEDePksXft3xkYH9I2ndSa4NWw2glOyg71lf+2PLKxpqLnEARohRr9iUvYs3vHd5w==</ns3:FremdBPK>
      </ns3:FremdBPK>
      <ns3:Geprueft>true</ns3:Geprueft>
    </ns3:GetBPKResponse>
  </soapenv:Body>
</soapenv:Envelope>

GetBPK mit ListMultiplePersons und Personenliste Response

Modifiziert man die Suchdaten, sodass mehrere Personen dazu passen, bekommt man als behördlicher Nutzer bis zu 3 Treffer retour. In dem Fall bekommt man jedoch keine bPKs (die gäbe es nur bei eindeutigen Treffern). Mit den Personendaten kann man eine Folgesuche zusammenstellen, die eindeutig wird.

Wären es jedoch mehr als 3 Treffer, würde man den SOAP Fault F231 bekommen.

Request

Zwecks Übersicht wird hier in den Beispielen der SOAP Header inkl PVP Chain etc entfernt

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>...</S:Header>
   <S:Body>
      <GetBPK xmlns="urn:SZRServices" xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#">
  <PersonInfo>
    <Person>
      <ns2:Name>
        <ns2:GivenName>XXXTest</ns2:GivenName>
        <ns2:FamilyName>XXXSZR</ns2:FamilyName>
      </ns2:Name>
      <ns2:DateOfBirth>1960</ns2:DateOfBirth>
    </Person>
  </PersonInfo>
  <BereichsKennung>urn:publicid:gv.at:cdid+TEST</BereichsKennung>
  <VKZ>BMI</VKZ>
  <ListMultiplePersons>true</ListMultiplePersons>
</GetBPK>
   </S:Body>
</S:Envelope>
Response
<soapenv:Envelope xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns2="urn:SZRServices" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns3:GetBPKResponse xmlns:ns0="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns3="urn:SZRServices">
         <ns3:PersonInfo>
            <ns3:Person>
               <ns0:Name>
                  <ns0:GivenName>XXXTest</ns0:GivenName>
                  <ns0:FamilyName>XXXSZR</ns0:FamilyName>
               </ns0:Name>
               <ns0:Sex>male</ns0:Sex>
               <ns0:DateOfBirth>1960-04-04</ns0:DateOfBirth>
               <ns0:PlaceOfBirth>Wien</ns0:PlaceOfBirth>
               <ns0:CountryOfBirth>Österreich</ns0:CountryOfBirth>
               <ns0:Nationality>Österreich</ns0:Nationality>
            </ns3:Person>
            <ns3:RegularDomicile>
               <ns0:PostalCode>0088</ns0:PostalCode>
               <ns0:Municipality>Testgemeinde 09988</ns0:Municipality>
               <ns0:Locality>Testort 8 B</ns0:Locality>
               <ns0:StateCode3>AUT</ns0:StateCode3>
               <ns0:DeliveryAddress>
                  <ns0:StreetName>Testgasse 8 Adamweg</ns0:StreetName>
                  <ns0:BuildingNumber>104</ns0:BuildingNumber>
                  <ns0:Unit>A</ns0:Unit>
                  <ns0:DoorNumber>13</ns0:DoorNumber>
               </ns0:DeliveryAddress>
            </ns3:RegularDomicile>
         </ns3:PersonInfo>
         <ns3:PersonInfo>
            <ns3:Person>
               <ns0:Name>
                  <ns0:GivenName>XXXTest</ns0:GivenName>
                  <ns0:FamilyName>XXXSZR</ns0:FamilyName>
               </ns0:Name>
               <ns0:Sex>male</ns0:Sex>
               <ns0:DateOfBirth>1960-02-02</ns0:DateOfBirth>
               <ns0:PlaceOfBirth>Wien</ns0:PlaceOfBirth>
               <ns0:CountryOfBirth>Österreich</ns0:CountryOfBirth>
               <ns0:Nationality>Österreich</ns0:Nationality>
            </ns3:Person>
            <ns3:RegularDomicile>
               <ns0:PostalCode>0088</ns0:PostalCode>
               <ns0:Municipality>Testgemeinde 09988</ns0:Municipality>
               <ns0:Locality>Testort 8 A</ns0:Locality>
               <ns0:StateCode3>AUT</ns0:StateCode3>
               <ns0:DeliveryAddress>
                  <ns0:StreetName>Testgasse 8 Adamweg</ns0:StreetName>
                  <ns0:BuildingNumber>Gruppe</ns0:BuildingNumber>
                  <ns0:Unit>117</ns0:Unit>
                  <ns0:DoorNumber>4</ns0:DoorNumber>
               </ns0:DeliveryAddress>
            </ns3:RegularDomicile>
         </ns3:PersonInfo>
         <ns3:PersonInfo>
            <ns3:Person>
               <ns0:Name>
                  <ns0:GivenName>XXXTest</ns0:GivenName>
                  <ns0:FamilyName>XXXSZR</ns0:FamilyName>
               </ns0:Name>
               <ns0:Sex>male</ns0:Sex>
               <ns0:DateOfBirth>1960-02-02</ns0:DateOfBirth>
               <ns0:PlaceOfBirth>Wien</ns0:PlaceOfBirth>
               <ns0:CountryOfBirth>Österreich</ns0:CountryOfBirth>
               <ns0:Nationality>Österreich</ns0:Nationality>
            </ns3:Person>
            <ns3:RegularDomicile>
               <ns0:PostalCode>0088</ns0:PostalCode>
               <ns0:Municipality>Testgemeinde 09988</ns0:Municipality>
               <ns0:Locality>Testort 8 A</ns0:Locality>
               <ns0:StateCode3>AUT</ns0:StateCode3>
               <ns0:DeliveryAddress>
                  <ns0:StreetName>Teststraße 8 Bertaweg</ns0:StreetName>
                  <ns0:BuildingNumber>Ladenzeile</ns0:BuildingNumber>
               </ns0:DeliveryAddress>
            </ns3:RegularDomicile>
         </ns3:PersonInfo>
      </ns3:GetBPKResponse>
   </soapenv:Body>
</soapenv:Envelope>
Weitere GetBpk Optionen

GetBPKs mit 1x bPK und 1x Error Response

Hierbei handelt es sich grundsätzlich um dieselbe Abfrage wie getBpk ohne die Optionen <ListMultiplePersons> und <InsertErnp>, jedoch ist die Operation listenbasiert und somit für die Abfrage mehrerer Personen viel performanter als einzelne GetBPK Abfragen.

Nachdem es eine Listenabfrage ist, dürfen personenbezogene Fehler nicht den gesamten Response zu einem SOAP Fault machen, daher werden Fehler die mit den jeweiligen Suchdaten zu tun haben im Response unter GetBPKsResponseType.Fault hinterlegt.

Im folgenden Beispiel sieht man eine Abfrage nach 2 Personen, wobei die 1. gefunden wird und die 2. den Fehler No person matched bekommt (wie zuvor erwähnt macht das nicht den gesamten Response zu einem Fehler, sondern nur das jeweilige zur Person passende Listenelement)

Request

Zwecks Übersicht wird hier in den Beispielen der SOAP Header inkl PVP Chain etc entfernt

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>...</S:Header>
   <S:Body>
<GetBPKs xmlns="urn:SZRServices" xmlns:ns2="http://reference.e-government.gv.at/namespace/persondata/20020228#">
  <PersonInfo>
    <Person>
      <ns2:Name>
        <ns2:GivenName>XXXMax</ns2:GivenName>
        <ns2:FamilyName>XXXMuster</ns2:FamilyName>
      </ns2:Name>
      <ns2:DateOfBirth>1980-01-01</ns2:DateOfBirth>
    </Person>
  </PersonInfo>
  <PersonInfo>
    <Person>
      <ns2:Name>
        <ns2:GivenName>GIBTS</ns2:GivenName>
        <ns2:FamilyName>NICHT</ns2:FamilyName>
      </ns2:Name>
      <ns2:DateOfBirth>1980-01-01</ns2:DateOfBirth>
    </Person>
  </PersonInfo>
  <VKZ>BMI</VKZ>
  <Target>
    <BereichsKennung>urn:publicid:gv.at:cdid+T1</BereichsKennung>
    <VKZ>BMI</VKZ>
  </Target>
</GetBPKs>
   </S:Body>
</S:Envelope>
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns2="urn:SZRServices">
   <soapenv:Body>
      <ns2:GetBPKsResponse xmlns:ns3="http://egov.gv.at/pvp1.xsd" xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
         <ns2:ResultRecord>
            <ns2:FremdBPK>
               <ns2:BereichsKennung>urn:publicid:gv.at:ecdid+BMI+T1</ns2:BereichsKennung>
               <ns2:FremdBPK>DrrL/jv3m15AcG96V1tuDe2mmfdfzdG3N5FuImKCjoerCid+lxk02ANf2WNEdwHmBNk+iCJWmwEnpzNa7E+qxJ9P/RBax06nXPdV/BVstSgyfEkS/TiTOQkotcW0COonngi7arZjo38Ia026odpebvbOKmUs4hHnBYweXyaLu31EODsRK9cKpqlWV3wtG3ZGVMyNJrgMUNvEdjit9uOHQlYQfulFwtiT2/2HwnxXq25GkfW2EDI8jwVKQxAxBQXzdhQqOkhTpRhrsmrq6rLPffJmwe2ArUQFUU6rmX0Ku/AnGZhebjYtMLZ7/zB3DVs9oZeoFtC+8h7bDxmW2L8Npw==</ns2:FremdBPK>
            </ns2:FremdBPK>
         </ns2:ResultRecord>
         <ns2:ResultRecord>
            <ns2:Fault Code="F230" String="No person matched"/>
         </ns2:ResultRecord>
      </ns2:GetBPKsResponse>
   </soapenv:Body>
</soapenv:Envelope>

GetVersion

Die Operation liefert allgemeine Informationen zum SZR Service, wie die Umgebung, die aktuelle Version und die Zeit wann diese Version eingesetzt wurde.

Request

Zwecks Übersicht wird hier in den Beispielen der SOAP Header inkl PVP Chain etc entfernt

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>...</S:Header>
   <S:Body>
      <GetVersion xmlns="urn:SZRServices"/>
   </S:Body>
</S:Envelope>
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#" xmlns:ns2="urn:SZRServices">
   <soapenv:Body>
      <ns2:GetVersionResponse xmlns:ns3="http://egov.gv.at/pvp1.xsd" xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
         <ns2:Version>2.2.0.0</ns2:Version>
         <ns2:Time>2024-01-15 09:40:10</ns2:Time>
         <ns2:Umgebung>P</ns2:Umgebung>
      </ns2:GetVersionResponse>
   </soapenv:Body>
</soapenv:Envelope>

Abkürzungsverzeichnis