DownloadSZR-Onlineschnittstelle-SOAP

SZR Onlineschnittstelle SOAP

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

Erzeugt am: 2024-12-05 07:51:21. Die jeweils aktuellste Fassung ist hier verfügbar.

Allgemeines

Das SZR ist als SOAP Front-End zum Zentralen Melderegister (ZMR) und Ergänzungsregister natürlicher Personen (ERnP) aufgebaut, um bereichsspezifische Personenkennzeichen (bPK) berechnen zu können.

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:

Anlaufstelle für alle Belange hinsichtlich Ausstattungsanträge
Genehmiger der Ausstattungsanträge
Datenschutzrechtlich verantwortlich für das SZR und ERnP
Fachlich verantwortlich für das SZR und ERnP

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

bmi-ikt-szr-postfach@bmi.gv.at

Zuständigkeiten:

Anlaufstelle für Fragen zum SZR in technischer Hinsicht
Technische Umsetzung von Anforderungen an das SZR
Technische Umsetzung von Ausstattungsanträgen. Betrifft Zugänge, Berechtigungen, etc.
SZR Support

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 die Stammzahlenregisterbehörde ü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 die Stammzahlenregisterbehörde zu richten.

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

Nutzungsbedingungen

Für einzelne Abfragen kann die GetBpk Methode verwendet werden, jedoch ist die Empfehlung auch hier schon die Listenoperation getBpks zu nutzen, weil es dann einfacher ist bei Bedarf viele bPKs performant abfragen zu können.

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

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 SZR-wsdl-Paket 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 Problemmeldung zumindest die gesendeten Anfragedaten (SOAP Request), die betroffene Betriebsumgebung und der exakte Anfragezeitpunkt mitgeteilt wird.

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.

SZR Zugriff über den Portalverbund

Das SZR ist ein SOAP 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: [Portal-Domain]/at.gv.bmi.sz2-n-[Umgebung]/SZR

Portal-Domain leitet sich von der Art des Zugriffs ab. Folgende Liste zeigt die üblichen Portal-Domains und deren Nutzung:
- Menschliche Benutzer greifen über das Stammportal zu. Portal-Domain = https://stportal.bmi.gv.at
- Applikations-Zugriffe von außen nutzen das Anwendungsportal. Portal-Domain = https://pvawp.bmi.gv.at
- Applikations-Zugriffe innerhalb des BMI nutzen das interne Portal. Portal-Domain = https://internalportal.sz.bmi.gv.at
Umgebung entspricht der Umgebung auf die zugegriffen werden soll (p = Produktion, a = externe Testumgebung, b = Businesspartnertest, t = interne Testumgebung, e = Entwicklungsumgebung). Im Backend werden die Umgebungen durchgängig eingehalten. Z.b. geht das SZR-A auch im Backend gegen die A Umgebungen vom ERnP und ZMR.

SOAP PVP Header

Das SZR erfordert als Portalapplikation die typischen PVP Header + Chained PVP Header des Ursprungsusers.

Die Toplevel PVP Header werden normalerweise vom Portal angehängt, bei dem sich die Clientapplikation via Client-Zertifikat authentifiziert hat. Sobald ein Request in diesem Portal ankommt, hängt es automatisch die zum Zertifikat hinterlegten PVP Header der Clientapplikation als SOAP Header 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.

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

Ist die Clientapplikation ebenfalls eine SOAP Applikation hinter einem Portal, bekommt diese die PVP Daten im SOAP Header Format. Dann ist die Transformation für den SZR Request relativ einfach, weil nur sichergestellt werden muss, dass die Daten korrekt an das SZR weitergeleitet werden (innerhalb des SOAP Security Headers wie im wsdl spezifiziert).
Nutzt die Clientapplikation HTTP statt SOAP, liegen die PVP Daten als HTTP Header vor und der einfachste Weg ist ein Mapping dieser Header auf die passenden PVP Elemente welche das SZR lt xsd erwartet.

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

