UnternehmensInfo Webservice 2.1
Die GET AG stellt einen Webservice für die Abfrage von Stammdaten der Unternehmen bereit. Bei den Unternehmensdaten handelt es sich hauptsächlich um Information zu den Marktpartnern der Energiewirtschaft im Bereich Strom und Gas. Die Unternehmensstammdaten sollen unseren Kunden die manuelle und automatische Stammdatenpflege in Abrechnungssystemen wie SAP, DATEV, Wilken ENER:GY, Schleupen CS.MP oder SIV kVASy ermöglichen. Neben den Stammdaten gibt es eine Reihe weiterer Daten, welche für die Prozesse Lieferantenwechsel, Netzanmeldungen oder Netzabmeldungen benötigt werden. Dazu zählen die Kontaktdatenblätter, EDIFACT-Adressen, Ansprechpartner, Bankdaten wie IBAN und BIC sowie Informationen zu Zertifikaten je Marktrolle.
Ebenso bietet die API die Ausgabe von Detailinformation eines Unternehmens wie die Firmierung, die Rechtsform, die Handelsregisternummer oder die Anschrift. Ihnen ist die Abfrage von prozessrelevanten Daten zur Unterstützung der Marktkommunikation für UTILMD, INVOIC, PARTIN, PRICAT anhand der Verknüpfung zu den BDEW Codes und DVGW Codes der einzelnen Marktrollen der Marktpartner möglich.
Stammdaten Unternehmen SwaggerUI und API Cliententwicklung
Anleitung Nutzung SwaggerUI am Beispiel getVersion
Für einen einfachen Einstieg in unsere Welt der API steht Ihnen die Swagger UI unseres Testsystems zur Verfügung:
SwaggerUI für Stammdaten Unternehmen Webservice
Bitte beachten Sie, dass es sich hierbei um die Testservices handelt, welche nur Testdaten (Region Sachsen) enthalten und nicht permanent erreichbar sein müssen. Die GET AG aktualisiert das Testsystem zudem planmäßig jeden Donnerstag von 10-11 Uhr.
Ihre Zugangsdaten haben Sie über unseren Support erhalten oder, falls noch nicht, können Sie sich im Kontaktformular der GET AG Webservices eigene anfordern.
Die Zugangsdaten tragen Sie bitte nach Klick auf „Authorize“ der Swagger UI unter „Username:“ und „Password:“ ein und bestätigen mittels „Authorize“.
Client-Entwicklung
In der Technischen Dokumentation finden Sie weitere Hinweise zu Zertifikaten, Authentifizierung, Freischaltung oder Angaben zum Anfrageverhalten.
Bei der Implementierung können Sie den SOAP-Endpunkt und die clientseitige Komprimierung verwenden. Für die Client-Entwicklung nutzen Sie entweder die YAML Datei aus der Swagger UI oder die hier aufgeführten URL und Endpunkte der API.
Hinweis: Beim SOAP-Protokoll verwenden Sie bitte die WSDL und für das REST-Protokoll ist die YAML-Spezifikation entscheidend.
Tipps für Softwareentwickler zur Clientgenerierung aus der OpenAPI Beschreibung oder YAML Datei gibt es hier.
API Stammdaten Unternehmen - URL und Endpunkte
Es sind folgende WSDL / WADL für die Anbindung des Webservice verfügbar:
http://webservicetest1.ag-server.de/getagWSCore/jaxws/UnternehmensInfoService21x0?wsdl
Produktiv-Webservice (SSL):
https://webservice1.ag-server.de/getagWSCore/jaxrs/UnternehmensInfoService21x0/application.wadl
Methodenübersicht Stammdaten Unternehmen
getVersion
getVersion liefert Ihnen, ohne die Übergabe von spezifischer Request-Daten, die Versionsinformationen bzw. den Softwarestand des Service zurück und sie ist nützlich, um die grundsätzliche Service-Erreichbarkeit des anfragenden Systems zu testen.
getVersorgerInfo
Diese Methode kann von Ihnen als Einstieg für den Webservice verwendet werden, um die Marktpartner-ID der Marktrollen zu den übergebenen Parametern zu bestimmen. Das ist unter anderem die Unternehmensbezeichnung, die BDEW / DVGEW Codenummer / GLN (global location number) sowie die Marktrollen, wie zum Beispiel Lieferant, Netzbetreiber oder Messstellenbetreiber.
getVersorgerDetailInfo
Hierbei handelt es sich um eine Abfragemöglichkeit, welche Ihnen die Stammdaten zu dem ausgewählten Unternehmen liefert. Mit Ihrer Übergabe einer versorgerspezifischen internen ID und dem gewünschten Medium Strom oder Erdgas, bietet Ihnen die Antwort unter anderem die Detailinformation zur Firmierung (z.B. Stromnetz Berlin GmbH), Firmenadresse, Handelsregisternummer oder Steuernummer. Der Service gibt auch verschiedene URL-Typen wieder, deren Aufruf auf die unterschiedlichen Datenblätter der Unternehmen führt (z.B. Kontaktdatenblatt Westnetz). Weitere URL-Typen geben die Quellen und Links zum Impressum oder den Ansprechpartner der Unternehmen an.
getEdifactDaten
getEdifactDaten dient der Bereitstellung von EDIFACT-Adressen der Marktpartner, welche in der Marktkommunikation Verwendung finden (z.B. UTILMD, INVOIC, PARTIN, PRICAT). Die erfolgreiche Serviceantwort liefert unter anderem die Marktrolle, die E-Mail-Adresse zur Marktkommunikation und Information zur Verschlüsselung, Signatur und Komprimierung. Zusätzlich können Sie die Abfrage anhand der gezielten Marktrolle, wie zum Beispiel Lieferant, Netzbetreiber oder Messstellenbetreiber, präzisieren.
getAnsprechpartner
Mit Hilfe dieser Methode erhalten Sie die richtigen Ansprechpartner des gewünschten Unternehmens. Mit der Webservice-Anfrage ist es Ihnen möglich, gezielt nach den in der Get AG Datenbank gespeicherten Kontaktdaten einer Person oder Abteilung der Firma zu suchen. Der Service liefert Information mit Angabe der Marktrolle, dem Typ (z.B. Netznutzung, Bilanzkreismanagement, Netzanmeldung oder Netzabmeldung) und den Kontaktdetails, wie Telefonnummer oder E-Mail-Adresse. Die Online-Bereitstellung der Stammdaten von Ansprechpartnern in der Energiewirtschaft vereinfacht die Stammdatenpflege in Ihrem genutzten System.
getParameter
Bei der getParameter handelt es sich um eine wichtige informatorische Methode, welche die Namensauflösung der Parameter-IDs ausgibt. Sie ist vor allem bei der Anbindung hilfreich, um die Parameter-IDs in den jeweiligen Methoden zuordnen zu können. Beispielsweise können Sie darüber die im System verwendeten Markrollen-IDs oder Ansprechpartnertypen nachschlagen.
getWiederverkaeuferbescheinigung
getWiederverkaeuferbescheinigung ermöglicht die Abfrage von Wiederverkäufernachweisen / Wiederverkäuferbescheinigungen und im Ergebnis wird, neben der Marktrolle und dem Gültigkeitsdatum, eine URL ausgegeben, über die Sie sich das Dokument ansehen können. Damit erhalten Sie einen Nachweis für die korrekte Umsetzung des umsatzsteuerlichen Reverse-Charge-Verfahren (Umkehr der Steuerschuldnerschaft bzw. RC-Verfahren).
getBankdaten
Die Ausgabe von Bankdaten bzw. Kontodaten ist Ihnen mit der Methode getBankdaten möglich. Marktrollenspezifisch können Sie pro Marktpartner den SWIFT-Code (BIC), die Bankverbindung (IBAN) und die Gläubiger-Identifikationsnummer abfragen. Zusätzlich wird die Information zur Quelle, z.B. vom Kontaktdatenblatt, der Kontodaten geliefert. Diese Daten eignen sich nicht nur für die Aktualisierung der Stammdaten, sondern auch für automatische Zahlungsprozesse. Für eine Online-Validierung von Bankdaten in Abschlussstrecken oder Tarifrechnen nutzen Sie bitte unseren separaten Bankdatenprüfservice.
getServiceDaten
Mit dem Abruf der Service-Daten erhalten Sie die von Strom- bzw. Gaslieferanten veröffentlichen Zeiten der Erreichbarkeit. Neben den Wochentagen und den Uhrzeiten, in dem der Service des Unternehmen erreichbar ist, wird durch die Methode auch die hinterlegte Telefonnummer bzw. Faxnummer wiedergegeben.
getBilanzierungsgebietEIC
Durch Übergabe der versorgerspezifischen internen ID oder der BDEW Codenummer, zusätzlich zur Wahl des Mediums Strom oder Gas, ermöglicht Ihnen diese Methode die Ausgabe des EIC (Energy Identification Code) des Bilanzierungsgebiets des Unternehmens. Neben dem Gültigkeitszeitraum wird auch der EIC der zuständigen Regelzone angezeigt.
Bitte beachten Sie, dass die Zuordnung von Bilanzierungsgebiet EIC zum Regelzone EIC der Angabe des BDEW entspricht.
getSchaltzeiten
Die veröffentlichten Schaltzeiten eines Netzbetreibers, auch HT/NT, Schwachlastzeiten oder Sperrzeit genannt, können Sie sich anhand dieser Methode ausgegeben lassen. Nach Angabe des Unternehmens und Wahl von Filterparametern (z.B. SLP/RLM, allgemeiner Entgelttyp, steuerbare Verbrauchseinrichtung, etc.) liefert Ihnen diese Methode, neben der Gültigkeit im Jahr, Angaben zum Wochentagestyp, zur Uhrzeit bzw. zum Zeitzonentyp (HT/NT) und ob die Schaltzeitangabe durch die Umstellung der Sommerzeit beeinflusst wird.
Weiterführende Information
Dynamische Angaben
Das Objekt „dynamischeAngaben“ ist in der aktuellen Version des Unternehmen Webservice ohne Funktion und muss von Ihnen somit nicht übergeben werden.
Zweck dieses Objektes ist es, dass die GET AG auf mögliche zukünftige Anforderungen hinsichtlich der Übergabe im Request und der Steuerung bzw. Filterung der Ausgabe im Response reagieren kann, ohne eine Strukturanpassung am Webservice durchführen zu müssen.
Optionale Parameter/Objekte
Optionale Parameter wurden von uns mit der Bemerkung „(optional)“ und optionale Objekte mit „(0:n Beziehung)“ gekennzeichnet. Dabei richtet sich die Kennzeichnung bei den Request-Parametern nach der fachlichen Anforderung. Die Kennzeichnung der Response-Parameter und -objekte als optional richtet sich allein nach der technischen Spezifikation.
ID-Spezifikation der Parameter
Die aktuellen IDs für die jeweiligen Parameter können Sie in der Methode getParameter einsehen.
Information zu Bankdaten
Bei der Ausgabe der Bankverbindungen in der Methode getBankdaten müssen Sie folgendes beachten.
Die Bankverbindungen werden durch unser Team in der Datenbank mit einem der folgenden Typen erfasst:
– INVOIC
– Kontaktdatenblatt
– Sonstige
Die Bankverbindungstyp-ID wird durch den Webservice ausgegeben und die Definition können Sie in der Methode getParameter einsehen.
Übergabe einer versorgerID:
Wenn Sie die Bankdaten zu einem konkreten Versorger (Übergabe versorgerID und ggf. marktrolle) anfragen, gibt der Webservice alle Bankverbindungen aus, die in der Datenbank erfasst wurden. Dies ist ein wesentlicher Unterschied zur Webservice-Vorgängerversion und die Ausgabe folgt damit auch keiner Rankinglogik mehr.
Fehlermeldungen / Fehlersuche zum Service Stammdaten Unternehmen
Sollte bei Ihrer Anfrage ein Fehler auftreten, dann wird ebenfalls das Ergebnisobjekt zurückgegeben. Dieses beinhaltet in der ersten Ebene einen Antwortstatus. Die einzelnen Codes werden mit der entsprechenden Fehlerbegründung. nachstehend aufgelistet.
Mit Ergebnis
1 antwortStatus – Ok, Abfrage erfolgt.
Ohne Ergebnis
2 antwortStatus – (Bitte wenden Sie sich unter Angabe der vollständigen Input-Parameter an den Support der GET AG.)
400 antwortStatus – Diese Funktion wird zur Zeit nicht unterstützt.
500 antwortStatus – Der Nutzer konnte nicht authentifiziert werden. (Bitte überprüfen Sie die eingegebenen Authentifizierungsdaten und wenden sich ggf. unter Angabe Ihres Benutzernamens an den Support der GET AG.)
700 ff. antwortStatus – Bitte wenden Sie sich unter Angabe der vollständigen Input-Parameter an den Support der GET AG (Prüfen Sie bitte zuerst Ihre Eingabe. Der zurückgegebene Fehlertext gibt einen Hinweis darauf, an welcher Stelle der Fehler aufgetreten ist.
701 antwortStatus – Interner Datenfehler.
800 antwortStatus – Es konnten keine Daten zu den übergebenen Parameter gefunden werden.
801 antwortStatus – Die Kombination der übergebenen Parameter ist ungültig.
802 antwortStatus – Es wurde ein ungültiger Wert in dem Parameter MarktrolleID übergeben.
803 antwortStatus – Es wurde kein Medium übergeben.
804 antwortStatus – Es wurde kein gueltigVon übergeben.
805 antwortStatus – Das Datumsformat des Parameters gueltigVon ist ungültig. Format YYYY-MM-DD.
806 antwortStatus – Das Datumsformat des Parameters gueltigBis ist ungültig. Format YYYY-MM-DD.
Bitte senden Sie zu jeder Anfrage an den Support der GET AG auch folgende Angaben mit:
• Webservice-Bezeichnung und –Versionsnummer
• antwortStatus
• iTag