Schnittstellendokumentation

Allgemeiner Überblick über die Schnittstelle

Es handelt sich um eine REST-Schnittstelle (xml-over-https). Es werden ausschließlich POST-Methoden verwendet mit unterschiedlicher Aufruf-URI je Nachrichtentyp (REST Level 1).

Eine Abfrage folgt dem folgenden Muster:

a. Die Authentifizierung findet in Form eines OAuth 2.0 Bearer-Tokens im Request-Header Authorization statt

b. Nachrichtenkörper des Requests ist XML (application/xml), welches dem Standard XBasisdaten entspricht

c. Anhand des HTTP-Status-Codes lässt sich Erfolg/Misserfolg der Anfrage ableiten

d. Antworten sind in XML verfasst und erhalten im Erfolgsfall z. B. die entsprechenden Basisdaten, bei Misserfolg eine neutrale Antwort oder die Rückmeldung, dass eine Identifikation nicht möglich war bzw. die in der XBasisdaten-Spezifikation beschriebenen technischen und fachlichen Fehlercodes

Abb. 2 Diagramm Datenabruf mit Personendaten -- Quelle: BVA; Spezifikation XBasisdaten

Bei fachlich synchroner Kommunikation werden Antwortnachrichten über HTTP-Responses übermittelt.

Bei fachlich asynchroner Kommunikation werden Antwortnachrichten über einen Polling-Mechanismus abgefragt (sog. REST-Polling), siehe z. B. Nachrichten zur Erstbefüllung in Massendatenabrufe für die initiale Zuordnung von IDNr und weiterer Basisdaten - Polling.

Als Transportprotokoll wird ausschließlich HTTPS unter Verwendung der kryptographischen Protokolle TLS1.2 oder TLS1.3 eingesetzt.

Die Verbindungen werden mit Server- und Client-Zertifikaten (mTLS) abgesichert.

Über HTTPS ist der Identitätsdatenabruf ausschließlich aus den NdB oder dem VN erreichbar.

Authentifizierung und Autorisierung

Die Authentifizierung der aufrufenden Verfahren erfolgt über technische Benutzerkonten in Verbindung mit Client-Zertifikaten.

Client-Zertifikate werden durch das BVA gemäß den Empfehlungen aus TR-02102 ausgestellt und den aufrufenden Verfahren zur Verfügung gestellt.

Die Authentifizierung erfolgt zunächst gegen einen Authentifizierungsendpunkt gemäß OAuth 2.0 unter Verwendung des Client Credentials Flow (OAuth 2.0 RFC 6749).

cURL:

curl --request POST \
-L "https://${IDA_IAM_HOST}/realms/bva-ida/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=${CLIENT_ID}" \
--data-urlencode "client_secret=${CLIENT_SECRET}" \
--data-urlencode "grant_type=client_credentials" \
--cacert ${IDA_CA_CERT} \
--cert ${CLIENT_CERT} \
--key ${CLIENT_CERT_PRIVATE_KEY}

Dieser liefert ein Authentifizierungstoken, das in allen folgenden Anfragen gegen IDA im HTTP-Authorization-Header in folgender Form mitgesendet werden muss:

Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}

Eine Autorisierung findet auf Ebene des aufgerufenen Dienstes und der darin genutzten Anforderungselemente statt. Zugriffe auf nicht autorisierte Dienste oder nicht autorisierte Anforderungselemente werden mit der XBasisdaten-Fehlernachricht 901 quittiert und protokolliert.

WADL

Die für den Datenabruf notwendige WADL-Datei wird im Rahmen des Anbindungsprozesses durch das BVA bereitgestellt.

Es gibt je XBD Schnittstelle und XBasisdatenversion eine WADL Datei, welche die notwendigen REST Endpunkte bereitstellt.

Allgemeiner Überblick XBasisdaten

XBasisdaten ist ein XÖV-Standard des BVA für den elektronischen Datenaustausch mit registerführenden Stellen und weiteren öffentlichen Stellen im Rahmen des Identitätsdatenabrufs nach dem IDNrG.\ \ Dabei nimmt das BVA im Wesentlichen Abrufersuchen berechtigter Stellen entgegen, ruft die entsprechenden Basisdaten aus dem Steuer-ID-Datenbank des BZSt ab und übermittelt diese an die abrufenden Stellen. \ \ Rechtliche Grundlage für XBasisdaten ist die Verordnung zur Einführung des Datenübermittlungsstandards XBasisdaten (XBasisdatenV).

