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 MACH formsolutions mit der Error-API eine Lösung bereit, mit der sämtliche Fehler, die standardmäßig auf eine Error-URL weitergeleitet werden, auflistet und dem Sachbearbeiter ersichtlich gemacht werden können.
Die Architektur beruht auf dem REST-Standard. Wie bei allen von MACH formsolutions angebotenen Schnittstellen unterliegt auch diese einem Authentifizierungskonzept.
Die ausgelesenen Ergebnisdaten werden im JSON-Format ausgegeben.

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).
• Es muss für die Authentifizierung die Mandantennummer und der API-Key vorhanden sein.

Verwendung der Schnittstelle

Um die Schnittstelle verwenden zu können, ist es notwendig eine "errorUrl" wie in Rücksprung-URLs beschrieben beim Assistentenstart 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. Weitere Verwendungsmöglichkeiten finden Sie in unserer Swagger-Dokumentation.

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

Authentifizierung

Um die Schnittstelle verwenden zu können, muss eine Authentifizierung vorgenommen werden. Für diese sind die Mandantennummer und ein API-Key notwendig, wobei die Mandantennummer als Benutzername und der API-Key als Passwort gilt. Die verwendete Authentifizierungsart ist eine Basis-Authentifizierung.

Einen API-Key können Sie beim Betreiber des Formularservers beantragen.

Beispielanwendung (Swagger-Dokumentation)

Auf dem Formularserver ist mit der Swagger-Anwendung eine übersichtliche Darstellung und technische Dokumentation der Schnittstelle verfügbar. Mit dieser Anwendung kann die Funktionalität auch getestet werden.

Die Adresse der Swagger-Anwendung der Error-API lautet < Formularserveradresse >/error/api/swagger-ui.html
Um die Anwendung aufzurufen, setzen Sie die Adresse des jeweiligen Formularservers ein.

Für Funktionstests sind gültige Authentifizierungsdaten für den jeweiligen Server erforderlich (Mandantennummer und API-Key).