SOAP Beispiel für das 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>

Schnittstellendokumentation

Das SZR.wsdl beschreibt die Schnittstelle und enthält einige ergänzende XML Kommentare mit weiteren Details zu Feldern etc.

Im Folgenden werden Dinge beschrieben, die nicht unmittelbar aus dem wsdl herausgelesen werden können.

Striktheit

Grundsätzlich vermeiden wir rückwärtsinkompatible Schnittstellenänderungen im SZR so gut wie möglich, außer es gibt z.B. gesetzliche Anforderungen wie die Meldegesetznovelle, welche neue Geschlechter eingeführt hat.

Trotzdem empfehlen wir bei Requests an das SZR möglichst strikt und wsdl-valide zu sein, während man bei Responses möglichst tolerant sein sollte. So ist man zukunftssicher bezüglich zukünftiger SZR API Anpassungen.
Beispiele für die empfohlene Toleranz beim Parsen von SZR Responses:

der Response sollte mit einem XML Parser geparst werden. Das stellt sicher, dass wechselnde Namespace-Prefixe oder eine andere Reihenfolge von Namespace-Deklarationen keine Probleme verursachen. Obwohl diese Dinge typischerweise statisch sind, können solche XML Feinheiten z.B. durch technische Updates geändert werden.
der Response Parser sollte unerwartete Elemente ignorieren. Das stellt sicher, dass der seltene Fall einer Schnittstellenerweiterung im SZR um neue Felder keine Probleme macht.
der Response Parser sollte nicht abstürzen, falls nicht benötigte Elemente im Response fehlen. Dann sind, selbst wenn das SZR eines Tages z.B. ein Pflichtfeld zu einem optionalen Feld macht, keine Anpassungen im eigenen Client nötig.

Unabhängig davon, dass eine tolerante Response Verarbeitung sinnvoll ist, werden neue Funktionen im SZR normalerweise rückwärtskompatibel eingebaut. Neue Response Elemente muss der Benutzer typischerweise extra anfordern. Ein Beispiel ist das AddGeprueftInfo Element bei GetBpk Abfragen. Schickt man das Element nicht, verhält sich alles wie bisher. Schickt man es, liefert das SZR erweiterte Informationen im Ergebnis aus. Somit betreffen die neuen Daten nur Benutzer, die damit umgehen können.

SZR Usecases

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

GetBPK: Benötigt PVP Rolle SZR-BPK-Abfrage. Liefert eine bPK zu den angegebenen Suchdaten
GetBPKs: Benötigt PVP Rolle SZR-BPK-Abfrage. Funktioniert genauso wie GetBPK aber ist listenbasiert und performanter
GetVersion: Zugriff ohne PVP Rolle möglich. Liefert SZR Version und Informationen zum Service

Anfrageinformationen

Das SZR darf eine bPK zu einer Person nur dann ausliefern, wenn diese eindeutig identifiziert wurde.

Zur Identifizierung einer Person müssen bestimmte Personenkriterien übermittelt werden. Vorname und Familienname, sowie mindestens eines der folgenden Kriterien:

Identification (typischerweise bPK)
Geburtsdatum (auch wenn nur Jahr oder Jahr+Monat angegeben wird)
Staatsangehörigkeit
Geburtsstaat
Geburtsort
Geschlecht
Hausnummer
Tür
Straße
Stiege
Ort
Gemeindename
Postleitzahl

Im SZR.wsdl ist das jeweils englische Feld ersichtlich um diese Daten im SOAP Request übermitteln zu können.

Aus technischen Gründen wird empfohlen neben Vorname und Familienname ein möglichst eindeutiges 3. Kriterium zu schicken. Geburtsdatum ist ein sehr gutes 3. Kriterium, während Geschlecht ein schlechtes ist.

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

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:

Han: keine
Hans: Hans, Hans Peter, Hans Peter Josef
Hans-Peter: Hans-Peter
Hans Peter: Hans Peter, Hans-Peter
Hans Peter Josef: Hans Peter Josef
Hans-Peter Josef: Hans Peter Josef