Die zentrale Plattform zur Bereitstellung und zum Bezug von XÖV-Standards und Codelisten - und somit auch zur Beschreibung des XBasisdaten-Standards des BVA -- ist das XRepository.

Hinweis: Das IDA-Verfahren ist um eine Version abwärtskompatibel und unterstützt somit die aktuelle und die vorherige XBasisdaten Version.

Veröffentlichungszeiträume der Versions-Updates sind i. d. R. im Mai und November eines jeden Jahres.

Tabelle 1: XBasisdaten: Prinzipielle Struktur

XML-Knoten	Kindelemente	Zweck
nachrichtenkopf	Identifikation (Nachrichtentypcode), Leser, Autor	Wer kommuniziert mit wem? Angaben zu den an der Kommunikation beteiligten fachlich zuständigen Behörden /öffentlichen Stellen sowie Angaben zur eindeutigen Identifikation der Nachricht
protokollierung	Anwenderkennung, Kontaktdaten	Wer fragt an? Angaben, die das BVA für die Protokollierung von Abrufersuchen und die Auskunft von Abfragen des Datenschutzcockpits benötigt.
ident	z.B. Name, Geburtstag, Anschrift	Zu wem wird abgefragt? Identifikationsmerkmale der Personen, für die der Abruf erfolgen soll
anforderungselement	Code-Liste (IdNr, Name, etc.)	Was wird abgefragt? Daten, die die abrufende Stelle für die Erfüllung ihrer Aufgaben benötigt und demnach in der Antwortnachricht erhalten möchte

Beispiel-Anfragen an IDA

Dieser Abschnitt enthält Beispiel-Anfragen für die in IDA verfügbaren Schnittstellen in Form von cURL-Requests. Hiermit können im Vorfeld bzw. während der Entwicklung des Clients fachliche Abfragen getestet werden.

Beispiele für Verbindungstests finden Sie oben im Abschnitt 3.55.

Die nachfolgenden Anwendungsfälle sind in der XBasisdaten-Spezifikation und im IDA-Anbindungsleitfaden näher beschrieben. Erläuterungen zu den in Beispielen verwendeten Umgebungsvariablen finden Sie in Anhang.

Authentifizierung gegen IDA

Bevor Requests gegen die Datenabruf-Schnittstellen von IDA ausgeführt werden können, muss an der Token-Schnittstelle des IDA-IAM (Keycloak) ein OAuth2 Bearer Token abgerufen werden, das in allen Requests gegen IDA im Authorization-Header gesetzt werden muss. Jedes Token hat eine Gültigkeitsdauer von 30 Minuten und kann innerhalb dieses Zeitraums für Abfragen (wieder)verwendet werden.

cURL:

curl -X POST\
-L "https://${IDA_IAM_HOST}/realms/bva-ida/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}\
&client_secret=${CLIENT_SECRET}&grant_type=client_credentials" \
--cert ${CLIENT_CERT}\
--key ${CLIENT_CERT_PRIVATE_KEY} \
--cacert ${IDA_CA_CERT}

Datenabrufe mit Personendaten (Einzeldatenabruf)

Eine abrufende Stelle benötigt für die Erfüllung ihrer Aufgaben zur Erbringung von Verwaltungsleistungen nach dem Onlinezugangsgesetz Basisdaten zu einer bei ihr gespeicherten Person, bspw. um für die Person die IDNr über das IDA-Verfahren abzurufen. Dafür erstellt die abrufende Stelle ein Abrufersuchen inklusive der Personendaten (Identifikationsmerkmale und ggf. IdentifikationsmerkmaleOptional) zu einer Person sowie der benötigten Anforderungselemente und übermittelt das Abrufersuchen an das BVA.

Im Erfolgsfall erhält die abrufende Stelle die IDNr sowie die weiteren angeforderten (Basis-)Daten zu dieser Person.

Beispielaufruf mit cURL mit XBD 1.5:

curl -X POST \
-L "https://${IDA_SGW_HOST}/ida/rest/v1_5/datenabruf/person" \
-H "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
 -H "Content-Type: application/xml" \
 -d \@request-abruf-personendaten.xml \
--cert "${CLIENT_CERT}" \
--key "${CLIENT_CERT_PRIVATE_KEY}"\
 --cacert "${IDA_CA_CERT}"

