Dokumentation für Anwender der HGS-Schnittstelle

Allgemein

Anbieter von Herstellergarantiesystemen (HGS) müssen der stiftung ear die Garantiebeträge, die sie ihren Kunden zugeordnet haben, über die zur Verfügung gestellte HGS-Schnittstelle übermitteln. Die Schnittstelle basiert auf REST, alle Daten werden im JSON Format ausgetauscht.

Die übermittelten Garantiebeträge sind immer an eine Zusatzinformation-Garantie, ein Beginn und ein Ende der Gültigkeitsowie eine Geräteart gebunden. Ein einmal übermittelter Garantiebetrag kann nicht gelöscht werden. Es ist ausschließlich die Änderungeines Garantiebetrags möglich.

Ab dem 01.01.2024 gilt folgende Formatvorgabe für die Zusatzinformation-Garantie: Die ersten vier Stellen bestehen aus der Garantie-ID des HGS, die weiteren sieben Stellen sind ausschließlich Ziffern.

Zusatzinformation-Garantie:= ^[A-Za-z0-9]{4}[0-9]{7}$

Mit der Bereitstellung der neuen Schnittstellenversion zum 01.01.2024 werden die bis zu diesem Zeitpunkt übermittelten Zusatzinformationen-Garantiemit einer Zuordnung zu einem Hersteller in der ear-Anwendungssoftware migriert. Die Vergabe erfolgt systemweit nach einem Schema. Übermittelte Garantiebeträge, die nicht zugeordnet wurden, werden gelöscht.

Nach dem 01.01.2024 ist jedes HGS selbst verantwortlich für die korrekte Vergabe der Zusatzinformation-Garantie. Jedes HGS erhält von der stiftung ear eine Liste aus der die zum 31.12.2023 vorgenommene Migration nachvollziehbar ist und in die eigenen EDV-Systeme der HGS übernommen werden kann.

Die HGS-Schnittstelle bietet hiernach folgende Funktionalitäten an:

(a) Passwort ändern:

Das initial von der stiftung ear vergebene Kennwort muss zwingend vom HGS geändert werden, bevor weitere Schnittstellenfunktionen erfolgreich aufgerufen werden können.

(b) Gerätearten:

Diese Funktion liefert eine Liste aller Gerätearten der ear-Anwendungssoftware. Die hier gelieferte ID wird in subsequenten Aufrufen benötigt.

(c) Garantiebetrag übermitteln:

Die Funktion zur Übermittlung des Garantiebetrags.

(d) Übermittelte Garantiebeträge lesen:

Diese Funktion steht ab dem 01.01.2024 vollumfänglich zur Verfügung. Mit dieser Funktion können die aktuellen und bereits übermittelten Garantiebeträge abgefragt werden.

Anbieter von HGS müssen für die Nutzung der hier beschriebenen HGS-Schnittstelle von der stiftung ear freigeschaltet werden. Zu technischen Fragen im Hinblick auf die Übermittlung von Garantiedaten wenden Sie sich bitte per E-Mail an system@stiftung-ear.de.

Mit der Einrichtung des Zugangs und dem Ändern des Initialkennwortes stehen alle Aufrufe der Schnittstelle zur Verfügung und können von jedem beliebigen REST-Client verwendet werden.

Um die Schnittstelle seitens des Anbieters eines HGS testen zu können, steht ein separates Testsystem zur Verfügung. Für die Nutzung dieses Testsystems sind obligatorisch:

• Der URL: https://test.ear-system.de/ear-hgs/,
• ein Benutzername ("test") sowie
• ein Initialkennwort ("test").

Ferner steht über die o.g. URL auch eine interaktive Schnittstellenbeschreibung zur Verfügung, die alle REST-Aufrufe detailliert beschreibt.

Ablaufbeschreibung für die Nutzung

Zur erfolgreichen Inbetriebnahme der HGS-Schnittstelle sind folgende Schritte vorgesehen:

Was	Wer	Beschreibung
Entwicklung HGS-Client	HGS	Entwicklung eines HGS-Schnittstellenclients gegen die HGS-Schnittstelle des Testsystems
Test	HGS	Test des HGS-Schnittstellenclients gegen die HGS-Schnittstelle des Testsystems.
Beantragung eines Zugangs zum Produktivsystem	HGS	Mitteilung an die stiftung ear, dass das HGS zukünftig die Schnittstelle nutzen will.
Übermittlung der Zugangs-daten Produktivsystem	stiftung ear	Nach Einrichtung des Zugangs zum HGS-System übermittelt die stiftung ear dem HGS: Benutzername, Kennwort und URL der REST-Schnittstelle auf dem Produk-tivsystem
Nutzung der HGS Schnittstelle	HGS	Nutzung im Regelbetrieb

Allgemeine Hinweise für die Implementierung

Die Clientimplementierung ist unabhängig von einer Programmiersprache. Die Auswahl der Programmiersprache obliegt dem Anbieter des HGS.

Die Schlüssel (IDs) des Aufrufs "Gerätearten" können sich ändern. Es ist daher clientseitig sicherzustellen, dass jeweils vor dem Aufruf zur Aktualisierung eines Garantiebetrags die aktuelle ID der jeweiligen Geräteart gelesen wird.

Die HGS-Schnittstelle bietet die Möglichkeit, alle Funktionen, ohne die Implementierung einer Clientschnittstelle, in einem Web-Interface zu nutzen.

Für die Nutzung der Online-Variante der Schnittstelle ist ein grundsätzliches Verständnis von REST erforderlich, insbesondere die Differenzierung von GET und POST-Aufrufen.

Aufrufe der Schnittstelle

Alle Aufrufe setzen voraus, dass zuvor eine erfolgreiche Anmeldung mit Benutzername und Passwort ausgeführt wurde.

Das von der stiftung ear übermittelte Passwort ist ein Initialpasswort und muss zwingend geändert werden. Erst nach der Änderung des Passworts können weitere Funktionen der Schnittstelle genutzt werden.

Empfehlung: Änderung des Initialkennworts über die Webschnittstelle, wie unter Ziffer 2.1 beschrieben.

Die Anmeldung an der HGS-Schnittstelle erfolgt über die "Basic Authentication". Über die Standard Web Funktionalität (Session) wird für subsequente Aufrufe die Authentifizierung validiert.

Passwortänderung über das Web-Interface

Auf der Startseite der HGS Schnittstelle ist der Eintrag List Operations zu wählen:

Nach der Auswahl von List Operations kann die Funktion garantiebetrag/passwort ausgewählt werden:

Es folgt die Dokumentation des Aufrufs:

Nach Auswahl von Model Schema und Click to set as parameter value, kann man in dem Web Interface das Kennwort ändern:

Das alte Passwort und das neue Passwort können nun eingeben werden:

{
    "oldPassword": "string",
    "newPassword": "string"
}

Mit einem Klick auf Send werden die Parameter übermittelt und das Ergebnis des Aufrufs angezeigt:

Ermitteln der Geräteart über das Web-Interface

Diese Funktion liefert eine Liste der Gerätearten.

Wie schon in Passwortänderung über das Web-Interface beschrieben, kann die Funktion auch per Browser ausgeführt werden und liefert bspw. folgendes Ergebnis:

Übermittlung des Garantiebetrags über das Web-Interface

Analog zur Navigation, wie in Passwortänderung über das Web-Interface beschrieben ist, kann man zur Funktion send gelangen und die notwendigen Parameter von Hand in das Web-Interface eintragen.

Die notwendigen Parameter können händisch eingetragen werden und der Request kann mit dem Button Send übermittelt werden.

Die entsprechende http Antwort ist ebenfalls im Web-Interface ersichtlich.

Lesen der Garantiebeträge über das Web-Interface

Analog zur Navigation, die in Passwortänderung über das Web-Interface beschrieben ist, kann man zur Funktion /garantiebetrag/list gelangen und die notwendigen Parameter von Hand in das Web-Interface eintragen.

Der page Parameter ist ein Pflichtfeld, der Parameter herstellerInformation optional. Der Request kann mit dem Button Send gesendet werden und die entsprechende http Antwort ist ebenfalls im Web-Interface ersichtlich.