Webdienst

Hinweis

Ihnen stehen zwei Möglichkeiten zur Verfügung, Ihre Clients an unseren Webdienst anzubinden:
  • Der Produktions-Webdienst unter der Adresse www.marktstammdatenregister.de/MaStRApi ist öffentlich verfügbar. Er dient dazu, externe Systeme an das Marktstammdatenregister anzubinden.
  • Der Test-Webdienst unter der Adresse test.marktstammdatenregister.de/MaStRApi ist nicht öffentlich verfügbar. Er dient dazu, Prozesse insbesondere die Netzbetreiberprüfung zu testen. Alle Netzbetreiber, die Zugriff auf das Testsystem des Marktstammdatenregister haben, können diesen Dienst uneingeschränkt für ihre Tests nutzen.
Interessierten Nutzern wird ein Entwicklungssystem angeboten. Auf dem Entwicklungsystem werden neue Funktionen schneller bereitgestellt, als auf den anderen Systemen. Weitere Informationen dazu können über den Support erhalten werden.

Allgemeine Informationen

Weitere nützliche, auf Ihre Entwicklungsumgebung bezogene Hinweise, finden sie hier:

  • Für Microsoft.NET:
    Bitte wählen Sie im Visual Studio "Service Referenz hinzufügen" und geben Sie die im ZIP-Archiv hinterlegte WSDL-Datei an. Alternativ können Sie auch das Util "svcutil.exe Api.svc?wsdl" verwenden.
  • Für JAVA:
    Bitte schauen Sie auf folgende Dokumentation, um Hilfe bei der Erstellung eines Clients zu erhalten: Oracle Dokumentation
  • Für PHP:
    Bitte schauen Sie auf folgende Dokumentation, um Hilfe bei der Erstellung eines Clients zu erhalten: PHP Manual
Die Prozessbeschreibung der Netzbetreiberprüfung über den Webdienst können Sie den folgenden Dokumenten entnehmen:
Antworten auf häufig gestellte Fragen zur Funktionalität des Webdienstes finden Sie hier.

Allgemeine Hinweise und Antworten zum Marktstammdatenregister finden Sie hier.

Webdienst Version 24.1.128

Zur Unterstützung

... bei der Programmierung der Schnittstelle für das Marktstammdatenregister stellen wir Ihnen auf dieser Internetseite einige Informationen zur Verfügung.

Unter den folgenden Links können Sie auf die Dienstbeschreibung des Webdienstes als WSDL-Datei inkl. XSD-Schema zugreifen:

Test-Webdienst

Produktions-Webdienst

Erklärung:
  • WSDL – Web Services Description Language – ist eine plattform-, programmiersprachen- und protokollunabhängige Beschreibungssprache für Netzwerkdienste.
  • XSD – XML Schema – beschreibt in einer komplexen Schemasprache Datentypen, einzelne XML-Schema-Instanzen (Dokumente) und Gruppen solcher Instanzen, zum Beispiel eine WSDL-Datei.

Die Beschreibung der Testumgebung kann als Konzept des Webdienstes und Objektdefinition hier heruntergeladen werden: Weitere Informationen können Sie auch unserer automatisch generierten API Dokumentation V24.1.128 entnehmen. Zusätzlich können Sie die Datei WSDL Patchnotes V24.1.128 (Excel, Datei ist nicht barrierefrei) nutzen, die Ihnen eine Übersicht über die Änderungen an der WSDL geben soll.

FAQ

Test-Webdienst

Wie lautet die Adresse? Welche URL soll für die Testverbindung genutzt werden?

Das Testsystem erreichen Sie unter der URL https://test.marktstammdatenregister.de/MaStRApi

Weiterhin steht das Vorschausystem des Marktstammdatenregisters unter https://vorschau.marktstammdatenregister.de/MaStRApi zur Verfügung. Das Vorschausystem gibt insbesondere den Marktakteuren, die über einen Webdienst mit dem MaStR kommunizieren, die Möglichkeit anstehende Änderungen am Webdienst vorab zu implementieren und zu testen. Marktakteure, die das Vorschausystem und den Webdienst verwenden möchten, können sich über das Kontaktformular mit dem Betreff „Zugangsdaten Vorschausystem“ melden, um Zugangsdaten zu erhalten.

