Zum Inhalt springen

Wiki-Quellcode von Submission-API

Version 2.1 von MACH formsolutions am 08.10.2020
Zeige letzte Bearbeiter
1 ## Authentifizierung
2
3 Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
4
5 Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
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.
9
10 ___
11
12 ## Base-URL
13
14 Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:
15 `https://<Server-Name>/submission/api/v2/`
16
17 ___
18
19 ## Einreichungen
20
21 Unter dem `submission`-Endpunkt lassen sich Informationen zu eingegangenen Formularen abrufen. Zusätzlich kann Bearbeitungsstatus zurückgemeldet werden.
22
23 ### Übersicht
24
25 `/submission/<Mandant>/<Formularnummer>`
26 Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
27
28 ```json
29 [{
30 "transID":"AS_940000-gsh7ntqS",
31 "userID":"22222222-2222-0126",
32 "identifier":"AS_940000",
33 "applicantName":"Mustermann",
34 "applicantEMail":null,
35 "status":"NEW",
36 "options": {
37 "submissionType":"REGULAR",
38 "paymentType":"NONE",
39 "npa":false
40 },
41 "payload":null,
42 "pdf":null,
43 "xml":null,
44 "attachments":null,
45 "submissionDate":1455801335305
46 }]
47 ```
48 Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
49
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:
51
52 1. `?status=NEW&status=READ`
53 2. `?status=NEW,READ`
54
55 Gültige Statuswerte sind:
56
57 - NEW
58 - READ
59 - CLOSED
60 - PRELIMINARY
61 - HIDDEN
62 - DELETED
63
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
66 ### Detailauskunft
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>`
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
72 ### Statusänderung
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:
75
76 - NEW
77 - READ
78 - CLOSED
79 - PRELIMINARY
80 - HIDDEN
81 - DELETED
82
83 > ***Hinweis:***
84 > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
85
86 ___
87
88 ## Nachricht
89
90 Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.
91
92 ### Neue Nachricht erzeugen
93
94 Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
95 `/message/<Mandant>/<Transaktions-ID>/create`
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
98 ### Übersicht
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:
101
102 ```json
103 [{
104 "id":"581754a5bf962e5318d90f7b",
105 "transID":"AS_940000-gsh7ntqS",
106 "changedDate":1477924005742,
107 "status":"NEW",
108 "text":null,
109 "size":0,
110 "files":[]
111 }]
112 ```
113
114 ### Details
115
116 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>`
117
118 ### Text
119
120 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.
121
122 ### Status
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:
125
126 - NEW
127 - READ
128 - CLOSED
129 - PRELIMINARY
130 - HIDDEN
131 - DELETED
132
133 > ***Hinweis:***
134 > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
135
136 ___
137
138 ## Nachrichtenanhang
139
140 Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.
141
142 ### Hinzuzufügen
143
144 Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:
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
147 ### Übersicht
148
149 Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.
150
151 ___
152
153 ## Abruf
154
155 Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
156 `/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.
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
159 ### Löschen
160
161 Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.