request-abruf-personendaten.xml

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <urn:abruf.personendaten.0101 produkt="IDA" produkthersteller="Bundesverwaltungsamt" produktversion="19.0.1"
    standard="XBasisdaten" version="1.5"
      xmlns:urn="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:abrufe_1.5"
      xmlns:urn1="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:baukasten_1.5">
      <nachrichtenkopf.g2g>
        <identifikation.nachricht>
          <nachrichtenUUID>[NACHRICHTENUUID]</nachrichtenUUID>
          <nachrichtentyp>
            <code>[0101]</code>
          </nachrichtentyp>
          <erstellungszeitpunkt>[ERSTELLUNGSZEITPUNKT]</erstellungszeitpunkt>
        </identifikation.nachricht>
        <leser>
          <verzeichnisdienst listVersionID="2">
            <code>IDA-BHVZ</code>
          </verzeichnisdienst>
          <kennung>100100</kennung>
          <name>Bundesverwaltungsamt</name>
        </leser>
        <autor>
          <verzeichnisdienst listVersionID="2">
            <code>[CODE]</code>
          </verzeichnisdienst>
          <kennung>[KENNUNG]</kennung>
          <name>[NAME]</name>
        </autor>
      </nachrichtenkopf.g2g>
      <urn:protokollierung>
        <urn1:anwenderkennung>[ANWENDERKENNUNG]</urn1:anwenderkennung>
        <urn1:kontaktdaten>[KONTAKTDATEN]</urn1:kontaktdaten>
        <urn1:kontaktdaten>[KONTAKTDATEN]</urn1:kontaktdaten>
      </urn:protokollierung>
      <urn:identifikationsmerkmale>
        <urn1:familienname>[FAMILIENNAME]</urn1:familienname>
        <urn1:geburtstag>[GEBURTSTAG]</urn1:geburtstag>
        <urn1:anschrift>
          <urn1:inland>
            <urn1:postleitzahl>[POSTLEITZAHL]</urn1:postleitzahl>
            <urn1:wohnort>[WOHNORT]</urn1:wohnort>
          </urn1:inland>
        </urn1:anschrift>
      </urn:identifikationsmerkmale>
      <urn:identifikationsmerkmaleOptional>
        <urn1:vornamen>[VORNAMEN]</urn1:vornamen>
      </urn:identifikationsmerkmaleOptional>
      <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
      <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
      <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
    </urn:abruf.personendaten.0101>

Platzhalter	Beschreibung
[NACHRICHTENUUID]	Identifikation.Nachricht.nachrichtenUUID
[0101]	XBasisdaten Nachrichtentypen
[ERSTELLUNGSZEITPUNKT]	Identifikation.Nachricht.erstellungszeitpunkt
Leser	nachrichtenkopf.leser.BehoerdeOeffStelle
IDA-BHVZ	Verzeichnisdienst
100100	Kennung
Bundesverwaltungsamt	Name
Autor	nachrichtenkopf.autor.BehoerdeOeffStelle
[CODE]	Verzeichnisdienst
[KENNUNG]	Kennung
[NAME]	Name
Protokollierung	protokollierung
[ANWENDERKENNUNG]	anwenderkennung
[KONTAKTDATEN]	kontaktdaten (bis zu 10 Sätze)
Identifikationsmerkmale	identifikationsmerkmale
[FAMILIENNAME]	Familienname
[GEBURTSTAG]	Geburtstag
[POSTLEITZAHL]	Postleitzahl
[WOHNORT]	Wohnort
Optionale Identifikationsmerkmale	identifikationsmerkmaleOptional
[VORNAMEN]	Vornamen
[CODE]	Anforderungselemente auf Basis IDNrG max. 16 Elemente

Massendatenabrufe für die initiale Zuordnung

Mit dem Prozess der initialen Zuordnung stellt XBasisdaten Anwendungsfälle bereit, mit den registerführende Stellen die erstmalige Datenübermittlung der IDNr und der (Basis-)Daten für alle Personen in ihrem Datenbestand ersuchen können. Dieser Prozess zeichnet sich dadurch aus, dass (1) in einem Abrufersuchen auf initiale Zuordnung Daten für eine Vielzahl von Personen abgerufen werden können und (2) im Rahmen der erstmaligen Datenübermittlung der IDNr auch Daten von Personen abgerufen werden können, für die eine Auskunftssperre nach dem Bundesmeldegesetz vorliegt (vgl. § 6 Abs. 5 IDNrG).

Ein Abrufersuchen auf initiale Zuordnung wird in der Regel Identifikationsdaten für eine Vielzahl von Personen enthalten, sodass die Bereitstellung der Ergebnisse im Zusammenspiel von dem IDA-Verfahren des BVA und der Steuer-ID-Datenbank des BZSt eine im Vergleich zu Einzelabrufen längere Zeit in Anspruch nehmen wird. Der Gesamtprozess zur initialen Zuordnung ist daher als fachlich asynchrone Kommunikation ausgestaltet.