Geburtsdatum

Beim Geburtsdatum besteht die Möglichkeit, nur mit Jahr oder nur mit Jahr und Monat anstelle eines vollständigen Datums zu suchen. Dabei kann der Tag bzw. das Monat ausgelassen oder mit 00 gesetzt werden.

Gültige Werte z.B.: 1980-01-01, 1980-01, 1980, 1980-01-00, 1980-00-00, 1980-00
Ungültige Werte z.B.: 1980-1-1, 1980-00-01, 1980-?, 1980-0, 1700-01-01, 80-01-01

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

ein sehr häufiger Grund für einen Nichttreffer ist, wenn die Abfrage mit mehreren Namen im ZMR erfolgt und diese nicht im ZMR eingetragen sind.
ein weiterer Fall sind Kitfälle bei der Verwendung einer bPK als Identification. Nachdem die Kitquelle im Rahmen des Kits eine andere bPK erhält, muss sichergestellt werden, dass entweder alle Suchdaten (Identification, Personendaten, ...) von der Kitquelle oder vom Kitziel sind aber nicht gemischt.
wird eine Person im ERNP bzw ZMR amtlich beendet (da sie z.B. eine unabsichtliche Anlage war), kann man zu den Suchdaten keine bPK mehr erhalten.

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.

Bereichsangaben

Allgemeines bPK Konzept

Eine bPK (bereichsspezifische Personenkennzeichen) ist eine eindeutige Identifikation für eine Person und einen Bereich. Technisch gesehen basiert sie auf einer ZMR-Zahl (ZMR) bzw Ordnungsnummer (ERnP), welche zu einer bereichsunabhängigen Stammzahl verschlüsselt wird und anschließend um den Bereich ergänzt und damit zur bPK wird.

Außerdem können bPKs auch verschlüsselt (als vbPK) beim SZR abgefragt werden, wodurch es möglich wird, dass auch fremde Bereiche vbPKs zu Personen abfragen können.

Die Verschlüsselung erfolgt mit dem öffentlichen Schlüssel der Empfängerapplikation. Daher ist allein die Empfängerapplikation in der Lage mit Ihrem privaten Key diese bPK zu entschlüsseln, um dann das unverschlüsselte bPK zu erhalten. Es wird auch Datum und Zeit mit verschlüsselt, weshalb jede verschlüsselte bPK bei jeder Abfrage anders aussieht.

Ein Detail welches manchmal relevant ist: bPKs aus der PROD (p) 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

Bereiche

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.

Um bPK oder verschlüsselte bPK zu erhalten, muss man den Bereich angeben, für den die bPK gelten soll. Die Angabe muss im SOAP Request dabei immer mit vollständigem Präfix erfolgen.

Präfix einer bPK eines nicht privaten Bereichs

urn:publicid:gv.at:cdid+

Zusammen mit dem zwei bis fünfstelligen Bereich ergibt dies zum Beispiel einen Ausdruck urn:publicid:gv.at:cdid+ZP für den Bereich "zur Person".

Präfix einer bPK eines privaten Bereichs

urn:publicid:gv.at:wbpk+

Der obige Präfix ergibt zusammen mit der Registerkennung laut nachfolgender Tabelle und der Registernummer (z.B. Firmenbuchnummer, ...) eine vollständige Bereichsangabe.

Z.B. urn:publicid:gv.at:wbpk+XFN+1234i für eine Firmenbuchnummer oder urn:publicid:gv.at:wbpk+XZVR+1234 für das Vereinsregister

Präfix einer verschlüsselten bPK im Response

urn:publicid:gv.at:ecdid+ bzw. urn:publicid:gv.at:ewbpk+ (privater Bereich)

Wie man sieht, entspricht der Präfix dem jeweiligen unverschlüsselten, hat aber ein e vorangestellt.

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

