Dokumentation für Anwender der SOAP Schnittstelle

Kurzbeschreibung

Mittels der SOAP Schnittstelle soll die Datenübertragung zwischen der stiftung elektro-altgeräte register (stiftung ear®) und ihren Kunden (resp. deren Dienstleistern) vereinfacht werden. Mengenmitteilungen nach ElektroG können durch eine entsprechende Implementierung beim Kunden auf elektronischem Wege abgegeben und Informationen zur Abholkoordination abgerufen werden. Für die fristgerechten Abrufe und Mengenmitteilungen über die SOAP Schnittstelle sind die Kunden selbst verantwortlich. Ferner beinhaltet die Schnittstelle Funktionen zur Abfrage der öffentlichen Verzeichnisse separiert nach ElektroG bzw. BattG.

Voraussetzungen

Für die Nutzung der Funktionen im Rahmen von Mengenmitteilungen sowie Informationen zur Abholkoordination müssen folgende Voraussetzungen erfüllt sein:

• Die Schnittstelle benötigt für die Services AbholkoordinationsService und MitteilungsService eine Identifizierung und Authentifizierung mittels Benutzername und Kennwort. Der AbholkoordinationsService kann nur durch den Hauptansprechpartner oder einen berechtigten Benutzer eines Herstellers / Bevollmächtigten genutzt werden. Ein berechtigter Benutzer kann jederzeit vom Hauptansprechpartner angelegt werden. Die erforderlichen Benutzerrechte werden in der Dokumentation jedes SOAP Aufrufes aufgeführt, wie z.B. "Daten zur Abholkoordination über SOAP abrufen".
• Dritte können – sofern die entsprechenden Berechtigungen vergeben wurden – ebenfalls die SOAP Schnittstelle nutzen und für einen Hersteller über den MitteilungsService melden.
• Für den Service EigenruecknahmesystemHerstellerlisteService wird eine Identifizierung und Authentifizierung mittels Benutzername und Kennwort benötigt. Der Aufruf ist für einen berechtigten Benutzer eines BattG-Eigenrücknahmesystems möglich.

Schnittstelle

Die SOAP Schnittstelle besteht aus sechs Services. Der AbholkoordinationsService beinhaltet Funktionen zum Abruf von Informationen zur Abholkoordination. Hersteller können sich hier u.a. generierte PDF-Dokumente herunterladen. Der MitteilungsService beinhaltet die Funktionalität, Mengenmitteilungen elektronisch abzusetzen. Der VerzeichnisService bietet die Möglichkeit ohne Authentifizierung Statusinformationen zu einem Abhol- und/oder Aufstellungscode der Abholkoordination abzurufen. Weiterhin sind Funktionen zum Abrufen für die Verzeichnisse nach dem ElektroG bzgl. der registrierten Hersteller und Bevollmächtigten, der Sammel- und Rücknahmestellen und der Betreiber von Erstbehandlungsanlagen vorhanden. Der BattGVerzeichnisService bietet die Möglichkeit ohne Authentifizierung Funktionen zum Abrufen für das Verzeichnis der registrierten Hersteller und Bevollmächtigten nach dem BattG zu nutzen. Der BattGRSVerzeichnisService bietet zuletzt die Möglichkeit ohne Authentifizierung Funktionen zum Abrufen für das Verzeichnis der genehmigten Eigenrücknahmesysteme zu nutzen. Der EigenruecknahmesystemHerstellerlisteService bietet berechtigten Benutzern eines BattG-Eigenrücknahmesystems die Möglichkeit, seine Herstellerliste anzuzeigen und zu bearbeiten (verfügbar ab Inkrafttreten BattG-E). Es können Einträge hinzugefügt, geändert und gelöscht werden. Darüber hinaus ist es möglich, die Teilnahme von Herstellern in der Liste zu bestätigen. Die technische Anbindung an die Schnittstelle erfolgt mittels SOAP 1.1 über HTTPS. Die WSDL-Dateien für das Produktivsystem sind erreichbar unter folgenden URLs:

• https://soap.ear-system.de/ear-soap/v2/AbholkoordinationsService?wsdl
• https://soap.ear-system.de/ear-soap/v2/MitteilungsService?wsdl
• https://soap.ear-system.de/ear-soap/v2/VerzeichnisService?wsdl
• https://soap.ear-system.de/ear-soap/v2/BattGVerzeichnisService?wsdl
• https://soap.ear-system.de/ear-soap/v2/BattGRSVerzeichnisService?wsdl
• https://soap.ear-system.de/ear-soap/v2/EigenruecknahmesystemHerstellerlisteService?wsdl

