Zum Inhalt springen

Wiki-Quellcode von Submission-API

Version 5.1 von MACH ProForms GmbH am 15.02.2021
Zeige letzte Bearbeiter
1 ## Authentifizierung
2
3 Um die Schnittstelle verwenden zu können, muss eine Authentifizierung vorgenommen werden. Für diese ist die Mandantennummer und der dafür hinterlegte API-Schlüssel notwendig, wobei die Mandantennummer als Benutzername und der API-Schlüssel als Passwort gilt. Sollte noch kein passender API-Schlüssel vorliegen, kann dieser beim Administrator des Fomularservers beantragt werden.
4
5 Mit dem folgenden Link wird auf eine Oberfläche weitergeleitet, bei der die Schnittstelle auf ihre Funktionalität getestet werden kann.
6 Die erforderlichen Authentifizierungsdaten dienen zu Demonstrationszwecken und lauten wie folgt:
7
8 *Beispiel: [https://vertrieb.form-solutions.de/submission/swagger-ui/index.html](https://vertrieb.form-solutions.de/submission/swagger-ui/index.html)*
9 <br>
10 *Mandantennummer: 88888888-8888*
11 <br>
12 *API-Schlüssel: npcnqwpefwAFWFAFAFqwcqcqwc23rf23rzhbnerg*
13
14 > ***Hinweis:***
15 > Die verwendete Authentifizierungsart ist eine [Basis-Authentifizierung](https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication).
16
17 ___
18
19 ## Base-URL
20
21 Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
22 `https://<Server-Name>/submission/api/v2/`
23
24 ___
25
26 ## Einreichungen
27
28 Unter dem `submission`-Endpunkt lassen sich Informationen zu eingegangenen Formularen abrufen. Zusätzlich kann Bearbeitungsstatus zurückgemeldet werden.
29
30 ### Übersicht
31
32 `/submission/<Mandant>/<Formularnummer>`\
33 Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
34
35 ```
36 [{
37 "transID":"AS_940000-gsh7ntqS",
38 "userID":"22222222-2222-0126",
39 "identifier":"AS_940000",
40 "applicantName":"Mustermann",
41 "applicantEMail":null,
42 "status":"NEW",
43 "options": {
44 "submissionType":"REGULAR",
45 "paymentType":"NONE",
46 "npa":false
47 },
48 "payload":null,
49 "pdf":null,
50 "xml":null,
51 "attachments":null,
52 "submissionDate":1455801335305
53 }]
54 ```
55
56 Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
57
58 Die Anzeige kann eingeschränkt werden, indem als Abfrage-Parameter der gewünschte Status mit angegeben wird. So kann z. B. mittels `?status=NEW` auf neue Anträge eingeschränkt werden. Ebenso ist es möglich mehrere Stati gleichzeitig für die Filterung anzugeben. Hierzu stehen zwei Möglichkeiten zur Verfügung:
59
60 1. `?status=NEW&status=READ`
61 2. `?status=NEW,READ`
62
63 Gültige Statuswerte sind:
64
65 - NEW
66 - READ
67 - CLOSED
68 - PRELIMINARY
69 - HIDDEN
70 - DELETED
71
72 Zusätzlich kann der Abfragezeitraum über die Angabe eines `Last-Modified`-Headers eingeschränkt werden. Dabei handelt es sich um den Einreichezeitpunkt, nicht die letzte Statusänderung.
73
74 ### Detailauskunft
75
76 Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL um die Transaktions-ID zu ergänzen:\
77 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/metadata`
78 Das Ergebnis besitzt dieselbe Struktur wie bei der Übersichtsabfrage. Allerdings enthält das Attribut `payload` die kompletten Assistentendaten als eingebettetes JSON-Element und die Attribute pdf, xml und attachments enthalten die entsprechenden Einreichedaten.
79
80 Der bis zum Release 4.60.0 gültige Aufruf mittels:\
81 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
82 sollte mit der obige aufgeführten Endung ergänzt werden. Der damalige Aufruf behält bis auf Weiteres seine Gültigkeit.
83
84 #### PDF
85
86 Um ausschließlich die generierte oder befüllte PDF-Datei abzurufen, wird der Pfad mit der Endung `pdf` verwendet:\
87 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/pdf`
88
89
90 #### XML
91
92 Um ausschließlich die generierte XML-Datei abzurufen, wird der Pfad mit der Endung `xml` verwendet:\
93 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/xml`
94
95 ```
96 <?xml version="1.0" encoding="UTF-8"?>
97 <!--Sonderzeichen in Feldnamen wurden ersetzt bzw. entfernt!-->
98 <form template="AS_940000">
99 ...
100 </form>
101 ```
102
103 #### Anhänge
104
105 Um alle Dateianhänge in einem Zip-Archiv abzurufen, wird der Pfad mit der Endung `zip` verwendet:\
106 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/zip`
107
108 ### Statusänderung
109
110 Um den Bearbeitungsstatus eines Vorgangs kenntlich zu machen, kann der Status einer Transaktion geändert werden. Dazu wird an die Detail-URL ein POST gesendet mit dem zusätzlichen Parameter `setStatus`. Gültige Statuswerte sind:
111
112 - NEW
113 - READ
114 - CLOSED
115 - PRELIMINARY
116 - HIDDEN
117 - DELETED
118
119 > ***Hinweis:***
120 > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
121
122 ___
123
124 ## Nachricht
125
126 Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.
127
128 ### Neue Nachricht erzeugen
129
130 Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
131 `/message/<Mandant>/<Transaktions-ID>/create`\
132 Als Rückgabewert erhält man lediglich die Nachrichten-ID des neuen Eintrags. Enthält der POST einen Body, so wird dieser als Nachrichtentext verwendet.
133
134 ### Übersicht
135
136 Eine Übersicht der Nachrichten zu einem einzelnen Vorgang können über `/message/<Mandant>/<Transaktions-ID>` abgerufen werden. Als Antwort erhält man ein JSON-Array in folgender Form:
137
138 ```
139 [{
140 "id":"581754a5bf962e5318d90f7b",
141 "transID":"AS_940000-gsh7ntqS",
142 "changedDate":1477924005742,
143 "status":"NEW",
144 "text":null,
145 "size":0,
146 "files":[]
147 }]
148 ```
149
150 ### Details
151
152 Die Details zu einer einzelnen Nachricht inkl. Nachrichtentext und Verweisen auf hinterlegte Dateien können über eine URL der folgenden Form abgerufen werden: `/message/<Mandant>/<Transaktions-ID>/<Nachrichten-ID>`
153
154 ### Text
155
156 Soll der Text einer Nachricht nachträglich hinzugefügt oder geändert werden, kann dies über einen Post an die Detail-URL bewerkstelligt werden. Der neue Text ist dabei als POST-Body zu übergeben.
157
158 ### Status
159
160 Auch Nachrichten besitzen ein Status-Attribut. Dieses kann dadurch geändert werden, dass man eine POST-Nachricht an die Detail-URL mit einem zusätzlichen `setStatus`-Parameter sendet. Gültige Statuswerte sind:
161
162 - NEW
163 - READ
164 - CLOSED
165 - PRELIMINARY
166 - HIDDEN
167 - DELETED
168
169 > ***Hinweis:***
170 > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
171
172 ___
173
174 ## Nachrichtenanhang
175
176 Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.
177
178 ### Hinzuzufügen
179
180 Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
181 `/file/<Mandant>/<Nachtrichten-ID>/add` als POST gesendet werden. Der Dateiname muss dabei als Parameter `filename` übergeben werden. Der Contenttype wird dem entsprechenden HTTP-Header entnommen.
182
183 ### Übersicht
184
185 Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.
186
187 ___
188
189 ## Abruf
190
191 Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
192 `/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
193 Um den Inhalt abzurufen, muss die URL nur um `/data` ergänzt werden. Der Contenttype wird dabei auf den Wert gesetzt, der beim Hochladen verwendet wurde.
194
195 ### Löschen
196
197 Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
198
199 ___
200
201 ### Beispielanwendung
202
203 Um die Schnittstelle beispielhaft bedienen zu können, wird eine Demoanwendung unter folgender URL bereitgestellt: https://vertrieb.form-solutions.de/submission/swagger-ui/index.html
204
205 Ebenso steht dem Anwender mit dieser Beispielanwendung eine technische Dokumentation bereit, welche die einzelnen Ressourcen detaillierter beschreibt.