AbholkoordinationsService Service

Der AbholkoordinationsService beinhaltet Funktionen zum Abruf von Informationen zur Abholkoordination. Hersteller können sich hier u.a. generierte PDF-Dokumente herunterladen. Bitte beachten Sie, dass Sie nur noch für Anordnungen (Codes) welche bis einschließlich 27.12.2023 ergangen sind die entsprechenden Gebührenbescheide über die Schnittstelle abrufen können.

Der Anwender der Schnittstelle ruft zunächst die Methode getCodes auf. Diese ermittelt die Schlüsseldaten (Abholungs-/Aufstellungscode, Status, Art) nach den übergebenen Kriterien. Die Daten werden als XML zur Verfügung gestellt und bestehen aus einer Liste, die den Kriterien entsprechenden Abholungs-/Aufstellungscodes (Code) inklusive des Status sowie der Art entspricht.

Des Weiteren bietet die Schnittstelle dem Anwender die Möglichkeit, im ear-System an den eigenen Abholungen bzw. Aufstellungen einen herstellereigenen Status zu pflegen. Dies geschieht über die Methode setStatusHst. Dieser durch den Anwender frei zu belegende Status kann bei der Methode getCodes als statusHstVon - statusHstBis Kriterium mit übergeben werden und versetzt den Anwender in die Lage, sich eine vom ear-System unabhängige Logik der Abholung bzw. Nachverfolgung von Codes aus dem ear-System aufzubauen. Der herstellereigene Status findet außerhalb der in diesem Dokument beschriebenen Schnittstellenfunktionalität keine Verwendung.

Die Dokumente werden bei den Aufrufen getDetails bzw. getGebuehrenbescheid mittels SOAP Message Transmission Optimization Mechanism (MTOM) übertragen. Dabei wird XOP für die Übermittlung der binären Daten verwendet. Bei den übertragenen Dokumenten handelt es sich ausschließlich um PDF-Dokumente. Bei der Implementierung eines Clients ist darauf zu achten, dass die Codierung der SOAP-Nachrichten entsprechend konfiguriert ist (z.B für .NET binding.MessageEncoding = WSMessageEncoding.Mtom).

Namespace
http://www.ear-system.de/ear-soap/v2
WSDL
/AbholkoordinationsService?wsdl

isAlive Operation

Diese Funktion beinhaltet eine Abfrage, welche prüft, ob der SOAP Service aktiv ist. Dies ist vergleichbar mit einem Ping.

Verfügbar ab
2.0
Rückgabewert
Typ Beschreibung
StandardResponse Text Service verfügbar, wenn verfügbar.
Exception
Name Typ Bedingung
ServiceException ServiceException Service ist nicht verfügbar oder interner Serverfehler

getCodes Operation

Unter Verwendung dieser Funktion können die dem Hersteller zugeordneten Codes nach vom Anwender frei zu definierenden Kriterien (Datum von, Datum bis) abgerufen werden. Das Datum bezieht sich jeweils auf das Anforderungsdatum der Abholung bzw. Aufstellung. Ist keine zeitliche Einschränkung gewünscht, so ist der Parameter mit einem Nullwert (null) zu übergeben.

Desweitern kann die Ergebnismenge mit der dem Paramter art, entsprechend des fachlichen Auslösers, eingeschränkt werden. Wird der Wert "0" übergeben, findet keine Einschränkung statt, der Wert "1" ist für die Einschränkung der Liste auf Abmeldungen, der Wert "2" für Einschränkung auf Erstgestellungen und der Wert "3" schränkt die Liste auf Vollmeldungen ein.

Wird der Parameter changesOnly mit dem Wert "true" übergeben, werden nur Abholungen/Aufstellungen aufgelistet, welche sich seit dem letzten Abruf der Details über die Methode getDetails geändert haben. Eine Änderung kann beispielsweise ein neuer Abholstatus sein.

Bei den Parametern statusHstVon und statusHstBis handelt es sich um einen herstellereigenen Status. Mit Hilfe dieser Parameter kann die Ergebnismenge bezüglich dieses Status eingeschränkt werden (siehe setStatusHst). Ist keine Filterung auf den herstellereigenen Status gewünscht, so ist der Parameter mit einem Nullwert (null) zu übergeben.

Die Funktion liefert maximal 100 Codes, weitere Codes können über subsequente Aufrufe mit einer weiteren Seite (page) ausgelesen werden.

Erforderliche Berechtigungen:

  • Daten zur Abholkoordination über SOAP abrufen