Im Folgenden sind die Services im Detail mit den darin enthaltenen Meldeschlüsseln und Mitteilungsfunktionen sowie deren Parameter aufgelistet. Die Services sind, mit Ausnahme jener für öffentlich verfügbare Informationen, mittels Basic Authentication vor unbefugtem Zugriff geschützt. Dabei wird die Benutzer-ID und das Benutzerkennwort, wie es auch für das ear-portal genutzt werden kann, für SOAP verwendet.

Berechtigungen für AbholkoordinationsService und MitteilungsService

Eigenen Benutzer des Herstellers im Portal anlegen

Der Hauptansprechpartner des Herstellers / Bevollmächtigten kann im Portal einen neuen Benutzer anlegen.

Hierzu muss zunächst über Auswahl des Menüpunktes „Benutzerverwaltung“ der Knopf „Neuer Benutzer“ betätigt werden.

Anschließend können die entsprechenden Berechtigungen für den neuen Benutzer festgelegt werden. Diese Berechtigungen können auch später noch angepasst werden. Die gewählten Berechtigungen entscheiden darüber, welche Funktionen der SOAP Schnittstelle von diesem Benutzer verwendet werden können.

Nach der Auswahl "Weiter" erscheint eine Zusammenfassungsseite. Der neue Benutzer wird anschließend mit der Auswahl „Neu anlegen“ im ear System angelegt. An die bei den Benutzerdaten hinterlegte E-Mail-Adresse wird nach der Neuanlage zunächst eine E-Mail mit einem Validierungscode versendet, um sicherzustellen, dass diese E-Mail-Adresse existiert. Im Anschluss daran folgt eine weitere E-Mail, mit der Benutzerkennung. Mit der ersten Anmeldung kann der Benutzer sein Kennwort selbst wählen.

Dritte für die Nutzung der SOAP Schnittstelle berechtigen

Hersteller können im ear Portal Dritte zuordnen. Zusätzlich können Dritte vom Hersteller berechtigt werden Mengenmeldungen abzugeben.

Die dazu notwendigen Berechtigungen kann der Hersteller für den Dritten im Portal konfigurieren. Die Einrichtung eines SOAP Benutzers für einen vom Hersteller selbst angelegten Dritten wird im obigen Abschnitt „Eigenen Benutzer des Herstellers im Portal anlegen“ beschrieben.

Die Verwaltung der Berechtigungen zur Abgabe von Mengenmeldungen über die SOAP Schnittstelle erfolgt bei eigenständig angemeldeten Entsorgern als Dritte (im Portal über die Funktion: „Zuordnung von angemeldeten Entsorgern mit Entsorger-ID“) über die Vergabe der Berechtigungen bei der Entsorgerzuordnung.

Werden die o. a. Berechtigungen für einen Entsorger vergeben, kann der Entsorger die Mitteilungen auch über die SOAP Schnittstelle durchführen.

Testzugang für die Entwicklung

Um die Schnittstelle seitens der Hersteller testen zu können, steht ein separates Testsystem zur Verfügung.

Die WSDL für das Testsystem kann unter folgenden URLs abgefragt werden:

• https://test.ear-system.de/ear-soap/v2/AbholkoordinationsService?wsdl
• https://test.ear-system.de/ear-soap/v2/MitteilungsService?wsdl
• https://test.ear-system.de/ear-soap/v2/VerzeichnisService?wsdl
• https://test.ear-system.de/ear-soap/v2/BattGVerzeichnisService?wsdl
• https://test.ear-system.de/ear-soap/v2/BattGRSVerzeichnisService?wsdl
• https://test.ear-system.de/ear-soap/v2/EigenruecknahmesystemHerstellerlisteService?wsdl

Die Benutzung der Schnittstelle auf dem Testsystem erfordert, vergleichbar dem Produktivsystem eine Authentifizierung. Die Anmeldung ist über einen Testaccount möglich, mit der Benutzer-ID test und dem Kennwort test. Unter diesem Benutzer findet grundsätzlich keine Änderung von Daten über diese Schnittstelle statt. Der Testbenutzer besitzt die "virtuelle" Registrierungsnummer 12345678. Diese muss bei diversen Aufrufen des MitteilungsServices mit übergeben werden. Für die Funktionen des AbholkoordinationsService getCodes und getDetails, sowie für die Funktion des VerzeichnisService getAhkstatus kann mit der codeId V001 (für Vollmeldung), A001 (für Abzug) und B001 (für Erstgestellung) eine feste Beispielantwort generiert werden, die immer, sowohl für die Abholung als auch für die Aufstellung, den Status 5 ("Abholung bestätigt nach Zuweisung" bzw. "Aufstellung bestätigt nach Zuweisung") zurückliefert.

