BayernPortal (SOAP Schnittstelle) - Version 3

Diese Dokumentation für die SOAP-Schnittstelle in der Version 3 richtet sich in erster Linie an IT-Dienstleister und Entwickler, die Daten aus dem BayernPortal in kommunale oder staatliche Webauftritte integrieren wollen.

Wir möchten Nutzern früherer Versionen der SOAP-Schnittstelle einen möglichst einfachen Upgrade ermöglichen und übernehmen deshalb in dieser Version alle Endpunkte der Vorgängerversionen. Andererseits sollen aber auch neue Features bzw. Erweiterungen des Datenmodells realisiert werden. Daher gibt es auch ein paar zusätzliche neue Endpunkte und kleine Erweiterungen im XML-Datenmodell.

Zur Authentifizierung müssen Sie in der Anfrage genau einen SOAP-Header mitschicken, nämlich einen UsernameToken-Header nach der WS-Security-Spezifikation:

Beispiel:

<soapenv:Header>
 <wsse:Security soapenv:mustUnderstand="1"
   xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  
  <wsse:UsernameToken wsu:Id="UsernameToken-15703">
    <wsse:Username>
      username
    </wsse:Username>
    <wsse:Password 
     Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
      password
    </wsse:Password>
   </wsse:UsernameToken>

 </wsse:Security>
</soapenv:Header>
                        

Weitere Security-Header sind im Gegensatz zu früheren Versionen der allgemeinen SOAP-Webservices nicht mehr erforderlich.

Die ausführliche Dokumentation für die Versionen 1, 2 und 3 finden sie im Dokument Gesamtdokumentation (PDF).
Die SOAP Schnittstelle der Version 3 ermöglichen einen relativ unkomplizierten Umstieg von den Vorgänger-Versionen. Abweichungen und Erweiterungen der Version 3 gegenüber früheren Versionen beschreiben wir in den folgenden Abschnitten.

Die Berechtigung für die verschieden Endpunkte wird den Benutzern über die gleichen Rollen erteilt, die auch für die Versionen 1 und 2 gelten. Sie können also die Version 3 mit der gleichen Kennung und den gleichen Rechten nutzen, wie die Vorgängerversionen.

Erweiterungen und Anpassungen in Version 3

Hier sind die Anpassungen und Erweiterungen gegenüber früheren Versionen der allgemeinen Webservices beschrieben.

Webservice "Behörden, Gebäude und Ansprechpartner allgemein - Version 3 (WSDL - XML)"

Bei diesem Webservice gibt es folgende neuen Endpunkte:

  • GetDienststellen - Liefert alle Dienststellen (inkl. Außenstellen), auf die der Benutzer Zugriff hat. Bei Angabe des optionalen Elements dienststellenschluessel werden nur Dienststellen geliefert, zu denen der 7-stellige Dienststellenschlüssel passt. Ersetzt den Endpunkt GetDienststelle der Webservice-Versionen 1 und 2.
    Das Ergebnis ist im Response in einen neuen zusätzlichen Container dienststellen > dienststelle eingepackt (Angleichung an das REST API).
  • GetBehoerden - Liefert alle Behörden (Dienststellen, Außenstellen, Organisationseinheiten), auf die der Benutzer Zugriff hat
  • GetAnsprechpartner - Liefert behördenübergreifend alle Ansprechpartner, auf die der Benutzer Zugriff hat. Bei Angabe des optionen Elements ansprechpartnerId werden nur Daten zu dem Ansprechpartner mit der angegebenen Id geliefert.
    Das Ergebnis ist im Response in einen neuen zusätzlichen Container ansprechparter > ap eingepackt (Angleichung an das REST API).
Optionale Attribute
Attributname Zulässige Werte Gültig für Request
full true=vollständige Objekte.
false=Kurzformen der Objekte
GetDienststellen
GetBehoerden
GetAnsprechpartner
page 0-basierter Index der anzuzeigenden Teilseite / Teilmenge

default: 0
min: 0
max: [positive Ganzahl] = Menge aller gefundenen Objekte - 1
GetDienststellen
GetBehoerden
size Anzahl der Objekte pro Teilseite / Teilmenge

default: 100
min: 1
max: 100
GetDienststellen
GetBehoerden

Für die Anfragen der drei neuen Endpunkte gibt es jeweils ein optionales Attribut (full). Wenn dieses gesetzt ist und den Wert true hat, dann werden vollständige Objekte (Dienststelle, Behörde, Ansprechpartner) geliefert, andernfalls nur Kurzformen.

Bei Angabe eines optionalen Attributs (page). Wenn dieses gesetzt ist und den Wert true hat, dann werden vollständige Objekte (Dienststelle, Behörde, Ansprechpartner) geliefert, andernfalls nur Kurzformen.

