Error-API

Allgemeines

Während des Antragsprozesses kann der Assistent auf einen Fehler laufen, welcher nicht unbedingt erwartet wird. Um die genaue Fehlerursache festzustellen, musste bisher in jedem Fall der Administrator des Formularservers kontaktiert werden. Damit dies künftig nicht mehr notwendig ist, stellt Form-Solutions mit der Error-API eine Lösung bereit, welche sämtliche Fehler, die standardmäßig auf eine error-URL weitergeleitet werden, auflistet und dem Sachbearbeiter ersichtlich macht.

Voraussetzungen

Um die Error-API nutzen zu können sind folgende Voraussetzungen zu erfüllen:

• Es muss eine "errorUrl" beim Start des Assistenten mitgegeben werden (siehe hierzu "Rücksprung-URLs")
• Der Formularserver benötigt mindestens das Release mit der Version 4.57.0
• Es muss für die Authentifizierung die Mandantennummer und der API-Key vorhanden sein.

Verwenden der Schnittstelle

Um die Schnittstelle verwenden zu können, ist es notwendig eine errorUrl wie in "Rücksprung-URLs" beschrieben beim Assistenten start zu übergeben. Somit wird in allen Fehlerfällen, bei denen während des Ausfüllens des Assistenten oder bei der Einreichung auf die hinterlegte "errorUrl" weitergeleitet wird, künftig ein Parameter "errorId" an die URL angehängt. Der Wert des neuen Parameters gibt die ID an, mit welcher der Datensatz aus der Schnittstelle ausgelesen werden kann.

Beispiel nach Weiterleitung auf die errorUrl:
https://www.testurl.de?errorId=5f60c6da8110c14fc9cfa508

Einstiegspunkt

Um den Parameter aufzulösen, stellt Form-Solutions eine Schnittstelle bereit, über die die zugrunde liegenden Informationen der angegebenen "errorId" ausgelesen werden können. Die Schnittstelle erfüllt den REST-Standard und ist unter folgendem Basispfad erreichbar:

Endpunkte

Anhand der anzugebenden Endpunkte kann die Schnittstelle mit folgender Ressource umgehen:

Beschreibung: Der oben aufgeführte Endpunkt liest den angefallenen Fehler mit der entsprechenden "errorId" aus der Datenbank aus.

Authentifizierung

Um die Schnittstelle verwenden zu können, muss sich der Benutzer mit Hilfe einer Basis-Authentifizierung anmelden. Hierbei dient die entsprechende Mandantennummer als Benutzername und der dafür hinterlegte API-Schlüssel als Passwort. Sollten die benötigten Informationen zum Zeitpunkt der Nutzung noch nicht vorliegen, so können diese beim Administrator des Formualarservers angefragt werden.

Ausgabe im JSON-Format

Die zurückgelieferten Daten der Schnittstelle werden im JSON-Format ausgeliefert. Um die Bedeutung der einzelnen Attribute einzusehen werden diese hier erläutert.

Beispielanwendung

Um die Schnittstelle beispielhaft bedienen zu können, wird eine Demoanwendung unter folgender URL bereitgestellt: https://vertrieb.form-solutions.de/error/api/swagger-ui.html

Ebenso steht dem Anwender mit dieser Beispielanwendung eine technische Dokumentation bereit, welche die einzelnen Ressourcen detaillierter beschreibt.