Wo erhalte ich die WSDL-Datei? Welche WSDL soll für die Verbindung genutzt werden und ab wann ist diese gültig?

Sie erhalten Sie WSDL-Datei für den Webdienst auf dieser Seite.

Wie lauten die Zugangsdaten? Welcher Benutzername kann für die Testverbindung genutzt werden?

Webdienst-Benutzer können im Test-Webdienst über das Test-Webportal eigenständig angelegt und verwaltet werden.

Zertifikat Welches TLS-Zertifikat kann für die Testverbindung genutzt werden?

Die Authentifizierung erfolgt über einen Webdienst-Key, welcher dem Webdienstbenutzer zugewiesen ist. Ein Zertifikat wird nicht benötigt. Der Transportkanal ist SSL verschlüsselt. Beachten Sie, dass wir nur TLS 1.2-Verbindungen akzeptieren!

Faults In der neuen aktuellen WSDL werden keine Fault- Nachrichten mehr definiert, in der alten Test- WSDL schon. In der Beschreibung zur neuen Prod WSDL werden hingegen Fehlernachrichten beschrieben. Wie kann das sein?

Die erste WSDL beinhaltete Default-Faults, da diese Datei automatisch generiert wurde. Die aktuelle (und zukünftige WSDLs) werden durch einen anderen Prozess generiert und enthalten keine Faults. Informationen zu den Faults können Sie dem Schnittstellendokument entnehmen. Sie finden dies auf unserer Informationsseite.

Allgemeine Fragen

Gelangt man beim Testen auf eine Web-Oberfläche, die man dann händisch weiterbedienen kann?

Nein, es handelt sich um eine reine Machine-to-Machine Serviceschnittstelle.