Ein Beispiel wäre urn:publicid:gv.at:ecdid+BBA-STA+AS, was einer verschlüsselten bPK für die Statistik Austria mit dem VKZ BBA-STA und dem Bereich AS für Amtliche Statistik entspricht oder urn:publicid:gv.at:ewbpk+XFN-12345i+XFN+12345i für eine verschlüsselte wbpk.

Achtung: Dieser Präfix wird nur im SOAP Response des SZR verwendet!

Im SOAP Request wird VKZ und Bereich separat angeführt und durch das Wrapperobjekt <Target> zum verschlüsselten Bereich.

Beispiele sind urn:publicid:gv.at:ecdid+BMI+ZP bzw urn:publicid:gv.at:ewbpk+BMI+XFN+12345i

VKZ Sonderfälle:

Bei Teilnehmern aus dem privatrechtlichen Umfeld dient deren z.B. Vereinsregisternummer oder Firmenbuchnummer als Ersatzwert für das VKZ.
Bei verschlüsselten bPKs, kann auch ein sogenannter Service-Identifier (eine Service-ID) verwendet werden, da z.B. die Zustellung nicht einer bestimmten Verwaltung, sondern einem Service zugeordnet ist. Dies gilt derzeit beispielsweise für die Services ZUSETNVZ „eZustellungNEU“ und ZUSEAMOD „Anzeigemodul“

GetBPK Beispiele und Erklärung

GetBPK Abfrage mit wbpk und Identification

Folgende Abfrage:

sucht nach XXXMax xxx XXXMuster mit Gebdat 1980-01-01 innerhalb des <PersonInfo> Elements
Es wird der Bereich urn:publicid:gv.at:wbpk+XFN+12345i unverschlüsselt angefragt und als VKZ des Aufrufers wird XFN-12345i spezifiziert
Weiter unten wird dieselbe VKZ+BereichsKennung Kombination nochmal angeführt, allerdings innerhalb eines <Target> Elements, was bedeutet, dass die Kombination als verschlüsselte bPK abgefragt wird. Wie man sieht, wird im Request nicht der String urn:publicid:gv.at:ewbpk+XFN-12345i+XFN+12345i genutzt. Dieses Format befindet sich nur im zugehörigen Responseabschnitt.
Als weitere Besonderheit zeigt der Request auch die Nutzung einer vbPK BMI+ZP als Identification. Dadurch wird die Person garantiert eindeutig gefunden (sofern die übermittelte ID existiert und die Personendaten dazupassen)

Request:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <ns2:Security xmlns:ns2="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns="http://egov.gv.at/pvp1.xsd">
      <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">
        <authenticate>...</authenticate>
        <authorize>
          <role value="szr-bpk-abfrage"/>
        </authorize>
      </pvpToken>
    </ns2:Security>
  </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>

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

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: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 Abfrage mit regulärer bPK und Personenliste

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.

Wie man im Beispiel aber sieht: Wenn die Person eindeutig identifiziert werden kann, bekommt man nur die bPK(s) aber keine Personendaten

Request:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>
      <ns2:Security xmlns:ns2="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns="http://egov.gv.at/pvp1.xsd">
         <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">
            <authenticate>...</authenticate>
            <authorize>
               <role value="szr-bpk-abfrage"/>
            </authorize>
         </pvpToken>
      </ns2:Security>
   </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>
  <ListMultiplePersons>true</ListMultiplePersons>
</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>
      <ns2:GetBPKResponse xmlns:ns3="http://egov.gv.at/pvp1.xsd" xmlns:ns4="http://schemas.xmlsoap.org/ws/2002/04/secext">
         <ns2:GetBPKReturn>MplDSk8IKQ7vYLl6w5RYDDz6F/o=</ns2:GetBPKReturn>
         <ns2:FremdBPK>
            <ns2:BereichsKennung>urn:publicid:gv.at:ecdid+BMI+ZP</ns2:BereichsKennung>
            <ns2:FremdBPK>MfiMHBo2hYIOonhMHvkSB5DZRwrvCJ4GvJieu2w0sjxJdFztWW5el6/I9J+9FdR4foD1rT40AwD1DNcrlwlZIm+c1kf/URgRH507KK+yFuuanf94paa9Er26HyqUudTue3Mi/VkpPSbHZSssWhD2b787JIEvrpY8MLyPW28+XfM=</ns2:FremdBPK>
         </ns2:FremdBPK>
      </ns2:GetBPKResponse>
   </soapenv:Body>