Verfügbar ab
2.0
Eingabeparameter
Name Typ Beschreibung
von dateTime Untere Datumsgrenze bezogen auf das Anforderungsdatum. Das Format ist YYYY-MM-DD. Zeitangaben werden ignoriert. Der Parameter ist optional und erlaubt ein Nullwert (null = Keine Filterung).
bis dateTime Obere Datumsgrenze bezogen auf das Anforderungsdatum. Das Format ist YYYY-MM-DD. Zeitangaben werden ignoriert. Der Parameter ist optional und erlaubt ein Nullwert (null = Keine Filterung).
changesOnly boolean Nur Änderungen anzeigen. Bei "true" werden nur Abholungen/Aufstellungen aufgelistet, welche sich seit dem letzten Abruf der Details über die Methode getDetails() geändert haben.
art Art Einschränkung bezüglich des fachlichen Auslösers. Erlaubte Werte sind 0, 1, 2 und 3.
statusHstVon int Untere Grenze des herstellereigenen Status. Erlaubte Werte sind Zahlen von 0 bis 999 oder ein Nullwert (null = Keine Filterung).
statusHstBis int Obere Grenze des herstellereigenen Status. Erlaubte Werte sind Zahlen von 0 bis 999 oder ein Nullwert (null = Keine Filterung).
page int Nummer der angefragten Seite (Paging), je Seite werden max. 100 Codes geliefert. Der Seitenzähler beginnt bei 1.
Rückgabewert
Typ Beschreibung
Codes Liste von Abholungen/Aufstellungen entprechend der übergebenen Kriterien
Exception
Name Typ Bedingung
ServiceException ServiceException Ungültiges Format der übergebenen Parameter oder es liegt interner Serverfehler vor

getDetails Operation

Die Funktion getDetails() liefert Detailinformationen zu einem bestimmten Code. Diese entsprechen den Daten der Abholanordnung/Aufstellungsanordnung. Die Abholanordnung bzw. Aufstellungsanordnung werden mit MTOM mittels XOP übertragen.

Mit dem Lesen der Details wird ein internes Flag zurückgesetzt. Damit ist das Lesen der Codes mittels der Methode getCodes mit dem Parameter changesOnly = "true" nur einmal möglich.

Erforderliche Berechtigungen:

  • Daten zur Abholkoordination über SOAP abrufen

Verfügbar ab
2.0
Eingabeparameter
Name Typ Beschreibung
codeId string 4 stelliger Abhol- bzw. Aufstellungscode
Rückgabewert
Typ Beschreibung
Detailinformation Detailinformationen zu einer Abholung bzw. Aufstellung zu einem bestimmten Code
Exception
Name Typ Bedingung
ServiceException ServiceException Ungültiges Format des übergebenen Parameters, Code existiert nicht oder es liegt interner Serverfehler vor

getGebuehrenbescheid Operation

Diese Funktion liefert den Gebührenbescheid inklusive der einzelnen Gebühren zu einem bestimmten Code. Zu beachten ist, dass der Gebührenbescheid erst nach der sog. Bekanntgabefiktion, also 4 Tage nach Auslösen der Vollmeldung, Erstgestellung oder Abmeldung, vorliegt. Das Dokument wird mit MTOM mittels XOP übertragen. Bitte beachten Sie, dass Sie nur noch für Anordnungen (Codes) welche bis einschließlich 27.12.2023 ergangen sind die entsprechenden Gebührenbescheide über die Schnittstelle abrufen können.

Erforderliche Berechtigungen:

  • Daten zur Abholkoordination über SOAP abrufen
  • Bescheide einsehen und herunterladen

Verfügbar ab
2.0
Eingabeparameter
Name Typ Beschreibung
codeId string 4 stelliger Abhol- bzw. Aufstellungscode
Rückgabewert
Typ Beschreibung
Gebuehrenbescheid Gebührenbescheid inklusive der einzelnen Gebühren, der zum übergebenen Abhol- bzw. Aufstellungscode gehört
Exception
Name Typ Bedingung
ServiceException ServiceException Ungültiges Format des übergebenen Parameters, Code existiert nicht oder es liegt interner Serverfehler vor

setStatusHst Operation

Diese Funktion dient dem Setzen eines herstellerindividuellen Status zu einem Abholcode. Der Wert des Status muss numerisch ganzzahlig zwischen 0 und 999 sein.

Erforderliche Berechtigungen:

  • Daten zur Abholkoordination über SOAP abrufen

Verfügbar ab
2.0
Eingabeparameter
Name Typ Beschreibung
codeId string 4 stelliger Abhol- bzw. Aufstellungscode
statusHst int Herstellerindividueller Status. Erlaubte Werte von 0 bis 999. Wird ein Nullwert (null) übergeben, so wird der herstellerindividuelle Status gelöscht.
Rückgabewert
Typ Beschreibung
StandardResponse Status wurde geändert bzw. Status nicht geändert, wenn der Status bereits den gewünschten Wert hatte.
Exception
Name Typ Bedingung
ServiceException ServiceException Ungültiges Format des übergebenen Parameters, Code existiert nicht oder es liegt interner Serverfehler vor

Impressum | Disclaimer | Datenschutzerklärung
© ear ist eine eingetragene Marke
Schnittstellen-Version 2.5