Kann man eine freie SOAP-Software nutzen? Lässt sich z.B. SoapUI (https://www.soapui.org) für den Webdienst nutzen, um damit die WSDL-Datei per URL einlesen und testen zu können?

Ja, die WSDL Datei kann mit jedem Soap-Tool konsumiert werden. Bei SoapUI ist mindestens die Version 5.3 zu empfehlen, da es ansonsten Probleme mit der SSL- bzw. TSL-Version geben könnte. Auch andere Alterniven, wie Postmann, sind möglich.

Mit dem Browser kann ich die WSDL-Datei laden, mit meinem Tool erhalte ich jedoch die Meldung, dass der Server nicht erreichbar ist. Was muss ich tun?

Bitte prüfen Sie die Einstellungen Ihres Proxyservers. Beachten Sie auch, dass Ihr Tool eine HTTPS-Verbindung auf Basis von TLS 1.2 aufbauen muss. Alle anderen Anfragen werden aus Sicherheitsgründen abgewiesen.

Ich erhalte die Fehlermeldung, dass Dateien fehlen. Wie erhalte ich den vollständigen Umfang aller Dateien?

Die Dienstbeschreibung besteht aus einer WSDL- und mehreren XSD-Schemadateien. Die letzteren werden in der Regel bei der Verarbeitung der WSDL-Datei nachgeladen. Erfolgt dies nicht oder nicht vollständig, können Sie die Dateien aus dem ZIP-Archiv oder manuell vom Server laden.

Bei der Verarbeitung der Dienstbeschreibung erhalte ich Meldungen, dass der Wert "maxOccurrence=1" gefordert wird oder "abstract" nicht unterstützt wird. Wie behebe ich diese Fehler?

Bitte nutzen Sie bei svcutil nicht die Option "Datacontractonly", da diese fehlerhaft arbeitet. Bei einem Aufruf von svcutil ohne diese Option erhalten Sie diese Fehlermeldungen nicht.

Wie erfolgt die Versionierung des Webdienstes?

Die Versionierung erfolgt über den Namespace. Vergleichen Sie hierzu im Konzept das Kapitel 4.2 "Versionierung der Webdienste".

Als Antwort einer Funktion erhalte ich einen Support-Code. Wie kann ich weiter verfahren?

Bitte wenden Sie sich in diesem Fall mit diesem Code an unseren Support für eine weitere Klärung.

Wer kann den Webdienst benutzen?

Insbesondere den Netzbetreibern werden Funktionen angeboten, um ihre Netzbetreiberprüfungen realisieren zu können.

Der Webdienst steht zusätzlich jedem (registrierten) Benutzer zur Verfügung, um öffentliche Daten abzurufen oder eigene Daten zu verwalten.

Welche Zugangsberechtigungen sind erforderlich, um den Webdienst zu nutzen?

Die Funkion GetLokaleUhrzeit ist die einzige Funktion, für die keine Authentifizierung erforderlich ist. Sie dient im Wesentlichen dazu, die Verbindung zwischen Client und Server zu testen. Für alle anderen Webdienst-Funktionen ist eine Authentifizierung des Benutzers erforderlich. Dies erfolgt durch die Übermittlung eines Webdienst-Key des Webdienst-Benutzers.

Welchen Beschränkungen unterliegt die Nutzung des Webdienstes?

Ein registrierter Webdienst-Benutzer kann pro Tag 50.000 Aufrufe an den Webdienst übermitteln. Ein solches Tageskontingent gilt für Benutzer von Netzbetreibern nicht.

Wann wird das Konzept der Katalogwerte in der Schnittstelle aktiv nutzbar sein?

Im Marktstammdatenregister befinden sich Kataloge. Diese Kataloge beschreiben Attribute von Objekten. Die Kataloge sind dabei statisch oder dynamisch.

Statische Kataloge sind Kataloge, die sich im laufenden Betrieb nicht ändern. Sie sind fest im System hinterlegt und werden lediglich bei neuen Release-Versionen aktualisiert. So ein Katalog ist z.B. die Spannungsebene oder das Bundesland.

Dynamische Kataloge sind Kataloge, die sich im laufenden Betrieb ändern können. Nur wenige Kataloge sind dynamisch, wie z.b. der Hersteller einer Windkraftanlage.

Im Webdienst sind alle statischen Kataloge als Enumerationen hinterlegt und in der WSDL fest integriert. Diese Kataloge besitzen keine ID. Die Angabe der ID erfolgt hier nur als Hinweis. In dem jeweiligen Objekt wird bei dem entsprechenden Attribut auch keine ID hinterlegt, sondern das entsprechende Item der Enumeraton.

Im folgenden Fall ist HOCHSPANNUNG ein Item der Enumeration "SpannungsebeneEnum":

<Netzanschlusspunkt>
<Spannungsebene>Hochspannung</Spannungsebene>
</Netzanschlusspunkt>


Bei den dynamischen Katalogen werden hingegen nur die IDs in den entsprechenden Attributen hinterlegt. Diese dynamischen Attribute können Sie über die Basisfunktionen im Webdienst abfragen und somit den Inhalt auslesen. Diese Kataloge müssen Sie in Ihrem System hinterlegen, um die Informationen an den Objekten auswerten zu können.

Im folgenden Beispiel ist 1234 die ID des Items "Hersteller ABC" aus dem Katalog "Hersteller".

Z.B.:

<Windeinheit>
<Hersteller>1234</Hersteller>
</Windeinheit>

Es kommt zu einem Fehler bei Proxygenerierung des Servicesinterfaces [SAP] Proxy-Generierung nicht möglich (Objekt <element name=GetAktuellerStandTageskontingent... fehlt in WSDL, siehe Langtext

Die WSDL-Datei beinhaltet nicht alle Servicebeschreibungen. Diese sind in extra Dateien ausgelagert.

Bei der Generierung der Proxies werden diese Dateien üblicherweise nachgeladen, sodass die Informationen zur Proxygenerierung vorhanden sind. Wenn keine Verbindung zum Internet besteht, fehlen die Basistypen und die Servicetypen, was Ihren Fehler erklärt.

Bei Ihnen scheint daher dieses Nachladen nicht zu funktionieren. Bitte prüfen Sie daher die Funktion zur Generierung des Proxies und ob Ihr Serversystem eine Verbindung zum Internet hat.

Oft hilf es, diese Generierung nicht online sondern offline auszuführen, da die restlichen Dateien so nicht aus dem Internet geladen werden, sondern von einem lokalen Verzeichnis.

Sie bekommen alle Offline-Dateien in dem entsprechenden ZIP-Archiv .

Technische Fragen

Was ist eine Objektversionierung?

Gemeint ist die Version eines Objektes, welche über den Parameter "LetzteAenderung" identifiziert wird. Eine Objektversion ist mit einer Version eines Objektes nur dann gleich, wenn der Parameter "LetzteAenderung" gleich ist.

Was ist eine Deltafunktion?

Mit der Deltafunktion lassen sich bei allen Listen nur die Objekte abrufen, die sich ab dem angegebenen Datum geändert haben oder neu entstanden sind.

Als Antwort erhalte ich "Invalid Header"?

Im Fall eines Fault wird nicht ein HTTP-Code 200 gesendet, sondern ein entsprechender Fehlercode. Das Verhalten muss in Ihrer Implementierung berücksichtigt werden.

Beispiele für Fault HTTP-Codes:

Soapenv:Receiver.ZugriffVerweigert403 Soapenv:Receiver.ZugriffVerweigertFalscherMarktakteur403 Soapenv:Receiver.ZugriffPruefungVerweigert403 Soapenv:Receiver.QuotaUeberschritten403 Soapenv:Receiver.ZugriffVerweigertNichtZustaendigerNetzbetreiber403 Soapenv:Receiver.NichtGefunden404 Soapenv:Receiver.EinheitNichtGefunden404 Soapenv:Receiver.MarktakteurNichtGefunden404 Soapenv:Receiver.MarktakteurUnbekannt404 Soapenv:Receiver.KatalogwertUnbekannt404 Soapenv:Receiver.KeineLokationAngegeben400 Soapenv:Receiver.EinheitTypFalsch400 Soapenv:Receiver.Wertefehler400 Soapenv:Receiver.EinheitDerPruefungFalsch400 Soapenv:Receiver.ProzessschrittNichtMoeglich400 Soapenv:Receiver.ProzessNichtAbschliessbar400 Soapenv:Receiver.ObjektVersionUngueltig400 Soapenv:Receiver.ProzessschrittKorrekturNichtMöglich400 Soapenv:Receiver.WerteGesperrt423 Soapenv:Receiver.FunktionGesperrt423 Soapenv:Receiver.AllgemeinerFehler500

Was bedeutet es, wenn die Verbindung zum Webdienst wegen einer ungültigen Cipher Suite abgelehnt wird?
Aus Sicherheitsgründen werden derzeit nur SSL Verbindungen mit folgenden Ciphern akzeptiert:
  • TLS_ECDHE_RSA_WITH_AES128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES256_CBC_SHA
Bei einigen Frameworks müssen diese u. U. zusätzlich installiert werden, z.B.bei Java durch das Java Cryptography Extension (JCE) Pack und der explizierten Angabe des Ciphers über crypto.policy=unlimited und https.cipherSuites=TLS_ECDHE_RSA_WITH_AES256_CBC_SHA384 usw.

Marktakteure

Worum handelt es sich bei dem Feld "Region"? Handelt es sich hierbei um die Region des Marktakteurs oder um eine Angabe zum Thema „Standort der Einheit“?

Es handelt sich um die Region des Marktakteurs auf der Ebene von NUTS-II.

Einheiten und Anlagen

Feld "AdressZusatz" im Webdienst-Dokument: Wozu dient dieses Feld?

Es handelt sich um ein Freitextfeld, um weitere Informationen zu einer Adresse zu erfassen.

Netzbetreiberprüfung

Wer kann die Funktionen zur Netzbetreiberprüfung nutzen?

Diese Funktionen stehen Netzbetreibern zur Verfügung, die zu einer Netzbetreiberprüfung aufgefordert wurden.

Was ist eine Aufforderung zur Datenkorrektur?

Stellt ein Netzbetreiber fest, dass die Daten eines der durch ihn zu prüfenden Objekte fehlerhaft sind, kann er den Dateninhaber (Anlagenbetreiber) mittels eines Korrekturvorschlags zur Korrektur seiner Daten auffordern.

Was sagt der Status einer Netzbetreiberprüfung aus?

Der Status der Netzbetreiberprüfung gibt an, in welchem Schritt sich der zugehörige Ticketprozess befindet.