Die Benutzung der Schnittstelle ist aber auch mit einem auf dem Testsystem angelegten Hersteller-Account möglich. Dann stehen alle Funktionen zur Verfügung, die auch einem Benutzer des produktiven Produktivsystems zur Verfügung stehen. Unter einem Benutzer-Account mit einem angelegten Hersteller findet eine Speicherung der Daten statt. Zu beachten ist, dass das Testsystem bzgl. der AHK keine valide Daten liefert.

Bei Fragen zu der Benutzung des Testzugangs wenden Sie sich bitte per E-Mail an:

system@stiftung-ear.de
+49 911 76665 0

Verwendung in eigener Implementierung

Wenn in einer eigenen Implementierung auf die SOAP Schnittstelle zugegriffen werden soll, können aus den zwei genannten Webservices automatisch die notwendigen Quellcodedateien für eine Verarbeitung erzeugt werden. Die technische Anbindung an die Schnittstelle erfolgt mittels SOAP 1.1 über HTTPS. In der Programmiersprache Java können beispielsweise mittels Apache Axis oder wsimport (JAX-WS) aus den WSDL-Dateien die notwendigen Klassen für die SOAP Aufrufe erzeugt werden. Aufgrund der Menge an möglichen Programmiersprachen für Implementierungen von Zugriffen auf die SOAP Schnittstelle werden von der stiftung ear keine Programmcodes bereitgestellt.

Bei der Implementierung eines Clients, ist darauf zu achten, dass für den AbholkoordinationsService die Codierung der SOAP-Nachrichten entsprechend für MTOM konfiguriert ist (z.B für .NET binding.MessageEncoding = WSMessageEncoding.Mtom. Auch ist darauf zu achten, dass die Puffergröße für den Nachrichtenempfang entsprechend groß gewählt wird (z.B für getCodes() unter .NET binding.MaxBufferSize = 1000000), sowie für den Abruf von Abhol-, Aufstellungs- und Gebührenbescheide die maximal erlaubte Größe einer Nachricht entsprechend gewählt wird (z.B für getDetails() oder getGebuehrenbescheid() unter .NET binding.MaxReceivedMessageSize = 1000000).

Programmbeispiel in Java

Bei der Generierung der Java-Klassen mit wsimport empfiehlt es sich, folgendes JAXB-Binding zu verwenden, um nillable-Elemente nicht als JAXBElement<T> abzubilden ("binding.xml"):

<jaxb:bindings version="2.1" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb">
    <jaxb:globalBindings generateElementProperty="false" />
</jaxb:bindings>

Generierung der Java-Klassen für die Benutzung des Services AbholkoordinationsService unter Verwendung des obigen Bindings:

wsimport -b binding.xml -Xnocompile -keep https://test.ear-system.de/ear-soap/v2/AbholkoordinationsService?wsdl

Beispiel für den Aufruf der Operation isAlive und getGebuehrenbescheid des Services AbholkoordinationsService:

AbholkoordinationsService service = new AbholkoordinationsService();
AbholkoordinationsServicePort servicePort = service.getAbholkoordinationsServicePort();

// Authentifizierung
Map requestContext = ((BindingProvider) servicePort).getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, "test"); // Test Benutzer-ID
requestContext.put(BindingProvider.PASSWORD_PROPERTY, "test"); // Test Kennwort

// isAlive()
System.out.print(servicePort.isAlive().getText());

// getGebuehrenbescheid
Gebuehrenbescheid gebuehrenbescheid = servicePort.getGebuehrenbescheid("V001");
Dokument dokument = gebuehrenbescheid.getDokument();
try (FileOutputStream fos = new FileOutputStream(dokument.getFilename())) {
    dokument.getFile().writeTo(fos);
}

Programmbeispiel in C#

Der folgende Codeausschnitt geht davon aus, dass innerhalb eines C#-Projektes in der Entwicklungsumgebung Microsoft Visual Studio der AbholkoordinationsService bereits als Dienstverweis eingerichtet wurde.

Beispiel für den Aufruf der Operation isAlive und getDetails des Services AbholkoordinationsService:

var binding = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
binding.MaxReceivedMessageSize = 1000000;
binding.MaxBufferPoolSize = 1000000;
binding.MessageEncoding = WSMessageEncoding.Mtom;

var endpoint = new EndpointAddress("https://test.ear-system.de/ear-soap/v2/AbholkoordinationsService");
using (var client = new AbholkoordinationsServicePortClient(binding, endpoint))
{
    client.ClientCredentials.UserName.UserName = "test";
    client.ClientCredentials.UserName.Password = "test";

    Console.WriteLine($"isAlive: {client.isAlive()}");

    AbholkoordinationsService.Detailinformation results = client.getDetails("V001");
    Console.WriteLine($"Details TPE: {results.transporteinheit.bezeichung}");
}