Zum Inhalt springen

Änderungen von Dokument Submission-API

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

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -1,17 +1,24 @@
1 1  ## Authentifizierung
2 2  
3 -Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
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 4  
5 -Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
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:
6 6  
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.
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*
9 9  
14 +> ***Hinweis:***
15 +> Die verwendete Authentifizierungsart ist eine [Basis-Authentifizierung](https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication).
16 +
10 10  ___
11 11  
12 12  ## Base-URL
13 13  
14 -Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:
21 +Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
15 15  `https://<Server-Name>/submission/api/v2/`
16 16  
17 17  ___
... ... @@ -22,10 +22,10 @@
22 22  
23 23  ### Übersicht
24 24  
25 -`/submission/<Mandant>/<Formularnummer>`
32 +`/submission/<Mandant>/<Formularnummer>`\
26 26  Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
27 27  
28 -```json
35 +```
29 29  [{
30 30   "transID":"AS_940000-gsh7ntqS",
31 31   "userID":"22222222-2222-0126",
... ... @@ -45,6 +45,7 @@
45 45   "submissionDate":1455801335305
46 46  }]
47 47  ```
55 +
48 48  Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
49 49  
50 50  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:
... ... @@ -52,32 +52,60 @@
52 52  1. `?status=NEW&status=READ`
53 53  2. `?status=NEW,READ`
54 54  
55 -Gültige Statuswerte sind:
63 +Gültige Statuswerte sind:
56 56  
57 -- NEW
58 -- READ
59 -- CLOSED
60 -- PRELIMINARY
61 -- HIDDEN
62 -- DELETED
65 +- NEW
66 +- READ
67 +- CLOSED
68 +- PRELIMINARY
69 +- HIDDEN
70 +- DELETED
63 63  
64 64  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.
65 65  
66 66  ### Detailauskunft
67 67  
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>`
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`
70 70  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.
71 71  
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 +
72 72  ### Statusänderung
73 73  
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:
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:
75 75  
76 -- NEW
77 -- READ
78 -- CLOSED
79 -- PRELIMINARY
80 -- HIDDEN
112 +- NEW
113 +- READ
114 +- CLOSED
115 +- PRELIMINARY
116 +- HIDDEN
81 81  - DELETED
82 82  
83 83  > ***Hinweis:***
... ... @@ -91,15 +91,15 @@
91 91  
92 92  ### Neue Nachricht erzeugen
93 93  
94 -Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
95 -`/message/<Mandant>/<Transaktions-ID>/create`
130 +Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
131 +`/message/<Mandant>/<Transaktions-ID>/create`\
96 96  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.
97 97  
98 98  ### Übersicht
99 99  
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:
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:
101 101  
102 -```json
138 +```
103 103  [{
104 104   "id":"581754a5bf962e5318d90f7b",
105 105   "transID":"AS_940000-gsh7ntqS",
... ... @@ -121,13 +121,13 @@
121 121  
122 122  ### Status
123 123  
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:
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:
125 125  
126 -- NEW
127 -- READ
128 -- CLOSED
129 -- PRELIMINARY
130 -- HIDDEN
162 +- NEW
163 +- READ
164 +- CLOSED
165 +- PRELIMINARY
166 +- HIDDEN
131 131  - DELETED
132 132  
133 133  > ***Hinweis:***
... ... @@ -141,7 +141,7 @@
141 141  
142 142  ### Hinzuzufügen
143 143  
144 -Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:
180 +Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
145 145  `/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.
146 146  
147 147  ### Übersicht
... ... @@ -152,8 +152,8 @@
152 152  
153 153  ## Abruf
154 154  
155 -Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
156 -`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.
191 +Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
192 +`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
157 157  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.
158 158  
159 159  ### Löschen
... ... @@ -160,4 +160,12 @@
160 160  
161 161  Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
162 162  
199 +___
163 163  
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 +