Zum Inhalt springen

Wiki-Quellcode von Submission-API

Version 1.1 von MACH ProForms GmbH am 07.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
49 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.
50
51 Gültige Statuswerte sind:
52
53 - NEW
54 - READ
55 - CLOSED
56 - PRELIMINARY
57 - HIDDEN
58 - DELETED
59
60 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.
61
62 ### Detailauskunft
63
64 Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL lediglich um die Transaktions-ID zu ergänzen:
65 `/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
66 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.
67
68 ### Statusänderung
69
70 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:
71
72 - NEW
73 - READ
74 - CLOSED
75 - PRELIMINARY
76 - HIDDEN
77 - DELETED
78
79 > ***Hinweis:***
80 > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
81
82 ___
83
84 ## Nachricht
85
86 Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.
87
88 ### Neue Nachricht erzeugen
89
90 Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
91 `/message/<Mandant>/<Transaktions-ID>/create`
92 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.
93
94 ### Übersicht
95
96 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:
97
98 ```json
99 [{
100 "id":"581754a5bf962e5318d90f7b",
101 "transID":"AS_940000-gsh7ntqS",
102 "changedDate":1477924005742,
103 "status":"NEW",
104 "text":null,
105 "size":0,
106 "files":[]
107 }]
108 ```
109
110 ### Details
111
112 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>`
113
114 ### Text
115
116 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.
117
118 ### Status
119
120 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:
121
122 - NEW
123 - READ
124 - CLOSED
125 - PRELIMINARY
126 - HIDDEN
127 - DELETED
128
129 > ***Hinweis:***
130 > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
131
132 ___
133
134 ## Nachrichtenanhang
135
136 Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.
137
138 ### Hinzuzufügen
139
140 Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:
141 `/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.
142
143 ### Übersicht
144
145 Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.
146
147 ___
148
149 ## Abruf
150
151 Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
152 `/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.
153 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.
154
155 ### Löschen
156
157 Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.