Für die Anfragen der drei neuen Endpunkte gibt es jeweils ein optionales Attribut (full). Wenn dieses gesetzt ist und den Wert true hat, dann werden vollständige Objekte (Dienststelle, Behörde, Ansprechpartner) geliefert, andernfalls nur Kurzformen.

Außerdem gibt es im Datenmodell einer Behörde das folgende zusätzliche Element:

Neues-XML-Element
Elementbezeichnung Anmerkung
deMail De-Mail-Adresse der Dienststelle, Behörde oder Organisationseinheit

Im Datenmodell einer Behörde / Dienststelle wurden folgenden Elemente zu optionalen Elementen ( minOccurs="0" ) erklärt, weil sie in der Kurzform nicht ausgeliefert werden:

Zukünftig optionale-XML-Elemente
Elementbezeichnung Anmerkung
behoerdeZuordnungen nachgeordnete Behörden
behoerdenGebaeudeZuordnungen Gebäudezuordnungen
mitgliedVonVerwaltungsgemeinschaft Verwaltungsgemeinschaft, deren Mitglied die (Gemeinde-)Behörde ist

Leistungen allgemein - Version 3 (WSDL - XML)

Der Endpunkt "GetLeistungsbeschreibungenVonDienststelle" mit seinen Anfrage-Optionen ermöglicht es, regionale Ergänzungen und zuständige Stellen "nach Dienststelle" gefiltert abzufragen. Der Endpunkt liefert "eigene" regionale Ergänzungen der Dienststelle und "eigene" Zuständigkeiten der Dienststelle. Diese Leistungsbeschreibungen müssen somit nicht einzeln über den Endpunkt "GetSingleLeistungsbeschreibung" abgerufen werden.

Statt vieler kurz laufender Anfragen kann nun eine etwas länger laufende Anfrage ("GetLeistungsbeschreibungenVonDienststelleRequest") gesendet werden. Jedoch ist die Antwortzeit der Anfrage länger und die übertragene Datenmenge deutlich größer. Das ist aber bei ausreichender Bandbreite in der Regel besser, als sehr viele Einzelanfragen.

Folgende neuen Elemente wurden hinzugefügt:

GetAlleLeistungsbeschreibungenRequest
Elementbezeichnung Typ Kardinalität Bedeutung
mitRegionalenErgaenzungen boolean optional

false (oder nicht vorhanden):

regionale Ergänzungen werden nicht ausgeliefert (default)

true

regionale Ergänzungen zu Leistungsbeschreibungen werden ausgeliefert

GetLeistungsbeschreibungenVonDienststelleRequest
Elementbezeichnung Typ Kardinalität Bedeutung
mitRegionalenErgaenzungen boolean optional

false (oder nicht vorhanden):

Regionale Ergänzungen werden nicht ausgeliefert (default)

true

Regionale Ergänzungen zu Leistungsbeschreibungen werden ausgeliefert, und zwar nur solche, für die die Dienststelle mit dem angegebenen Dienststellenschlüssel redaktionell zuständig ist (eigene regionale Ergänzungen).

Im Gegensatz zur den Endpunkten "GetAlleLeistungsbeschreibungenRequest" und "GetSingleLeistungsbeschreibungRequest" spielt das optionale Element "gemeindekennziffer" für die Auswahl der passenden regionalen Ergänzungen keine Rolle. Es kann also auch weggelassen werden.

mitZustaendigkeiten boolean optional

true (oder nicht vorhanden):

Zuständige Stellen werden mit jeder Leistungsbeschreibung ausgeliefert. (default).

Es werden aber nur Organisationseinheiten berücksichtigt, die zur Dienststelle mit dem angegebenen "dienststellenschluessel" gehören, also die Dienststelle selbst, ihre Aussenstellen und alle Organisationseinheiten dieser Dienststelle oder ihrer Aussenstellen.

Im Gegensatz zum Endpunkt "GetSingleLeistungsbeschreibungRequest" spielt das optionale Element "gemeindekennziffer" für die Ermittlung der zuständigen Stellen überhaupt keine Rolle. Es kann auch weggelassen werden.

false

Zuständige Stellen werden nicht ausgeliefert

GetAlleLeistungsbeschreibungenResponse,
GetAlleLeistungsbeschreibungenVonDienststelleResponse,
GetSingleLeistungsbeschreibungRepsonse
Elementbezeichnung Kardinalität Bedeutung
leistungsbeschreibung > verfahrensablauf
optional Skizze zum Ablauf des Verwaltungsverfahrens (Prozess)
leistungsbeschreibung > hinweise
optional Hinweise, die im Zusammenhang mit der Leistung beachtet werden sollten
leistungsbeschreibung > bearbeitungsdauer
optional Angaben zur durchschnittlichen Bearbeitungsdauer
leistungsbeschreibung > formulare > formular [vorausfuellbar="true"/"false"]
required

