25
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 Dokumentation für Anwender der SOAP ... · stiftung elektro-altgeräte register SOAP Schnittstelle Dokumentation für Anwender der SOAP Schnittstelle Version 1.10

Embed Size (px)

Citation preview

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ß

[email protected]

+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'