Download

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:

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 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. Die Dokumentation des Portalverbundprotokolls „PVP-*-R-Profil“ in der jeweils aktuellen Fassung hilft bei offenen Fragen.

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

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:

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.8">
  <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.8">
        <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.8">
        <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.8">
          <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:

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:

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:

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:

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.

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.

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:

GetBPK Beispiele und Erklärung

GetBPK Abfrage mit wbpk und Identification

Folgende Abfrage:

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.8">
        <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.8">
            <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.8">
            <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

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.8">
            <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.8">...</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.

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:

Abkürzungsverzeichnis