true:

Das Formular ist mit den Empfängerdaten der zuständigen Behörde vorbelegt, wenn genau eine Behörde für diese Leistung zuständig ist. Wenn mehrere Behörden zuständig sind, kann das Formular leider nicht vorausgefüllt werden.

false:

Das Formular kann nicht vorbelegt werden.

Das neue Attribut wird geliefert, damit der Client Links auf vorausfüllbare Formulare bei der Darstellung (z.B. durch ein spezielles Symbol oder durch einen Texthinweis) optisch kennzeichnen kann.

leistungsbeschreibung > formulare > formular > schriftformErfordernis required

Angaben zur Schriftformerfordernis

Beispiel:

<schriftformErfordernis>
                    <id>1</id>
                    <beschreibung>
                        Dieses Formular muss unterschrieben (manuell oder elektronisch)
                        an die zuständige Stelle gesendet werden
                        (per Post, Fax oder geschützte E-Mail).
                    </beschreibung>
                </schriftformErfordernis>

Mögliche Ausprägungen sind:

  • ID 1: ja - Unterschrift rechtlich vorgeschrieben
  • ID 2: ja - Unterschrift und persönliches Erscheinen rechtlich vorgeschrieben
  • ID 3: nein - keine Unterschrift rechtlich vorgeschrieben

Die neuen Elemente werden geliefert, damit der Client Verweise auf die jeweiligen Formulare durch ein spezielles Symbol kennzeichnen oder mit Erläuterungen versehen kann. Als Erläuterung ist das Element "beschreibung" am besten geeignet.

Lebenslagen allgemein - Version 3 (WSDL - XML)

Hier gibt es folgende Neuerungen:

GetAlleLebenslagenRequest
Elementbezeichnung Type Kardinalität Bedeutung
leistungenZugeordnet boolean optional

false (oder nicht vorhanden):

Es werden alle Lebenslagen geliefert, auch solche ohne Leistungszuordnungen.

true

Es werden nur Lebenslagen mit zugeordneten Leistungen geliefert.

Neue Endpunkte:

  • GetLebenslagenVonDienststelle - Erlaubt das Abfragen von Lebenslagen, die für eine Dienststelle passend sind. Es werden nur Lebenslagen zurückgeliefert, denen mindestens eine Leistung der Dienststelle zugeordnet ist. Als verpflichtendes Element ist bei der Anfrage ein 7-stelliger Dienststellenschlüssel anzugeben.
  • GetLebenslage - Erlaubt das Abfragen einer bestimmten Lebenslage. Hierzu muss bei der Anfrage als verpflichtendes Element eine gültige id einer Lebenslage angegeben werden (z.B.: 10000100).

Weggefallenes Element:

Im Datenmodell der Antworten "GetAlleLebenslagenResponse" und "GetLebenslageResponse" ist bei den Elementen <lebenslage> das eingeschachtelte Element <metaTag> weggefallen.

Formulare allgemein - Version 3 (WSDL - XML)

Dieser Webservice ist neu in Version 3 und bietet den Endpunkt GetFormulareVonDienststelle zum Abrufen aller Formulare, die den Leistungen einer bestimmten Dienststelle zugeordnet sind.

GetFormulareVonDienststelleRequest
Elementbezeichnung Type Kardinalität Bedeutung
dienststellenschluessel integer (7-stellig) required Dienststellenschlüssel der gewünschten Dienststelle (z.B.: 0318006 - Regierung von Oberbayern).
gemeindekennziffer integer (8-stellig) optional Das Angeben eines Gemeindeschlüssels in der Anfrage hat zwei Auswirkungen:
  • Er drückt aus, für welche Gemeinde das Ergebnis lokalisiert werden soll. Bei vorausfüllbaren Formularen, wird die Anschrift der Empfängerbehörde vorausgefüllt.
  • Der Webservice liefert dann auch alle Formulare die "Regionalen Ergänzungen" zugeordnet sind.
gruppiertNachLeistungen boolean optional Das Element hat Auswirkungen auf die Strukturierung der Ergebnisse:
  • true (Default): Es werden Leistungen zurückgeliefert, die die zugeordneten Formulare beinhalten. Die Formulare können somit nach Leistungen gegliedert angezeigt werden. (kurz: Formulare gegliedert nach Leistungen)
  • false: Es werden Formulare zurückgeliefert, die die Leistungen, denen sie zugeordnet sind, beinhalten. Es können die Formulare mit den zugehörigen Leistungen angezeigt werden. (kurz: Formulare mit den jeweils zugehörigen Leistungen).