Abrufersuchen für initiale Zuordnung

Die registerführende Stelle erstellt das aktuell vorgesehene Abrufersuchen (Nachricht 0301). Für jeden dem Abrufersuchen zugeordneten Personendatensatz werden die Identifikationsmerkmale zusammen mit der RSID in das Element zuIdentifizierendePerson eingetragen und die für die initiale Zuordnung bestimmten Anforderungselemente in die Elemente anforderungselement. Die IDNr und der Tag der Geburt stellen den minimalen Abrufumfang dar und können daher nicht durch Anforderungselemente angefordert werden.

Beispielaufruf mit cURL mit XBD 1.5:

curl -X POST \
-L "https://${IDA_SGW_HOST}/ida/rest/v1_5/massendatenabruf/initialezuordnung/abrufersuchen" \
-H "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
 -H "Content-Type: application/xml" \
 -d \@request-abruf-initiale-zuordnung-erstanlage.xml \
--cert "${CLIENT_CERT}" \
--key "${CLIENT_CERT_PRIVATE_KEY}"\
 --cacert "${IDA_CA_CERT}"

request-abruf-initiale-zuordnung-erstanlage.xml

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <urn:abruf.initial.0301 produkt="IDA" produkthersteller="Bundesverwaltungsamt" produktversion="19.0.1"
    standard="XBasisdaten" version="1.5"
      xmlns:urn="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:abrufe_1.5"
      xmlns:urn1="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:baukasten_1.5">

      <nachrichtenkopf.g2g>
                  <identifikation.nachricht>
          <nachrichtenUUID>[NACHRICHTENUUID]</nachrichtenUUID>
          <nachrichtentyp>
            <code>[0301]</code>
          </nachrichtentyp>
          <erstellungszeitpunkt>[ERSTELLUNGSZEITPUNKT]</erstellungszeitpunkt>
        </identifikation.nachricht>
        <leser>
         <verzeichnisdienst listVersionID="2">
            <code>[CODE]</code>
          </verzeichnisdienst>
          <kennung>[KENNUNG]</kennung>
          <name>[NAME]</name>
        </leser>
        <autor>
          <verzeichnisdienst listVersionID="2">
            <code>IDA-BHVZ</code>
          </verzeichnisdienst>
          <kennung>100100</kennung>
          <name>Bundesverwaltungsamt</name>
        </autor>
      </nachrichtenkopf.g2g>
      <urn:protokollierung>
        <urn1:anwenderkennung>[ANWENDERKENNUNG]</urn1:anwenderkennung>
        <urn1:kontaktdaten>[KONTAKTDATEN]</urn1:kontaktdaten>
        <urn1:kontaktdaten>[KONTAKTDATEN]</urn1:kontaktdaten>
      </urn:protokollierung>
      <urn:zuIdentifizierendePerson rsID="RSID">

       <urn:identifikationsmerkmale>
          <urn1:familienname>[FAMILIENNAME]</urn1:familienname>
          <urn1:geburtstag>[GEBURTSTAG]</urn1:geburtstag>
          <urn1:anschrift>
            <urn1:inland>
              <urn1:postleitzahl>[POSTLEITZAHL]</urn1:postleitzahl>
              <urn1:wohnort>[WOHNORT]</urn1:wohnort>
            </urn1:inland>
          </urn1:anschrift>
        </urn:identifikationsmerkmale>
        <urn:identifikationsmerkmaleOptional>
          <urn1:vornamen>[VORNAMEN]</urn1:vornamen>
        </urn:identifikationsmerkmaleOptional>

      </urn:zuIdentifizierendePerson>


      <!-- ... hier können weitere Elemente vom Typ "zuIdentifizierendePerson" folgen:
      <urn:zuIdentifizierendePerson rsID="RSID">
          ...
      </urn:zuIdentifizierendePerson>
      ...
      -->
       <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
      <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
      <urn:anforderungselement>
        <code>[CODE]</code>
      </urn:anforderungselement>
  </urn:abruf.initial.0301>