</soapenv:Envelope>

GetBPK Abfrage mit regulärer bPK und Personenliste (Mehrfachtreffer)

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:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>
      <ns2:Security xmlns:ns2="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns="http://egov.gv.at/pvp1.xsd">
         <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">
            <authenticate>...</authenticate>
            <authorize>
               <role value="szr-bpk-abfrage"/>
            </authorize>
         </pvpToken>
      </ns2:Security>
   </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: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">
      <ns2:PersonInfo>
        <ns2:Person>
          <Name xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <GivenName>XXXTest</GivenName>
            <FamilyName>XXXSZR</FamilyName>
          </Name>
          <Sex xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">male</Sex>
          <DateOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">1960-04-04
          </DateOfBirth>
          <PlaceOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Wien</PlaceOfBirth>
          <CountryOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </CountryOfBirth>
          <Nationality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </Nationality>
        </ns2:Person>
        <ns2:RegularDomicile>
          <PostalCode xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">0088</PostalCode>
          <Municipality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Testgemeinde 09988
          </Municipality>
          <StateCode3 xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">AUT</StateCode3>
          <DeliveryAddress xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <StreetName>Testgasse 8 Adamweg</StreetName>
            <BuildingNumber>104</BuildingNumber>
            <Unit>A</Unit>
            <DoorNumber>13</DoorNumber>
          </DeliveryAddress>
        </ns2:RegularDomicile>
      </ns2:PersonInfo>
      <ns2:PersonInfo>
        <ns2:Person>
          <Name xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <GivenName>XXXTest</GivenName>
            <FamilyName>XXXSZR</FamilyName>
          </Name>
          <Sex xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">male</Sex>
          <DateOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">1960-02-02
          </DateOfBirth>
          <PlaceOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Wien</PlaceOfBirth>
          <CountryOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </CountryOfBirth>
          <Nationality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </Nationality>
        </ns2:Person>
        <ns2:RegularDomicile>
          <PostalCode xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">0088</PostalCode>
          <Municipality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Testgemeinde 09988
          </Municipality>
          <StateCode3 xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">AUT</StateCode3>
          <DeliveryAddress xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <StreetName>Testgasse 8 Adamweg</StreetName>
            <BuildingNumber>Gruppe</BuildingNumber>
            <Unit>117</Unit>
            <DoorNumber>4</DoorNumber>
          </DeliveryAddress>
        </ns2:RegularDomicile>
      </ns2:PersonInfo>
      <ns2:PersonInfo>
        <ns2:Person>
          <Name xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <GivenName>XXXTest</GivenName>
            <FamilyName>XXXSZR</FamilyName>
          </Name>
          <Sex xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">male</Sex>
          <DateOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">1960-02-02
          </DateOfBirth>
          <PlaceOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Wien</PlaceOfBirth>
          <CountryOfBirth xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </CountryOfBirth>
          <Nationality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Österreich
          </Nationality>
        </ns2:Person>
        <ns2:RegularDomicile>
          <PostalCode xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">0088</PostalCode>
          <Municipality xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">Testgemeinde 09988
          </Municipality>
          <StateCode3 xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">AUT</StateCode3>
          <DeliveryAddress xmlns="http://reference.e-government.gv.at/namespace/persondata/20020228#">
            <StreetName>Teststraße 8 Bertaweg</StreetName>
            <BuildingNumber>Ladenzeile</BuildingNumber>
          </DeliveryAddress>
        </ns2:RegularDomicile>
      </ns2:PersonInfo>
    </ns2:GetBPKResponse>
  </soapenv:Body>
