Post on 04-Aug-2019
stiftung elektro-altgeräte register
SOAP Schnittstelle
Dokumentation für
Anwender der SOAP
Schnittstelle
Version 1.10
Dieses Werk einschließlich seiner Teile ist urheberrechtlich geschützt.
Jede Verwertung außerhalb der engen Grenzen des Urheberrechtsgesetz-
tes ist ohne Zustimmung der stiftung elektro-altgeräte register unzulässig.
Das gilt insbesondere für Vervielfältigungen, Übersetzungen sowie die Ein-
speicherung und Verarbeitung in elektronischen Systemen.
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
2/25
I. Inhalt
I. Inhalt ............................................................................................................................................................................. 2
II. Änderungshistorie ................................................................................................................................................... 4
III. Abbildungen .............................................................................................................................................................. 5
IV. Tabellen ....................................................................................................................................................................... 6
1 Einführung .................................................................................................................................................................. 8
1.1 Kurzbeschreibung ........................................................................................................................................ 8
1.2 Voraussetzungen .......................................................................................................................................... 8
1.3 Benutzer für die Nutzung der SOAP Schnittstelle berechtigen ................................................. 9
1.3.1 Eigenen Benutzer des Herstellers im Portal anlegen ................................................................ 9
1.3.2 Entsorger für die Nutzung der SOAP Schnittstelle berechtigen ........................................ 10
1.4 Testzugang für die Entwicklung .......................................................................................................... 11
2 Technik ...................................................................................................................................................................... 12
2.1 Aufbau ........................................................................................................................................................... 12
2.2 SOAP-Services ............................................................................................................................................ 12
2.2.1 EarSoapManufacturerService ........................................................................................................... 12
2.2.2 EarSoapPickupService ......................................................................................................................... 16
2.3 Rückantwort der SOAP Funktionen .................................................................................................... 18
2.3.1 StandardResponse ............................................................................................................................... 19
2.3.2 Adresse ..................................................................................................................................................... 19
2.3.3 Anschrift ................................................................................................................................................... 19
2.3.4 Ansprechpartner ................................................................................................................................... 19
2.3.5 Code .......................................................................................................................................................... 19
2.3.6 getCodesResponse .............................................................................................................................. 19
2.3.7 Codes ........................................................................................................................................................ 20
2.3.8 Detailinformation ................................................................................................................................. 20
2.3.9 Dokument ................................................................................................................................................ 20
2.3.10 Entsorger ............................................................................................................................................ 20
2.3.11 Gebühr ................................................................................................................................................. 20
2.3.12 Gebührenbetrag .............................................................................................................................. 21
2.3.13 ListDeviceTypes ................................................................................................................................ 21
2.3.14 DeviceTypes ....................................................................................................................................... 21
2.3.15 Gebührentatbestand ...................................................................................................................... 21
2.3.16 Sammelgruppe ................................................................................................................................. 21
2.3.17 Kategorie ............................................................................................................................................ 21
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
3/25
2.3.18 Transporteinheit............................................................................................................................... 22
2.3.19 Transporteinheitsaufbau .............................................................................................................. 22
2.3.20 Behältnis .............................................................................................................................................. 22
2.3.21 Hersteller ............................................................................................................................................ 22
2.3.22 Konto .................................................................................................................................................... 22
2.3.23 Kostenbetrag ..................................................................................................................................... 22
2.3.24 Gebührenbescheid .......................................................................................................................... 22
2.3.25 Telefon/Telefax ................................................................................................................................. 23
2.3.26 Abholfrist ............................................................................................................................................ 23
2.3.27 Übergabestelle ................................................................................................................................. 23
2.4 Aufrufe in eigener Implementierung verwenden ......................................................................... 23
3 Schlüsseltabellen................................................................................................................................................... 24
3.1 Generelle Schlüssel ................................................................................................................................... 24
3.1.1 Art bei Buchungsschlüssel ................................................................................................................ 24
3.1.2 Maßeinheiten ......................................................................................................................................... 24
3.2 Status .............................................................................................................................................................. 24
3.2.1 Abholung ................................................................................................................................................. 24
3.2.2 Aufstellung .............................................................................................................................................. 24
3.2.3 Abholung und Aufstellung ............................................................................................................... 25
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
4/25
II. Änderungshistorie
Version Datum Durch Beschreibung der Änderung
1.0 26.08.2015 Jan Schillings Initiale Version
1.1 12.10.2015 Thomas Winter Wegfall der transactionId
1.2 16.10.2015 Thomas Winter Ergänzung der URLs für das Produktivsystem
1.3 27.10.2015 Thomas Winter Registrierungsnummer als Rückgabewert für get-
Codes
Element Entsorger mit Attribut name
1.4 18.11.2015 Thomas Winter Abholcode als Rückgabewert von getDetails um-
benannt nach codeId.
ID der Geräteart als Rückgabewert von getCodes
hinzu, als geraeteartId.
Lesen von getCodes setzt changed nicht mehr zu-
rück, stattdessen bei lesen von getDetails.
1.5 24.11.2015 Thomas Winter Gebührenbescheid enthält jetzt statt des Akten-
zeichens (aktenzeichen), die VorgangsId (vor-
gangsId)
1.6 28.12.2015 Thomas Winter Präzisierung des Parameters „art“ bei getCodes.
1.7 28.01.2016 Thomas Winter Harmonisierung der Status für Abholung, Aufstel-
lung sowie neue Status für Abholung und Auf-
stellung (fachlich: Vollmeldung).
1.8 10.02.2016 Thomas Winter Parameter wg_date des Funktionsaufrufs curren-
tOutputCollectCode4Manufacturer() ist kein
Pflichtfeld.
1.9 13.04.2016 Thomas Winter Nutzung der SOAP-Schnittstelle auch für berech-
tigte Entsorger.
1.10 15.03.2017 Thomas Winter Fehlerkorrektur: Funktionsaufruf GetCodes Da-
tumsformat war falsch angegeben.
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
5/25
III. Abbildungen
Abbildung 1: Anlegen eines neuen Benutzers ...................................................................................................... 9
Abbildung 2: Hinzufügen eines neuen Benutzers ................................................................................................ 9
Abbildung 3: Zusammenfassungsseite ................................................................................................................. 10
Abbildung 4: Berechtigung für bereits angelegte Entsorger vergeben ................................................... 11
Abbildung 5: SOAP im ear-System ......................................................................................................................... 12
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
6/25
IV. Tabellen
Tabelle 1: Parameter 'checkRegistrationNumber' ............................................................................................. 13
Tabelle 2: Parameter 'currentlnputLastMonth' ................................................................................................... 13
Tabelle 3: Parameter 'currentOutputCollectCode4Manufacturer' .............................................................. 14
Tabelle 4: Parameter ' currentOutputSelfWithdrawelByWeightNote' ....................................................... 15
Tabelle 5: Parameter 'currentIndirectExport'....................................................................................................... 15
Tabelle 6: Parameter 'getCodes' .............................................................................................................................. 17
Tabelle 7: Parameter 'getDetails' ............................................................................................................................. 17
Tabelle 8: Parameter der differenzierten 'getDetails' Funktionen .............................................................. 18
Tabelle 9: Parameter 'getKostenbescheid' ........................................................................................................... 18
Tabelle 10: Parameter 'setStatusHst' ...................................................................................................................... 18
Tabelle 11: 'StandardResponse' - Elemente ........................................................................................................ 19
Tabelle 12: 'Adresse' - Elemente .............................................................................................................................. 19
Tabelle 13: 'Anschrift' – Elemente............................................................................................................................ 19
Tabelle 14: 'Ansprechpartner' - Elemente ............................................................................................................ 19
Tabelle 15: 'Code' - Elemente ................................................................................................................................... 19
Tabelle 16: 'getCodesResponse' – Elemente ....................................................................................................... 20
Tabelle 17: 'Codes' - Elemente ................................................................................................................................. 20
Tabelle 18: 'Detailinformation' - Elemente .......................................................................................................... 20
Tabelle 19: 'Dokument' - Elemente ......................................................................................................................... 20
Tabelle 20: 'Entsorger' - Elemente .......................................................................................................................... 20
Tabelle 21: 'Gebühr' - Elemente ............................................................................................................................... 21
Tabelle 22: 'Gebührenbetrag' – Elemente ............................................................................................................ 21
Tabelle 23: 'ListOfDeviceTypes' - Elemente ......................................................................................................... 21
Tabelle 24: 'DeviceTypes' - Elemente ..................................................................................................................... 21
Tabelle 25: 'Gebührentatbestand' - Elemente .................................................................................................... 21
Tabelle 26: 'Sammelgruppe' - Elemente ............................................................................................................... 21
Tabelle 27: 'Sammelgruppe' - Elemente ............................................................................................................... 21
Tabelle 28: 'Transporteinheit' - Elemente............................................................................................................. 22
Tabelle 29: 'Transporteinheitsaufbau' - Elemente ............................................................................................ 22
Tabelle 30: 'Behältnis' – Elemente ........................................................................................................................... 22
Tabelle 31: 'Hersteller' - Elemente........................................................................................................................... 22
Tabelle 32: 'Konto' - Elemente .................................................................................................................................. 22
Tabelle 33: 'Kostenbetrag' - Elemente ................................................................................................................... 22
Tabelle 34: 'Gebührenbescheid' - Elemente ........................................................................................................ 23
Tabelle 35: 'Telefon/Telefax' - Elemente ............................................................................................................... 23
Tabelle 36: 'Abholfrist' - Elemente .......................................................................................................................... 23
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
7/25
Tabelle 37: 'Übergabestelle' - Elemente ............................................................................................................... 23
Tabelle 38: Buchungsschlüssel .................................................................................................................................. 24
Tabelle 39: Maßeinheiten ........................................................................................................................................... 24
Tabelle 40: Status - 'Abholung' ................................................................................................................................ 24
Tabelle 41: Status - 'Aufstellung' ............................................................................................................................. 25
Tabelle 42: Status - 'Abholung und Aufstellung' ............................................................................................... 25
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
8/25
1 Einführung
1.1 Kurzbeschreibung
Mittels SOAP1 Schnittstelle wird die Datenübertragung zwischen der stiftung elektro-altgeräte re-
gister (stiftung ear®) und ihren Kunden (resp. deren Dienstleistern) vereinfacht werden.
Mengenmitteilungen können durch eine entsprechende Implementierung beim Kunden auf elekt-
ronischem Wege abgegeben und Informationen zu Abholungen abgerufen werden. Für die frist-
gerechten Abrufe und Mengenmitteilungen über die SOAP Schnittstelle sind die Kunden selbst
verantwortlich.
Die zur Verfügung gestellten Funktionen erlauben Mengenmitteilung bzw. bilden Prozesse ab, die
für die Abholkoordination (AHK) relevant sind.
1.2 Voraussetzungen
Um die hier beschriebene SOAP Schnittstelle nutzen zu können, müssen folgende Voraussetzun-
gen erfüllt sein:
▪ Nutzung des von der stiftung ear bereitgestellten SOAP-Services.
▪ Die Schnittstelle benötigt eine Identifizierung und Authentifizierung mittels Benutzer-
name und Kennwort. Ein berechtigter Benutzer kann jederzeit vom Hauptansprechpartner
des Herstellers angelegt werden. Er benötigt lediglich die Berechtigung zur Mengenmel-
dung.
▪ Zugeordnete Entsorger können – sofern die entsprechenden Berechtigungen vergeben
wurden – ebenfalls die SOAP Schnittstelle nutzen und für den Hersteller melden.
Für die Nutzung der Schnittstelle ist es nicht erforderlich einen VPN2 Zugang zu beantragen.
Die SOAP Schnittstelle ist über das https-Protokoll und den Standard-URL der ear Anwendung
nutzbar.
Beachten Sie, dass die in Firmennetzwerken regelmäßig vorhandenen Sicherheitseinrichtungen
(Proxy, Firewall u. dgl. m.) i. d. R. die Nutzung der SOAP Schnittstelle beeinträchtigen.
1 SOAP: Simple Object Access Protocol, siehe auch:
https://de.wikipedia.org/wiki/SOAP 2 VPN: Virtuelles Privates Netzwerk, siehe auch:
https://de.wikipedia.org/wiki/Virtual_Private_Network
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
9/25
1.3 Benutzer für die Nutzung der SOAP Schnittstelle berechtigen
1.3.1 Eigenen Benutzer des Herstellers im Portal anlegen
Der Hauptansprechpartner des Herstellers kann im Portal einen neuen Benutzer anlegen:
Abbildung 1: Anlegen eines neuen Benutzers
Auswahl der Benutzerverwaltung im Menüpunkt „Benutzerverwaltung“, dann den Knopf „Neuer
Benutzer“ auswählen:
Abbildung 2: Hinzufügen eines neuen Benutzers
Es genügt hier die Berechtigung „Mengenmitteilungen abgeben und Korrekturen durchführen“
zu selektieren.
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
10/25
Abbildung 3: Zusammenfassungsseite
Mit der Auswahl „Neu anlegen“, wird der neue Benutzer im ear 3.0 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.
1.3.2 Entsorger für die Nutzung der SOAP Schnittstelle berechtigen
Hersteller können im ear Portal Entsorger zuordnen, zusätzlich können Entsorger vom Hersteller
berechtigt werden Mengenmeldungen abzugeben.
Die dazu notwendigen Berechtigungen kann der Hersteller für den Entsorger im Portal konfigu-
rieren. Die Einrichtung eines SOAP Benutzers für einen vom Hersteller selbst angelegten Entsor-
gers wird im Abschnitt „1.3.1 Eigenen Benutzer des Herstellers im Portal anlegen“ beschrieben.
Die Verwaltung der Berechtigungen zur Abgabe von Mengenmeldungen über die SOAP Schnitt-
stelle erfolgt bei angemeldeten Entsorgern (Im Portal über die Funktion: „Zuordnung von ange-
meldeten Entsorgern mit Entsorger-ID“) über die Vergabe der Berechtigungen bei der Entsorger-
zuordnung:
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Einführung
11/25
Abbildung 4: Berechtigung für bereits angelegte Entsorger vergeben
Werden die o. a. Berechtigungen für einen Entsorger vergeben, kann der Entsorger die Mitteilun-
gen auch über die SOAP Schnittstelle durchführen.
1.4 Testzugang für die Entwicklung
Um die Schnittstelle seitens der Hersteller testen zu können, steht ein separates Testsystem zur
Verfügung.
Das Testsystem liefert bzgl. der AHK keine valide Daten.
Die Einrichtung eines Zugangs erfolgt durch die stiftung ear, bitte wenden Sie sich per E-Mail an:
Herr Markus Weiß
system@stiftung-ear.de
+49 911 76665 0
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
12/25
2 Technik
2.1 Aufbau
Abbildung 5: SOAP im ear-System
2.2 SOAP-Services
Die SOAP Schnittstelle besteht aus zwei Services. Diese sind für das Produktivsystem erreichbar
unter folgenden URLs:
▪ https://soap.ear-system.de/ear-soap/EarManufacturerService?wsdl
▪ https://soap.ear-system.de/ear-soap/EarPickupService?wsdl
Das Testsystem kann unter folgenden URLs angesprochen werden:
▪ https://soaptest.ear-system.de/ear-soap/EarManufacturerService?wsdl
▪ https://soaptest.ear-system.de/ear-soap/EarPickupService?wsdl
Im Folgenden sind die Services im Detail mit den darin enthaltenen Meldeschlüsseln und Mittei-
lungsfunktionen sowie deren Parameter aufgelistet. Die Parameter sind alphabetisch sortiert. Die
Reihenfolge der Parameter kann ebenfalls den wsdl-Dateien entnommen werden.
Beide Services sind mit einem Login vor unbefugten Zugriff geschützt. Dies wird beim Zugriff auf
die Services abgefragt.
Parameter Beschreibung Datentyp Länge Format
benutzerld Benutzer-ID Integer 8
Passwort Benutzerpasswort String 50
Die detaillierte Aufschlüsselung der SOAP Antworten findet sich unter Ziffer 2.3.
2.2.1 EarSoapManufacturerService
Dieser Service beinhaltet die Funktionalität, über die folgenden Methoden Mengenmitteilungen
elektronisch abzusetzen.
2.2.1.1 checkRegistrationNumber
Prüfen der eigenen Registrierungsdaten auf Richtigkeit:
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
13/25
Funktionsaufruf:
checkRegistrationNumber
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
registrationNumber Registrierungsnummer Integer 8
Tabelle 1: Parameter 'checkRegistrationNumber'
Antwort:
StandardResponse
2.2.1.2 currentInputLastMonth()
Es werden die tatsächlich in Verkehr gebrachten Mengen je Geräteart in Bezug auf den Vormonat
mitgeteilt, um die geplanten Mengen (Registrierungsgrundmenge) zu aktualisieren. Die Ist-Input-
mitteilung ist spätestens bis zum 15. des Folgemonats, bzw. den darauffolgenden Werktag im
Falle eines samstags, sonntags oder feiertags einzureichen. Diese Mengen korrigieren monatlich
die Registrierungsgrundmenge.
Funktionsaufruf:
currentlnputLastMonth
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
amountWeight Gewicht Float
bookingYear Jahr der Meldung Integer 4 YYYY
bookingMonth Monat der Meldung Integer 2 MM
category Kategorie Integer 8
deviceType Geräteart Integer 3
registrationNumber Registrierungsnummer Integer 8
uomWeight Gewichtseinheit Integer 3
mengeGasentladungs-
lampen
Gewicht der Gasentla-
dungslampen
Float
mengeSonstigeLampen Gewicht der sonstigen
Lampen
Float
Tabelle 2: Parameter 'currentlnputLastMonth'
Die Parameter „mengeGasentladungslampen“ und „mengeSonstigeLampen“ sind nur bei einigen
Kombinationen von Geräteart und Sammelgruppe Pflichtfelder. Dies hängt von der aktuellen Um-
setzung ab.
Antwort:
StandardResponse
2.2.1.3 currentInputExportToPrivate()
Es werden die tatsächlich in den europäischen Mitgliedsstaaten an Privathaushalte oder vergleich-
bare Anfallstellen (b2c-Produkte) in Verkehr gebrachten Gerätearten des angegebenen Monats
gemeldet. Die EU-Exportmeldung ist spätestens bis zum 15. des Folgemonats, bzw. den darauf-
folgenden Werktag im Falle eines samstags, sonntags oder feiertags einzureichen.
Funktionsaufruf:
currentlnputExportToPrivate
Diese Funktion wird nicht mehr unterstützt!
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
14/25
2.2.1.4 currentOutputCollectCode4Manufacturer()
Dieser Funktionsaufruf dient der Erfassung von Ist-Outputmitteilungen. Er steht für die vom Ent-
sorger gewogene Nettomenge an Elektroaltgeräten der dem Kunden zugewiesenen und abge-
holten Transporteinheit. Diese Mitteilung korrigiert die Entlastung des Herstellers, die durch die
Vorab-Gutschrift mit dem durchschnittlichen Soll-Outputgewicht der abgeholten Transportein-
heit entstanden ist. Sie fließt in die Verpflichtungsrechnung für die AHK ein.
Funktionsaufruf:
currentOutputCollectCode4Manufacturer()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Daten-
typ
Länge Format
amountWeight Gewicht Float
collectCode Abholcode String 4
registrationNumber Registrierungsnummer Integer 8
uomWeight Gewichtseinheit, siehe Maß-
einheit
Integer 3
wg_date Parameter ist optional: Wiege-
scheindatum,
String 10 DD.MM.YYYY
wg kfz KFZ Kennzeichen LKW String 50
wg_number Wiegescheinnummer String 50
mengeGasentladungslampen Menge der Gasentladungs-
lampen
Float
mengeSonstigeLampen Menge der sonstigen Lampen Float
Tabelle 3: Parameter 'currentOutputCollectCode4Manufacturer'
Die Parameter „mengeGasentladungslampen“ und „mengeSonstigeLampen“ sind nur bei einigen
Kombinationen von Geräteart und Sammelgruppe Pflichtfelder. Dies hängt von der aktuellen Um-
setzung ab.
Antwort:
StandardResponse
2.2.1.5 currentOutputSelfWithdrawelByWeightNote()
Mit dieser Funktion können Eigenrücknahmen mitgeteilt werden. Die Mitteilung kann monatlich
erfolgen und es gelten die gleichen Fristen wie unter Ziffer 2.2.1.2 angegeben.
Funktionsaufruf:
currentOutputSelfWithdrawelByWeightNote()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
amountWeight Gewicht Float
bookingYear Jahr für das die Mel-
dung gilt
Integer 4 YYYY
bookingMonth Monat für den die Mel-
dung gilt
Integer 2 MM
category Kategorie Integer 8
deviceType Geräteart Integer 3
registrationNumber Registrierungsnummer Integer 8
uomWeight Gewichtseinheit, siehe
Maßeinheit
Integer 3
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
15/25
mengeGasentladungslampen Menge der Gasentla-
dungslampen
Float
mengeSonstigeLampen Menge der sonstigen
Lampen
Float
Tabelle 4: Parameter ' currentOutputSelfWithdrawelByWeightNote'
Die Parameter „mengeGasentladungslampen“ und „mengeSonstigeLampen“ sind nur bei einigen
Kombinationen von Geräteart und Sammelgruppe Pflichtfelder. Dies hängt von der aktuellen Um-
setzung ab.
Antwort:
StandardResponse
2.2.1.6 isAlive
Diese Funktion beinhaltet eine Abfrage, welche prüft, ob der SOAP Service aktiv ist. Dies ist ver-
gleichbar mit einem Ping.
Funktionsaufruf: isAlive ohne Parameter
Antwort:
StandardResponse
2.2.1.7 currentIndirectExport
Mit dieser Funktion können Mittelbare Exportmitteilungen übermittelt werden. Die Mitteilung
kann monatlich erfolgen und es gelten die gleichen Fristen wie unter Ziffer 2.2.1.2 angegeben. Es
besteht eine Korrelation zwischen der Mittelbaren Exportmitteilung und der jeweiligen Ist-Input-
mitteilung: Das Meldegewicht der Mittelbare Exportmitteilung muss stets ≤ des Meldegewichts
der Ist-Inputmitteilung des Meldemonats sein.
Funktionsaufruf:
currentIndirectExport()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
amountWeight Gewicht Float
bookingYear Jahr für das die Mel-
dung gilt
Integer 4 YYYY
bookingMonth Monat für den die Mel-
dung gilt
Integer 2 MM
category Kategorie Integer 8
deviceType Geräteart Integer 3
uomWeight Gewichtseinheit, siehe
Maßeinheiten.
Integer 3
mengeGasentladungslampen Menge der Gasentla-
dungslampen
Float
mengeSonstigeLampen Menge der sonstigen
Lampen
Float
Tabelle 5: Parameter 'currentIndirectExport'
Die Parameter „mengeGasentladungslampen“ und „mengeSonstigeLampen“ sind nur bei einigen
Kombinationen von Geräteart und Sammelgruppe Pflichtfelder. Dies hängt von der aktuellen Um-
setzung ab.
Antwort:
StandardResponse
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
16/25
2.2.1.8 getListOfDeviceTypes
Mit dieser Funktion können die im System konfigurierten Sammelgruppen, Kategorien und Gerä-
tearten abgerufen werden.
Funktionsaufruf:
getListOfDeviceTypes()
Antwort:
ListDeviceTypes
2.2.2 EarSoapPickupService
Der EarSoapPickupService beinhaltet Funktionen zum Abruf von Informationen zur Abholkoordi-
nation. Hersteller können sich hier u.a. generierte PDF-Dokumente herunterladen.
Der Anwender der Schnittstelle ruft zunächst die Methode "getCodes()" auf. Diese ermittelt die
Schlüssel-Daten (Abholungs-/Aufstellungscode, Status, Art) nach den übergebenen Kriterien. Die
Daten werden als XML zur Verfügung gestellt und bestehen aus einer Liste der den Kriterien ent-
sprechenden Abholungs-/Aufstellungscodes (Code) inklusive des Status sowie der Art.
Wird beim Aufruf der Methode "getCodes()" der Parameter "changesOnly" mit dem Wert "1"
übergeben, werden nur Abholungen aufgelistet, welche sich seit dem letzten Abruf der Details
(siehe unten) geändert haben. Eine Änderung kann beispielsweise ein neuer Abholstatus sein.
Im Anschluss an "getCodes()" kann der Anwender zu jedem der über diese Methode gelieferten
Code in Abhängigkeit der "Art" Detailinformationen über die Methoden "getAbholungDetails()",
"getBereitstellungDetails()", "getAbholungBereitstellungDetails()" abrufen.
In diesen Detailinformationen sind alle relevanten Daten aus den Dokumenten der jeweiligen An-
ordnung enthalten. Die Daten werden in elektronisch zu verarbeitender Form zurückgeliefert. Zu-
sätzlich zu diesen Daten werden dem Anwender auch die Dokumente und die zu den Dokumenten
zugehörigen Signaturen übermittelt.
Für jeden der aus der Methode "getCodes()" gelieferten Code kann der Anwender außerdem den
dazugehörigen Gebührenbescheid abrufen. Hier werden sowohl die relevanten Daten des Gebüh-
renbescheids elektronisch geliefert, als auch (wie bei den Detailabfragen) das Dokument zuzüglich
der Signatur.
Des Weiteren bietet die Schnittstelle dem Anwender die Möglichkeit, im ear-System an "seinen"
Code einen eigenen Status zu pflegen. Dies geschieht über die Methode "setStatusHst()". Dieser
durch den Anwender frei zu belegende Status kann bei der Methode "getCodes()" als "Von" -
"Bis" Kriterium mit übergeben werden und versetzt den Anwender in die Lage, sich eine vom ear-
System unabhängige Logik der Abholung/Nachverfolgung von Codes aus dem ear-System auf-
zubauen. Der herstellereigene Status findet außerhalb der in diesem Dokument beschriebenen
Schnittstellenfunktionalität keine Verwendung.
Die Parameter der benötigten Funktionen sind nachfolgend beschrieben.
2.2.2.1 getCodes()
Unter Verwendung dieser Funktion können die dem Hersteller zugeordneten Codes nach vom
Anwender frei zu definierenden Kriterien (Datum ab, Datum bis, Status des Codes) abgerufen
werden.
Sofern fachlich nicht nach der Art des Codes differenziert werden muss (vgl. Ziffer 3.1.1), empfiehlt
es sich, die Funktion getCodes ohne den Parameter „status“ aufzurufen. In der Antwort sind die
korrekten Status enthalten und können für nachfolgende Aufrufe (bspw. getDetails) bzw. für die
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
17/25
Verzweigung zu den Detailfunktionen getAbholungDetails, getBereitstellungDetails, getAbholung-
BereitstellungDetails verwendet werden.
Diese Funktion liefert maximal 100 Codes, weitere Codes können über subsequente Aufrufe mit
einer weiteren Seite (page) ausgelesen werden.
Funktionsaufruf:
getCodes
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
von Datum von Datum 10 YYYY-MM-DD
bis Datum bis Datum 10 YYYY-MM-DD
changesOnly Nur Änderungen „0“=nein, „1“=ja Integer 1
status Status der Abholung (siehe Ziffer 3.1.1). Op-
tionaler Parameter, kann weggelassen oder
mit „0“ = Alle übermittelt werden.
Integer 3
statusHstBis Max. HST Status Integer 3
statusHstVon Min. HST Status Integer 3
page Nummer der angefragten Seite (Paging), je
Seite werden 100 Codes geliefert. Der Sei-
tenzähler beginnt bei „1“
Integer 10
Tabelle 6: Parameter 'getCodes'
Bei den min. und max. Herstellerstatus handelt es sich um eigene Status des Teilnehmers, welche
nicht vom ear-System verarbeitet werden. So können mit diesen Status bestimmte Codes mittels
des Buchungsschlüssels, wie unter Ziffer 3.1.1 beschrieben, markiert wieder ausgewertet werden.
Antwort:
getCodesResponse
2.2.2.2 getDetails()
getDetails() liefert Detailinformationen zu einem bestimmten Code; diese entsprechen den Daten
der Abholanordnung/Aufstellungsanordnung.
Mit dem Lesen der Details wird das Flag „changed“ zurückgesetzt. Damit ist das Lesen der
Codes mit dem Parameter „changesOnly“ = 1 nur einmal möglich.
Funktionsaufruf:
getDetails()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
art Detailtyp von Buchungsschlüssel
siehe Ziffer 3.1.1
Integer 3
codeId Abholungs-/Aufstellungscode String 4
Tabelle 7: Parameter 'getDetails'
Antwort:
Detailinformation
2.2.2.3 getDetails() differenzierter
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
18/25
Mit Hilfe der folgenden Funktionen können bestimmte Daten zu diesem Code abgefragt werden.
Dies ist analog zu der vorherigen Beschreibung von getDetails(). Im Unterschied hierzu muss bei
folgenden Funktionsaufrufen der Parameter "art" nicht übergeben werden.
Funktionsaufrufe:
▪ getAbholungDetails(),
▪ getBereitstellungDetails(),
▪ getAbholungBereitstellungDetails(),
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
code Abhol-/ Aufstellungscode String 4
Tabelle 8: Parameter der differenzierten 'getDetails' Funktionen
Antwort:
Detailinformation
2.2.2.4 getKostenbescheid()
Funktionsaufruf: getKostenbescheid()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
codeId Abhol-/Aufstellungscode String 4
Tabelle 9: Parameter 'getKostenbescheid'
Antwort:
Gebührenbetrag
2.2.2.5 setStatusHst()
Diese Funktion unterstützt das Setzen eines herstellerindividuellen Status zu einem Abholcode,
Wert des Status numerisch ganzzahlig (0-99).
Funktionsaufruf:
setStatusHst()
Folgende Datentypen müssen die Parameter haben:
Parameter Beschreibung Datentyp Länge Format
codeId Abhol-/Aufstellungscode String 4
statushst Status Hersteller Integer 3
Tabelle 10: Parameter 'setStatusHst'
Antwort:
StandardResponse
2.3 Rückantwort der SOAP Funktionen
Die verschiedenen Rückantwortelemente der SOAP Anfragen sind in den folgenden Kapiteln auf-
gegliedert. Elemente können Unterelemente enthalten. Wenn dies der Fall ist, ist in der Spalte
"Datentyp" der Elementtyp gelistet. Weiterhin können Unterelemente auch Listen von Elementen
sein. Diese sind durch ein eckiges Paar von Klammer gekennzeichnet. In allen anderen Fällen han-
delt es sich um einen skalaren Datentypen (zum Beispiel: String, Integer, DateTime).
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
19/25
2.3.1 StandardResponse
Bei den meisten SOAP Anfragen wird im Response-XML der Wert code übertragen. Dieser enthält
im Nicht-Fehlerfall den Wert "0", im Fehlerfall den Wert „-1“.
Element Beschreibung Datentyp
code Returncode Integer
text Meldetext String
Tabelle 11: 'StandardResponse' - Elemente
2.3.2 Adresse
Element Beschreibung Datentyp
email E-Mail Adresse String
name Name 1 String
ort Ort String
plz Postleitzahl String
strasse Strasse String
Tabelle 12: 'Adresse' - Elemente
2.3.3 Anschrift
Element Beschreibung Datentyp
adresse Adresselement Adresse
telefax Telefaxelement Telefax
telefon Telefonelement Telefon
Tabelle 13: 'Anschrift' – Elemente
2.3.4 Ansprechpartner
Element Beschreibung Datentyp
adresse Adresselement Adresse
idAnsprechpartner Benutzer-ID Integer
telefax Telefaxelement Telefax
telefon Telefonelement Telefon
Tabelle 14: 'Ansprechpartner' - Elemente
2.3.5 Code
Element Beschreibung Datentyp
art Abgefragter Buchungsschlüssel Art (siehe Ziffer 3.1.1) Integer
codeld Abhol-/Aufstellungscode String
datumPickUp Abfragedatum DateTime
getDetailCount Anzahl Detailabfragen Integer
status Status der Abholung, Aufstellung, Abholung und Aufstellung
(siehe Ziffer 3.2)
Integer
statusHst Durch Hersteller gesetzten Status siehe Ziffer 2.2.2.5 Integer
statusText Status in Textform (siehe Ziffer 3.2) String
Tabelle 15: 'Code' - Elemente
2.3.6 getCodesResponse
Element Beschreibung Datentyp
resultSize Anzahl von Code Elementen die insgesamt vorhanden sind,
unter Berücksichtigung der Abfrageparameter
Integer
Codes Liste von Codes Codes
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
20/25
Tabelle 16: 'getCodesResponse' – Elemente
2.3.7 Codes
Dieser Rückgabewert enthält alle abgefragten Abholcodes inklusive Abholstatus als XML-Liste.
Element Beschreibung Datentyp
Art Abgefragte Buchungsschlüssel Art (siehe Ziffer 3.1.1) Integer
Codeld Abhol-/Aufstellungscode String
registrierungs-
nummer
Registrierungsnummer Integer
geraeteartId ID der Geräteart Integer
Status Status der Abholung, Bereitstellung (siehe Ziffer 3.2) Integer
statusText Status in Textform (siehe Ziffer 3.2) String
Tabelle 17: 'Codes' - Elemente
2.3.8 Detailinformation
Element Beschreibung Datentyp
Code Abhol-/Aufstellungscodeelement Code
datumAufforderung Datum der Vollmeldung DateTime
datumBestaetigung Datum der Bestätigung DateTime
dokumente Liste von Dokumenten Dokument
Entsorger Entsorgerelement Entsorger
sammelgruppe Sammelgruppe Sammelgruppe
transporteinheit Transporteinheit Transporteinheit
Hersteller Herstellerelement Hersteller
Termin Abholfrist Abholfrist
uebergabestelle Übergabestellenelement Uebergabestelle
Tabelle 18: 'Detailinformation' - Elemente
2.3.9 Dokument
Ein Dokument wird im Regelfall als Teil einer Liste (Array von Dokumenten) binär übergeben.
Element Beschreibung Datentyp
dokumentPdf PDF-Dokument Binär
dokumentSignatur Dokumentensignatur Binär
Tabelle 19: 'Dokument' - Elemente
2.3.10 Entsorger
Element Beschreibung Datentyp
Adresse Adresselement Adresse
idEntsorger Entsorger-ID Integer
Name Entsorgername String
Telefax Telefaxelement Telefax
Telefon Telefonelement Telefon
Tabelle 20: 'Entsorger' - Elemente
2.3.11 Gebühr
Element Beschreibung Datentyp
beginnDatum Beginndatum DateTime
antragsDatum Antragsdatum DateTime
bescheidDatum Bescheidsdatum DateTime
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
21/25
Leistungsdatum Leistungsdatum DateTime
Gebuehr Gebühr Float
steuerbetrag Steuerbetrag Float
Nummer Nummer der Gebühr Float
kostenstelle Kostenstelle Float
gebuehrentatbestand Gebührentatbestand Gebuehrentatbe-
stand
Tabelle 21: 'Gebühr' - Elemente
2.3.12 Gebührenbetrag
Element Beschreibung Datentyp
gebuehren Liste von Gebühren Gebühr
gesamtsumme Gesamtsumme der Gebühren Float
mwst Mehrwertsteuer Float
zwischensumme Zwischensumme Float
Tabelle 22: 'Gebührenbetrag' – Elemente
2.3.13 ListDeviceTypes
Element Beschreibung Datentyp
deviceType Ein Liste von DeviceTypes, siehe Ziffer 2.3.14 DeviceTypes
Tabelle 23: 'ListOfDeviceTypes' - Elemente
2.3.14 DeviceTypes
Element Beschreibung Datentyp
sammelgruppe Ein Element Sammelgruppe, siehe Ziffer 2.3.16 Sammelgruppe
kategorie Ein Element Kategorie, siehe Ziffer 2.3.17 Kategorie
geraeteart Nummer der Geräteart, findet Verwendung als Pa-
rameter 'deviceType' in anderen Funktionen
Integer
beschreibung Textuelle Beschreibung der Geräteart String
Tabelle 24: 'DeviceTypes' - Elemente
2.3.15 Gebührentatbestand
Element Beschreibung Datentyp
name Name String
nummer Nummer String
schluessel Schlüssel String
Tabelle 25: 'Gebührentatbestand' - Elemente
2.3.16 Sammelgruppe
Element Beschreibung Datentyp
name Name String
nummer Nummer Integer
Tabelle 26: 'Sammelgruppe' - Elemente
2.3.17 Kategorie
Element Beschreibung Datentyp
name Name String
nummer Nummer Integer
Tabelle 27: 'Sammelgruppe' - Elemente
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
22/25
2.3.18 Transporteinheit
Element Beschreibung Datentyp
bezeichung Bezeichung String
abholvolumen Abholvolumen Float
transeinheitsaufbau Liste von Transeinheitsaufbau Transporteinheitsaufbau
Tabelle 28: 'Transporteinheit' - Elemente
2.3.19 Transporteinheitsaufbau
Element Beschreibung Datentyp
anzahl Anzahl Float
behaeltnis Behältnis Behältnis
Tabelle 29: 'Transporteinheitsaufbau' - Elemente
2.3.20 Behältnis
Element Beschreibung Datentyp
bezeichnung Bezeichnung String
volumen Volumen Float
Tabelle 30: 'Behältnis' – Elemente
2.3.21 Hersteller
Element Beschreibung Datentyp
adresse Adresselement Adresse
hauptansprechpartner Hauptansprechpartnerelement Ansprechpartner
id teilnehmer Benutzer-ID Integer
konto Kontoelement Konto
rechnungsanschrift Rechnungsanschriftelement Anschrift
telefax Telefaxelement Telefax
telefon Telefonelement Telefon
Tabelle 31: 'Hersteller' - Elemente
2.3.22 Konto
Element Beschreibung Datentyp
bankName Name der Bank String
bic BIC String
iban IBAN String
Tabelle 32: 'Konto' - Elemente
2.3.23 Kostenbetrag
Element Beschreibung Datentyp
gebuehrenbetrag Liste von Gebührenbeträgen Gebührenbetrag
Tabelle 33: 'Kostenbetrag' - Elemente
2.3.24 Gebührenbescheid
Element Beschreibung Datentyp
vorgangsId VorgangsID String
code Abhol-/Aufstellungscodeelement Code
dokument Gebührenbescheidsdokument Dokument
hersteller Herstellerelement Hersteller
idBescheid Bescheidsnummer Integer
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Technik
23/25
idDebitor Debitorennummer String
idRegistrierung Registrierungsnummer (aka WE3) Integer
kosten Kosten als Summe Float
kostenbetrag Kostenbetrag mit Details Kostenbetrag
sendedatum Kostenbetrag mit Details DateTime
Steuernummer Steuernummer String
Tabelle 34: 'Gebührenbescheid' - Elemente
2.3.25 Telefon/Telefax
Element Beschreibung Datentyp
durchwahl Durchwahl String
landesvorwahl Landesvorwahl String
nummer Nummer String
ortsvorwahl Ortsvorwahl String
Tabelle 35: 'Telefon/Telefax' - Elemente
2.3.26 Abholfrist
Element Beschreibung Datentyp
bis Enddatum String
von Startdatum String
wunschtermin Wunschtermin DateTime
Tabelle 36: 'Abholfrist' - Elemente
2.3.27 Übergabestelle
Element Beschreibung Datentyp
adresse Adresselement Adresse
idUebergabestelle Übergabestellen-ID Integer
leitungsbefugter Leistungsbefugterelement Ansprechpartner
telefon Telefonelement Telefon
Tabelle 37: 'Übergabestelle' - Elemente
2.4 Aufrufe in eigener Implementierung verwenden
Wenn in einer eigenen Implementierung auf die SOAP Schnittstelle zugreifen werden soll, kann
aus den zwei genannten Webservices automatisch die notwendigen Quellcodedateien für eine
Verarbeitung erzeugt werden. In der Programmiersprache Java können beispielsweise mittels
Apache Axis aus den WSDL-Dateien die notwendigen Klassen für die SOAP Aufrufe erzeugt wer-
den. Aufgrund der Menge an möglichen Programmiersprachen für Implementierungen von Zu-
griffen auf die SOAP Schnittstelle werden von der stiftung ear keine Programmcodes bereitge-
stellt.
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Schlüsseltabellen
24/25
3 Schlüsseltabellen
3.1 Generelle Schlüssel
3.1.1 Art bei Buchungsschlüssel
Status ID Beschreibung
0 Alles (Abholung, Aufstellung, Abholung und Aufstellung)
1 Abholung (fachlicher Auslöser: Abmeldung einer Transporteinheit)
2 Aufstellung (fachlicher Auslöser: Erstgestellung einer Transporteinheit)
3 Abholung und Aufstellung (fachlicher Auslöser: Vollmeldung einer Trans-
porteinheit)
Tabelle 38: Buchungsschlüssel
Die Art des Buchungsschlüssels spezifiziert den fachlichen Auslöser für die Abholung bzw. Bereit-
stellung.
Eine Abmeldung einer Transporteinheit entspricht fachlich der „1“, einer Abholung ohne Bereit-
stellung.
Wird eine Erstgestellung angefordert führt dies zu einer Aufstellung. Eine Aufstellung hat die Art
„2“.
Eine Vollmeldung führt zu einer Abholung und Aufstellung (Art = „3“).
Durch die zugrundeliegende fachliche Semantik, werden nur Codes, bzw. Details zu Codes gelie-
fert, wenn die Art des Buchungsschlüssels identisch ist mit der Art des Codes.
3.1.2 Maßeinheiten
ID Masseinheiten Beschreibung
1 Kilogramm
2 Stück
3 Tonnen
Tabelle 39: Maßeinheiten
3.2 Status
3.2.1 Abholung
Status ID Beschreibung
0 Abholung unbearbeitet
1 Abholung zugewiesen
2 Abholung angemahnt
5 Abholung bestätigt nach Zuweisung
6 Abholung bestätigt nach Anmahnung
8 Abholung aufgehoben
Tabelle 40: Status - 'Abholung'
3.2.2 Aufstellung
Status ID Beschreibung
0 Aufstellung unbearbeitet
1 Aufstellung zugewiesen
2 Aufstellung angemahnt
5 Aufstellung bestätigt nach Zuweisung
6 Aufstellung bestätigt nach Anmahnung
8 Aufstellung aufgehoben
SOAP Schnittstelle für die Mengenmitteilung und Abfrage von AHK-Daten
Anleitung und Schnittstellendokumentation Schlüsseltabellen
25/25
Tabelle 41: Status - 'Aufstellung'
3.2.3 Abholung und Aufstellung
Status ID Beschreibung
0 Abholung unbearbeitet, Aufstellung unbearbeitet
1 Abholung zugewiesen, Aufstellung zugewiesen
2 Abholung angemahnt, Aufstellung angemahnt
5 Abholung bestätigt nach Zuweisung, Aufstellung bestätigt nach Zuweisung
6 Abholung bestätigt nach Anmahnung, Aufstellung bestätigt nach Anmahnung
8 Abholung aufgehoben, Aufstellung aufgehoben
12 Abholung zugewiesen, Aufstellung angemahnt
15 Abholung zugewiesen, Aufstellung bestätigt nach Zuweisung
16 Abholung zugewiesen, Aufstellung bestätigt nach Anmahnung
18 Abholung zugewiesen, Aufstellung aufgehoben
21 Abholung angemahnt, Aufstellung zugewiesen
25 Abholung angemahnt, Aufstellung bestätigt nach Zuweisung
26 Abholung angemahnt, Aufstellung bestätigt nach Anmahnung
28 Abholung angemahnt, Aufstellung aufgehoben
51 Abholung bestätigt nach Zuweisung, Aufstellung zugewiesen
52 Abholung bestätigt nach Zuweisung, Aufstellung angemahnt
56 Abholung bestätigt nach Zuweisung, Aufstellung bestätigt nach Anmahnung
58 Abholung bestätigt nach Zuweisung, Aufstellung aufgehoben
61 Abholung bestätigt nach Anmahnung, Aufstellung zugewiesen
62 Abholung bestätigt nach Anmahnung, Aufstellung angemahnt
65 Abholung bestätigt nach Anmahnung, Aufstellung bestätigt nach Zuweisung
68 Abholung bestätigt nach Anmahnung, Aufstellung aufgehoben
81 Abholung aufgehoben, Aufstellung zugewiesen
82 Abholung aufgehoben, Aufstellung angemahnt
85 Abholung aufgehoben, Aufstellung bestätigt nach Zuweisung
86 Abholung aufgehoben, Aufstellung bestätigt nach Anmahnung
Tabelle 42: Status - 'Abholung und Aufstellung'