Zum Inhalt springen

Änderungen von Dokument Submission-API

Zuletzt geändert von MACH ProForms GmbH am 25.06.2024
Von Version 5.1
bearbeitet von MACH ProForms GmbH
am 15.02.2021
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version 2.1
bearbeitet von MACH ProForms GmbH
am 08.10.2020
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -1,24 +1,17 @@
1 1  ## Authentifizierung
2 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.
3 +Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
4 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:
5 +Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
7 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*
7 +- Als Benutzername ist die Nummer des Mandanten zu verwenden, in dessen Namen der Aufruf durchgeführt wird.
8 +- Als Passwort dient ein CMS-Key wie er auch an anderen Stellen im System zur Anwendung kommt.
13 13  
14 -> ***Hinweis:***
15 -> Die verwendete Authentifizierungsart ist eine [Basis-Authentifizierung](https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication).
16 -
17 17  ___
18 18  
19 19  ## Base-URL
20 20  
21 -Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
14 +Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:
22 22  `https://<Server-Name>/submission/api/v2/`
23 23  
24 24  ___
... ... @@ -29,10 +29,10 @@
29 29  
30 30  ### Übersicht
31 31  
32 -`/submission/<Mandant>/<Formularnummer>`\
25 +`/submission/<Mandant>/<Formularnummer>`
33 33  Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
34 34  
35 -```
28 +```json
36 36  [{
37 37   "transID":"AS_940000-gsh7ntqS",
38 38   "userID":"22222222-2222-0126",
... ... @@ -52,7 +52,6 @@
52 52   "submissionDate":1455801335305
53 53  }]
54 54  ```
55 -
56 56  Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
57 57  
58 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:
... ... @@ -60,60 +60,32 @@
60 60  1. `?status=NEW&status=READ`
61 61  2. `?status=NEW,READ`
62 62  
63 -Gültige Statuswerte sind:
55 +Gültige Statuswerte sind:
64 64  
65 -- NEW
66 -- READ
67 -- CLOSED
68 -- PRELIMINARY
69 -- HIDDEN
70 -- DELETED
57 +- NEW
58 +- READ
59 +- CLOSED
60 +- PRELIMINARY
61 +- HIDDEN
62 +- DELETED
71 71  
72 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 73  
74 74  ### Detailauskunft
75 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`
68 +Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL lediglich um die Transaktions-ID zu ergänzen:
69 +`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
78 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 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 108  ### Statusänderung
109 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:
74 +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 111  
112 -- NEW
113 -- READ
114 -- CLOSED
115 -- PRELIMINARY
116 -- HIDDEN
76 +- NEW
77 +- READ
78 +- CLOSED
79 +- PRELIMINARY
80 +- HIDDEN
117 117  - DELETED
118 118  
119 119  > ***Hinweis:***
... ... @@ -127,15 +127,15 @@
127 127  
128 128  ### Neue Nachricht erzeugen
129 129  
130 -Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
131 -`/message/<Mandant>/<Transaktions-ID>/create`\
94 +Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
95 +`/message/<Mandant>/<Transaktions-ID>/create`
132 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 133  
134 134  ### Übersicht
135 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:
100 +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 137  
138 -```
102 +```json
139 139  [{
140 140   "id":"581754a5bf962e5318d90f7b",
141 141   "transID":"AS_940000-gsh7ntqS",
... ... @@ -157,13 +157,13 @@
157 157  
158 158  ### Status
159 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:
124 +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 161  
162 -- NEW
163 -- READ
164 -- CLOSED
165 -- PRELIMINARY
166 -- HIDDEN
126 +- NEW
127 +- READ
128 +- CLOSED
129 +- PRELIMINARY
130 +- HIDDEN
167 167  - DELETED
168 168  
169 169  > ***Hinweis:***
... ... @@ -177,7 +177,7 @@
177 177  
178 178  ### Hinzuzufügen
179 179  
180 -Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
144 +Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:
181 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 182  
183 183  ### Übersicht
... ... @@ -188,8 +188,8 @@
188 188  
189 189  ## Abruf
190 190  
191 -Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
192 -`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
155 +Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
156 +`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.
193 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 194  
195 195  ### Löschen
... ... @@ -196,12 +196,4 @@
196 196  
197 197  Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
198 198  
199 -___
200 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.
206 -
207 -