</soapenv:Envelope>

Weitere GetBpk Optionen

Für ausgewählte behördliche Benutzer gibt es die Option <InsertERnP>true</InsertERnP> womit nicht gefundene Personen automatisch im ERNP eingetragen werden. Diese Option muss explizit von der Stammzahlregisterbehörde freigegeben werden, damit man sie nutzen kann.
Die Option <AddGeprueftInfo>true</AddGeprueftInfo> kann von behördlichen Nutzern gesetzt werden, damit neben der bPK im Ergebnis auch steht, ob die jeweilige Person geprüft ist oder nicht.

GetBPKs Beispiele und Erklärung

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 Massenabfragen viel performanter als einzelne GetBPK Abfragen. Schickt man z.B. eine GetBpks Abfrage mit 100 Personen statt 100 einzelner GetBpk Abfragen, ist die Gesamtlaufzeit ca 10x so schnell.

Wir empfehlen jeweils 100 Personen auf einmal zu suchen, da größere Mengen pro Request nicht mehr viel schneller werden, dafür die Gefahr steigt in Timeouts zu laufen.

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:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>
      <ns2:Security xmlns:ns2="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns="http://egov.gv.at/pvp1.xsd">
         <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">
            <authenticate>...</authenticate>
            <authorize>
               <role value="szr-bpk-abfrage"/>
            </authorize>
         </pvpToken>
      </ns2:Security>
   </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 Beispiele und Erklärung

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

Darunter befinden sich diverse Informationen über wichtige anstehende Dinge im SZR. Es ist sinnvoll diese Operation regelmäßig abzurufen, um frühzeitig über anstehende Dinge informiert zu werden.

Request:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Header>
      <ns2:Security xmlns:ns2="http://schemas.xmlsoap.org/ws/2002/04/secext" xmlns="http://egov.gv.at/pvp1.xsd">
         <pvpToken xmlns="http://egov.gv.at/pvp1.xsd" version="1.9">...</pvpToken>
      </ns2:Security>
   </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:Info datum="2023-11-23" nachricht="Ab 05.12.2023 00:00 Uhr werden Mehrfachtreffer von max. 5 auf max. 3 Treffer reduziert. Diese Änderung wird automatisiert zu diesem Zeitpunkt im SZR ausgerollt. "/>
      </ns2:GetVersionResponse>
   </soapenv:Body>
</soapenv:Envelope>

Fehlerbehandlung

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 findet man einen SZR spezifischen Fehlercode und eine Nachricht, welche beschreibt, was passiert ist.

Ein beispielhafter SOAP Fehler ist "No person matched" mit Fehlercode 230 welcher retour kommt, wenn die Operation GetBPK zu den Personen-Suchdaten niemanden findet und deshalb keine bPK liefern kann:

<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>

Das Format 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.

SZR Fehlercodes

Eine Liste der SOAP-Faultcodes, die das SZR-Webservice zurückliefert.