Platzhalter	Beschreibung
[NACHRICHTENUUID]	Identifikation.Nachricht.nachrichtenUUID
[0301]	XBasisdaten Nachrichtentypen
[ERSTELLUNGSZEITPUNKT]	Identifikation.Nachricht.erstellungszeitpunkt
Leser	nachrichtenkopf.leser.BehoerdeOeffStelle
IDA-BHVZ	Verzeichnisdienst
100100	Kennung
Bundesverwaltungsamt	Name
Autor	nachrichtenkopf.autor.BehoerdeOeffStelle
[CODE]	Verzeichnisdienst
[KENNUNG]	Kennung
[NAME]	Name
Protokollierung	protokollierung
[ANWENDERKENNUNG]	anwenderkennung
[KONTAKTDATEN]	kontaktdaten (bis zu 10 Sätze)
Identifikationsmerkmale	identifikationsmerkmale
[FAMILIENNAME]	Familienname
[GEBURTSTAG]	Geburtstag
[POSTLEITZAHL]	Postleitzahl
[WOHNORT]	Wohnort
Optionale Identifikationsmerkmale	identifikationsmerkmaleOptional
[VORNAMEN]	Vornamen
[CODE]	Anforderungselemente auf Basis IDNrG max. 16 Elemente

Antwort mit Auftragsnummer

Im Falle einer erfolgreichen Eingangsprüfung erstellt das BVA die Nachricht 0302 mit dem Code 1 aus der Codeliste Statusangaben Massendatenabrufe im Element status und versendet sie an die registerführende Stelle.

Beispiel Antwortnachricht 0302 mit Auftragsnummer:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <urn:abruf.initial.0302 produkt="IDA" produkthersteller="Bundesverwaltungsamt" produktversion="19.0.1"
    standard="XBasisdaten" version="1.5"
      xmlns:urn="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:abrufe_1.5"
      xmlns:urn1="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:baukasten_1.5">

      <nachrichtenkopf.g2g>
          <identifikation.nachricht>
              <nachrichtenUUID>[NACHRICHTENUUID]</nachrichtenUUID>
              <nachrichtentyp>
                  <code>[0302]</code>
              </nachrichtentyp>
              <erstellungszeitpunkt>[ERSTELLUNGSZEITPUNKT]</erstellungszeitpunkt>
          </identifikation.nachricht>
          <leser>
              <verzeichnisdienst listVersionID="2">
                  <code>[CODE]</code>
              </verzeichnisdienst>
              <kennung>[KENNUNG]</kennung>
              <name>[NAME]</name>
          </leser>
          <autor>
              <verzeichnisdienst listVersionID="2">
                  <code>IDA-BHVZ</code>
              </verzeichnisdienst>
              <kennung>100100</kennung>
              <name>Bundesverwaltungsamt</name>
          </autor>
      </nachrichtenkopf.g2g>
      <ns3:auftragsnummer>[AUFTRAGSNUMMER]</ns3:auftragsnummer>
      <ns3:status listVersionID="1">
          <code>[CODE]</code>
      </ns3:status>
  </ns3:abruf.initial.0302>

