Zum Inhalt springen

Wiki-Quellcode von Error-API

Version 1.1 von MACH ProForms GmbH am 08.10.2020
Zeige letzte Bearbeiter
1 ## Allgemeines
2
3 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.
4
5 ___
6
7 ## Voraussetzungen
8
9 Um die Error-API nutzen zu können sind folgende Voraussetzungen zu erfüllen:
10
11 - Es muss eine "errorUrl" beim Start des Assistenten mitgegeben werden (siehe hierzu "[[Rücksprung-URLs|Main.03_Steuerungsprozess.03_Portalintegration]]")
12 - Der Formularserver benötigt mindestens das [Release](https://wiki.form-solutions.de/wiki/docwiki/view/Main/13_Release-Notes/) mit der Version 4.57.0
13 - Es muss für die Authentifizierung die Mandantennummer und der API-Key vorhanden sein.
14
15 ___
16
17 ## Verwenden der Schnittstelle
18
19 Um die Schnittstelle verwenden zu können, ist es notwendig eine errorUrl wie in "[[Rücksprung-URLs|Main.03_Steuerungsprozess.03_Portalintegration]]" 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.
20
21 > Beispiel nach Weiterleitung auf die errorUrl: </br>
22 > https://www.testurl.de?errorId=5f60c6da8110c14fc9cfa508
23
24 ### Einstiegspunkt
25
26 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:
27
28 ```javascript
29 Basispfad:
30 https://<server-name>/error/api/
31 ```
32
33 ## Endpunkte
34
35 Anhand der anzugebenden Endpunkte kann die Schnittstelle mit folgender Ressource umgehen:
36
37 ```javascript
38 Endpunkt: /errors/<errorId>
39
40 Pfadbeispiel:
41 https://<server-name>/error/api/errors/5f3ce45444a2a03c3167d4a0
42 ```
43
44 *Beschreibung: Der oben aufgeführte Endpunkt liest den angefallenen Fehler mit der entsprechenden "errorId" aus der Datenbank aus.*
45
46 ### Authentifizierung
47
48 Um die Schnittstelle verwenden zu können, muss sich der Benutzer mit Hilfe einer [Basis-Authentifizierung](https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication) 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.
49
50 ### Ausgabe im JSON-Format
51
52 Die zurückgelieferten Daten der Schnittstelle werden im JSON-Format ausgeliefert. Um die Bedeutung der einzelnen Attribute einzusehen werden diese [[hier|Main.02_FSSchnittstellen.04_ErrorAPI.01_Resources]] erläutert.
53
54 ### Beispielanwendung
55
56 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
57
58 Ebenso steht dem Anwender mit dieser Beispielanwendung eine technische Dokumentation bereit, welche die einzelnen Ressourcen detaillierter beschreibt.