F230: Es konnte keine Person im ZMR und/oder ERnP gefunden werden.
F231: Es wurden zu viele Personen im ZMR und/oder ERnP gefunden, sodass das Ergebnis nicht eindeutig war. Mit weiteren Suchkriterien kann das Ergebnis noch eindeutig gemacht werden.
F233: Dieselbe Ursache wie F231, allerdings mit >3 Treffern.
F401: Es fehlt die Rollenberechtigung. Entweder wird im PVP nicht die erforderliche Rolle mit gesendet, oder sie wird vom Anwendungsportal gefiltert.
F403: Die gesendete Session-ID konnte nicht zugeordnet werden. Es sollte die Session-ID geprüft werden. Ist diese zu alt, muss erneut abgefragt werden.
F404: Die Organisation mit dem angegebenen Verwaltungskennzeichen (VKZ) ist nicht für den angegebenen Bereich zur Errechnung von bPK berechtigt.
F411: Die Bereiche AS, ZP-TD und GH-GD dürfen nicht unverschlüsselt berechnet werden
F430: Für eine Personenabfrage müssen neben Familiennamen und Vorname zumindest ein weiteres Kriterium angegeben werden.
F431: Das eingemeldete Geburtsdatum ist ungültig
F432: Die Bereichsangabe ist ungültig. Sie muss immer mit vollständigem Präfix erfolgen. zum Beispiel urn:publicid:gv.at:cdid+SA um eine bPK für den Bereich SA zu erhalten.
F434: Von den mitgelieferten ZMR-Zahlen passt keine zur mitgelieferten bPK.
F435: Ungültige Angabe von einem Geschlecht
F438: Diese Meldung kommt bei ungültigen Zeichen im Request. Grundsätzlich unterstützt das SZR, ZMR und ERnP den Zeichensatz UTF-8. Allerdings sind nicht alle Zeichen daraus erlaubt. Wird eines dieser Zeichen zum Beispiel im Familiennamen mitgesendet, kommt diese Meldung
F439: Es kann nicht mit der bPK für einen Bereich gesucht werden, um die bPK einer Person zu einem anderen Bereich zu erhalten.
F441: Das XML-Element Identification muss mit Value und Type gesendet werden, da es sonst als ungültig angesehen wird.
F443: Das eigene VKZ muss im Request angegeben werden
F445: Zu viele vbPKs auf einmal angefordert
F447: Behördenkennzeichen erforderlich um ins ERNP einzufügen
F450: Das gesuchte Geburtsdatum liegt in der Zukunft
F451: Es muss mindestens 1 Bereich (unverschlüsselt oder verschlüsselt) angefordert werden
F453: Es ist im SZR kein Zertifikat hinterlegt, um die verschlüsselte bPK zu berechnen
F457: Begründung fehlt
F458: Nicht unterstütztes Setting
F459: Das SZR Service ist aktuell überlastet
F462: ListMultiplePersons darf nicht genutzt werden, wenn wbpks angefragt werden
F463: wbpks dürfen mit der Operation nicht genutzt werden
F464: Falsches bzw ungültiges oder veraltetes Setting
F465: Das VKZ darf keine verschlüsselten bPKs vom angefragten Bereich bekommen
F466: Die geschickte Stammzahl passt nicht zur Person
F467: Fehler beim Einfügen ins ERNP
F501, F502, F510, F511: Technische Fehler. Nach einiger Zeit erneut versuchen. Sollte die Meldung weiter bestehen, bitte den SZR-Support kontaktieren.

Achtung: Wie zuvor erwähnt sehen Portalfehler recht ähnlich aus und manche Fehlercodes wie F445 gibt es sowohl im SZR als auch im Portal.

Portalfehler sind aber immer am anderen <faultactor> erkennbar. Die häufigisten Portalfehler sind:

F445: Participant am Anwendungsportal nicht registriert
F490: Zertifikatsüberprüfung fehlgeschlagen (z.B. ungültige Root-CA, Zertifikat am Portal abgelaufen oder nicht registriert
F492: Keine Berechtigung für diese Anwendung im Anwendungsportal definiert
F494: Die Authentifizierung des Stammportals ist fehlgeschlagen

Abkürzungsverzeichnis

ERnP: Ergänzungsregister für natürliche Personen
ERsB: Ergänzungsregister für sonstige Betroffene
SZR: Stammzahlenregister
ZMR: Zentrales Melderegister
BMI: Bundesministerium für Inneres
BMF: Bundesministerium für Finanzen
DSG: Datenschutzgesetz
PVP: Portal Verbund Protokoll
E-GovG: E-Government-Gesetz
bPK: Bereichsspezifische Personenkennzeichen
wbPK: Wirtschaftsbereichsspezifische Personenkennzeichen
VKZ: Verwaltungskennzeichen
URL: Uniform Resource Locator
XML: Extensible Markup Language
SOAP: Simple Object Access Protocol