Platzhalter	Beschreibung
[NACHRICHTENUUID]	Identifikation.Nachricht.nachrichtenUUID
[0301]	XBasisdaten Nachrichtentypen
[ERSTELLUNGSZEITPUNKT]	Identifikation.Nachricht.erstellungszeitpunkt
Leser	nachrichtenkopf.autor.BehoerdeOeffStelle
[CODE]	Verzeichnisdienst
[KENNUNG]	Kennung
[NAME]	Name
Autor	nachrichtenkopf.leser.BehoerdeOeffStelle
IDA-BHVZ	Verzeichnisdienst
100100	Kennung
Bundesverwaltungsamt	Name
Bestätigung Abrufersuchen
[AUFTRAGSNUMMER]	(https://www.xrepository.de/api/xrepository/urn:xoev-de:bva:standard:xbasisdaten_1.5:dokument:Spezifikation_XBasisdaten_V1.5:datei:2024-01-31_XBasisdaten_1.5_final.pdf#%5B%7B%22num%22%3A2498%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C70.866%2C478.005%2Cnull%5D)
[CODE]	(https://www.xrepository.de/details/urn:xoev-de:xbasisdaten:codeliste:statusmassendatenabruf)

Ergebnisabruf mit Auftragsnummer

Im Prozess Ergebnisabruf ruft die registerführende Stelle zu einem späteren Zeitpunkt mithilfe der Auftragsnummer die Ergebnisse des Ersuchens beim BVA ab.

Beispielaufruf mit cURL:

curl -X POST \
-L "https://${IDA_SGW_HOST}/ida/rest/v1_5/massendatenabruf/initialezuordnung/ergebnis" \
-H "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
 -H "Content-Type: application/xml" \
 -d \@request-abruf-initial.xml \
--cert "${CLIENT_CERT}" \
--key "${CLIENT_CERT_PRIVATE_KEY}"\
 --cacert "${IDA_CA_CERT}"

request-abruf-initial.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urn:massendatenabruf.initial.0303 produkt="string" produkthersteller="string" produktversion="string" standard="XBasisdaten" test="string" version="1.5"
    xmlns:urn="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:initialeZuordnung_1.5"
    xmlns:urn1="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:baukasten_1.5">
      <nachrichtenkopf.g2g>
          <identifikation.nachricht>
              <nachrichtenUUID>[NACHRICHTENUUID]</nachrichtenUUID>
              <nachrichtentyp>
                  <code>[0303]</code>
              </nachrichtentyp>
              <erstellungszeitpunkt>[ERSTELLUNGSZEITPUNKT]</erstellungszeitpunkt>
          </identifikation.nachricht>
          <leser>
              <verzeichnisdienst listVersionID="2">
                  <code>IDA-BHVZ</code>
              </verzeichnisdienst>
              <kennung>100100</kennung>
              <name>Bundesverwaltungsamt</name>
          </leser>
          <autor>
              <verzeichnisdienst listVersionID="2">
                  <code>[CODE]</code>
              </verzeichnisdienst>
              <kennung>[KENNUNG]</kennung>
              <name>[NAME]</name>
          </autor>
      </nachrichtenkopf.g2g>
    <urn:auftragsnummer>[AUFTRAGSNUMMER]</urn:auftragsnummer>
</urn:massendatenabruf.initial.0303>

Platzhalter	Beschreibung
[NACHRICHTENUUID]	Identifikation.Nachricht.nachrichtenUUID
[0302]	XBasisdaten Nachrichtentypen
[ERSTELLUNGSZEITPUNKT]	Identifikation.Nachricht.erstellungszeitpunkt
Leser	nachrichtenkopf.leser.BehoerdeOeffStelle
IDA-BHVZ	Verzeichnisdienst
100100	Kennung
Bundesverwaltungsamt	Name
Autor	nachrichtenkopf.autor.BehoerdeOeffStelle
[CODE]	Verzeichnisdienst
[KENNUNG]	Kennung
[NAME]	Name
Auftragsnummer aus Antwort zum Abrufersuchen
[AUFTRAGSNUMMER]	(https://www.xrepository.de/api/xrepository/urn:xoev-de:bva:standard:xbasisdaten_1.5:dokument:Spezifikation_XBasisdaten_V1.5:datei:2024-01-31_XBasisdaten_1.5_final.pdf#%5B%7B%22num%22%3A2498%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C70.866%2C478.005%2Cnull%5D)

Ergebnis des Abrufs

Sofern das im Ergebnisabruf angegebene Abrufersuchen vollständig bearbeitet ist, bereitet das BVA Ergebnisse aus der Steuer-ID-Datenbank des BZSt auf. Daraufhin erstellt und versendet sie die Nachricht 0304 und gibt für jeden im ursprünglichen Abrufersuchen enthalten Datensatz das Ergebnis des Abrufs an.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:massendatenabruf.initial.0304 produkt="IDA" produkthersteller="Bundesverwaltungsamt, Registermodernisierungsbehörde" produktversion="19.0.1" standard="XBasisdaten" version="1.5"
    xmlns:ns2="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:initialeZuordnung_1.5"
    xmlns:ns3="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:massenabrufmitidnr_1.5"
    xmlns:ns4="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:baukasten_1.5"
    xmlns:ns5="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:abrufe_1.5"
    xmlns:ns6="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:mitteilungen_1.5"
    xmlns:ns7="urn:xoev-de:bva:standard:xbasisdaten:schema:xsd:administration_1.5">
    <nachrichtenkopf.g2g>
          <identifikation.nachricht>
              <nachrichtenUUID>[NACHRICHTENUUID]</nachrichtenUUID>
              <nachrichtentyp>
                  <code>[0304]</code>
              </nachrichtentyp>
              <erstellungszeitpunkt>[ERSTELLUNGSZEITPUNKT]</erstellungszeitpunkt>
          </identifikation.nachricht>
          <leser>
              <verzeichnisdienst listVersionID="2">
                  <code>[CODE]</code>
              </verzeichnisdienst>
              <kennung>[KENNUNG]</kennung>
              <name>[NAME]</name>
          </leser>
          <autor>
              <verzeichnisdienst listVersionID="2">
                  <code>IDA-BHVZ</code>
              </verzeichnisdienst>
              <kennung>100100</kennung>
              <name>Bundesverwaltungsamt</name>
          </autor>
      </nachrichtenkopf.g2g>
    <ns2:auftragsnummer>[AUFTRAGSNUMMER]</ns2:auftragsnummer>
    <ns2:ergebnis rsID="RSID">
        <ns2:auskunft>
            <ns4:idNr>[IDNR]</ns4:idNr>
            <ns4:familienname nichtVorhanden="false">[FAMILIENNAME]</ns4:familienname>
            <ns4:vornamen nichtVorhanden="false">[VORNAMEN]</ns4:vornamen>
            <ns4:geburtstag>[GEBURTSTAG]</ns4:geburtstag>
            <ns4:geburtsort>
                <ns4:ort>[GEBURTSORT]</ns4:ort>
            </ns4:geburtsort>
            <ns4:geschlecht listURI="urn:xoev-de:xbasisdaten:codeliste:geschlecht" listVersionID="1">
                <code>[CODE]</code>
            </ns4:geschlecht>
            <ns4:staatsangehoerigkeit listURI="urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staatsangehoerigkeit" listVersionID="1">
                <code>{CODE}</code>
            </ns4:staatsangehoerigkeit>
            <ns4:anschrift letzteBekannteAnschrift="false">
                <ns4:strasse>[STRASSE]</ns4:strasse>
                <ns4:hausnummer>[HUASNUMMER]</ns4:hausnummer>
                <ns4:postleitzahl>[POSTLEITZAHL](https://www.xrepository.de/api/xrepository/urn:xoev-de:bva:standard:xbasisdaten_1.5:dokument:Spezifikation_XBasisdaten_V1.5:datei:2024-01-31_XBasisdaten_1.5_final.pdf#%5B%7B%22num%22%3A216%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C70.866%2C727.937%2Cnull%5D)</ns4:postleitzahl>
                <ns4:wohnort>[WOHNORT](https://www.xrepository.de/api/xrepository/urn:xoev-de:bva:standard:xbasisdaten_1.5:dokument:Spezifikation_XBasisdaten_V1.5:datei:2024-01-31_XBasisdaten_1.5_final.pdf#%5B%7B%22num%22%3A216%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C70.866%2C727.937%2Cnull%5D)</ns4:wohnort>
                <ns4:gemeindeschluessel>[GEMEINDESCHLUESSEL]</ns4:gemeindeschluessel>
            </ns4:anschrift>
            <ns4:tagEinzug>[TAGEINZUG]</ns4:tagEinzug>
            <ns4:letzterVerwaltungskontakt>[LETZTERVERWALTUNGSKONTAKT]</ns4:letzterVerwaltungskontakt>
        </ns2:auskunft>
    </ns2:ergebnis>
    <!-- mögliche weitere Ergebnisse -->
    <ns2:ergebnis rsID="RSID">
        <!-- … -->
    </ns2:ergebnis>
</ns2:massendatenabruf.initial.0304>

Tabelle 2: Beschreibung und Beispiele

Node-/Attribute-Name	Beschreibung	Beispiel(e)
nachrichtenUUID	Die UUID der Nachricht (Typ 4)	fcba7f99-a67d-4120-bcef-8e7649a00435
nachrichtentyp.code	Code aus der Codeliste „XBasisdaten Nachrichtentypen“, dieser muss zwingend mit dem Code im äußersten XML-Element übereinstimmen	0101
erstellungszeitpunkt	enthält den Erstellungszeitpunkt der Nachricht	2024-09-29T14:48:01.009+01:00
verzeichnisdienst.code	Verzeichnisdienst, in welchem die Behörde/öffentliche Stelle eingetragen ist	DVDV, IDA-BHVZ
leser/autor.kennung	Behördenkennzeichen der Behörde/öffentlichen Stelle	100100
leser/autor.name	Name der Behörde / öffentlichen Stelle	Bundesverwaltungsamt, Registermodernisierungsbehörde
protokollierung.anwenderkennung	die Anwenderkennung der für das Abrufersuchen verantwortlichen Person oder im Rahmen von automatisierten Abrufen die Kennung des technischen Nutzers
protokollierung.kontaktdaten	Kontaktdaten des Verantwortlichen im Sinne von Artikel 30 Abs. 1 a) DSGVO
identifikationsmerkmale.familienname	der Familienname einer Person als Identifikationsmerkmal	Schmidt
identifikationsmerkmale.geburtstag	Angaben zum Tag der Geburt einer Person als Identifikationsmerkmal	1982-09-29, 1982-09, 1982
identifikationsmerkmale.idnr	Identifikationsnummer einer Person gemäß § 4 Abs. 2 IDNrG	47110815123
auftragsnummer	die dem Abrufersuchen zugeordnete Auftragsnummer,UUID Version 4	8771fcf8-4fff-4da9-9918-6887916d585b
status.code	Statusangabe eines Abrufersuchens	1 = Bestätigung Abrufersuche 2 = In Bearbeitung
auskunft.geschlecht		d,m,w,x

Best Practices zur Initialen Zuordnung

Die Initiale Zuordnung von Personendaten erfolgt über das im XBasisdaten-Standard definierte Polling-Verfahren. Auch wenn eine initiale Zuordnung per Einzelnachricht ebenfalls möglich ist, ist ein Abruf per Sammelnachricht die bevorzugte Variante, Abweichungen hiervon sollten mit dem BVA abgestimmt werden.

Eine detaillierte Beschreibung des Verfahrens befindet sich in der XBasisdaten Spezifikation im Kapitel "Initiale Zuordnung - Polling".

Bei der Implementierung des Clients für die Initiale Zuordnung in den Registern gibt es einige Besonderheiten zu berücksichtigen, die im Folgenden beschrieben werden.

Limitierung der Anzahl von Personen pro Nachricht:

Die Anzahl der Personen, die über eine Sammelnachricht zur Initialen Zuordnung abgefragt werden können, wird aktuell nicht durch das XSD-Schema der XBasisdaten-Nachricht beschränkt.

Aktuell sollten hierbei 200 Personen pro Sammelnachricht nicht überschritten werden, um eine zuverlässige Verarbeitung der Sammelnachrichten durch IDA gewährleisten zu können.

Parallelisierungsgrad der Anfragen

Damit alle Personen eines Registers initial zugeordnet werden können, müssen diese i.d.R. auf sehr viele Sammelnachrichten aufgeteilt werden.

Um eine fehlerfreie und zuverlässige Verarbeitung aller Sammelnachrichten durch IDA gewährleisten zu können, sollten nicht mehr als 10 parallele Anfragen (i.e. multi-threaded) durch die Client Anwendung abgesendet werden auf deren Bearbeitung dann zunächst gewartet werden muss.

Die aktuelle Empfehlung ist daher, nicht mehr als 10 Sammelnachrichten parallel abzusenden bzw dafür zu sorgen, dass nicht mehr als 10 Anfragen pro Client gleichzeitig auf eine Antwort warten.

Abruf der Antworten ("Polling")

Für den Abruf des Ergebnisses der Initialen Zuordnung über die Polling-Schnittstelle sollte clientseitig ein Delay konfigurierbar sein. Bei bisherigen Initialen Zuordnungen wurde mit einem Delay von 5 Sekunden zwischen den Abfragen gearbeitet.

Grund hierfür ist, dass die Weiterleitung und Verarbeitung der Aufträge eine gewisse Zeit dauert und Aufrufe der Polling-Schnittstelle in dieser Zeit zu unnötiger Last auf dem IDA-System führen.

Konfigurierbarkeit des Clients

Die Empfehlungen für die oben beschriebenen Parameter (Limit Anzahl Personen pro Anfragenachricht, Parallelisierungsgrad der Anfragen) können sich im Rahmen der Weiterentwicklung des IDA-Verfahrens ändern.

Aus diesem Grund sollten die Parameter in der Client Anwendung per Konfiguration anpassbar sein.

Automatische Löschung von Ergebnisdaten durch IDA

Bereits abgerufene Ergebnisse der asynchronen (Erst)Abfragen werden für 60 Minuten vorgehalten und anschließend gelöscht, d.h. sie sind dann nicht mehr unter der bestehenden Auftragsnummer abrufbar.

Noch nicht abgerufene Ergebnisse der asynchronen (Erst)Abfragen werden für 48 Stunden vorgehalten und anschließend gelöscht, d.h. sie sind nicht mehr unter der bestehenden Auftragsnummer abrufbar.

Erfahrungsbericht Nationales Waffenregister (NWR)

Die technische Erprobung des IDA-Verfahren wurden mit dem NWR durchgeführt. Die damit verbundenen Vorbereitungen und Erfahrungen wurden in einem Kurzbericht aufbereitet und können unter folgendem Link abgerufen werden: Erfahrungsbericht des NWR