Wiki-Quellcode von Submission-API

Version 3.1 von MACH ProForms GmbH am 19.12.2020

version	line-number	content
1.1	1	## Authentifizierung
	2
3.1	3	Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
1.1	4
3.1	5	Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
1.1	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
3.1	14	Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
1.1	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
3.1	25	`/submission/<Mandant>/<Formularnummer>`\
1.1	26	Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
	27
3.1	28	```
1.1	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	```
3.1	48
2.1	49	Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
1.1	50
2.1	51	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:
1.1	52
2.1	53	1. `?status=NEW&status=READ`
	54	2. `?status=NEW,READ`
	55
3.1	56	Gültige Statuswerte sind:
1.1	57
3.1	58	- NEW
	59	- READ
	60	- CLOSED
	61	- PRELIMINARY
	62	- HIDDEN
	63	- DELETED
1.1	64
	65	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.
	66
	67	### Detailauskunft
	68
3.1	69	Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL um die Transaktions-ID zu ergänzen:\
	70	`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/metadata`
1.1	71	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.
	72
3.1	73	Der bis zum Release 4.60.0 gültige Aufruf mittels:\
	74	`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
	75	sollte mit der obige aufgeführten Endung ergänzt werden. Der damalige Aufruf behält bis auf Weiteres seine Gültigkeit.
	76
	77	#### PDF
	78
	79	Um ausschließlich die generierte oder befüllte PDF-Datei abzurufen, wird der Pfad mit der Endung `pdf` verwendet:\
	80	`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/pdf`
	81
	82
	83	#### XML
	84
	85	Um ausschließlich die generierte XML-Datei abzurufen, wird der Pfad mit der Endung `xml` verwendet:\
	86	`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/xml`
	87
	88	```
	89	<?xml version="1.0" encoding="UTF-8"?>
	90	<!--Sonderzeichen in Feldnamen wurden ersetzt bzw. entfernt!-->
	91	<form template="AS_940000">
	92	...
	93	</form>
	94	```
	95
	96	#### Anhänge
	97
	98	Um alle Dateianhänge in einem Zip-Archiv abzurufen, wird der Pfad mit der Endung `zip` verwendet:\
	99	`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/zip`
	100
1.1	101	### Statusänderung
	102
3.1	103	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:
1.1	104
3.1	105	- NEW
	106	- READ
	107	- CLOSED
	108	- PRELIMINARY
	109	- HIDDEN
1.1	110	- DELETED
	111
3.1	112	> *Hinweis:*\
1.1	113	> Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
	114
	115	___
	116
	117	## Nachricht
	118
	119	Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.
	120
	121	### Neue Nachricht erzeugen
	122
3.1	123	Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
	124	`/message/<Mandant>/<Transaktions-ID>/create`\
1.1	125	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.
	126
	127	### Übersicht
	128
3.1	129	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:
1.1	130
3.1	131	```
1.1	132	[{
	133	"id":"581754a5bf962e5318d90f7b",
	134	"transID":"AS_940000-gsh7ntqS",
	135	"changedDate":1477924005742,
	136	"status":"NEW",
	137	"text":null,
	138	"size":0,
	139	"files":[]
	140	}]
	141	```
	142
	143	### Details
	144
	145	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>`
	146
	147	### Text
	148
	149	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.
	150
	151	### Status
	152
3.1	153	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:
1.1	154
3.1	155	- NEW
	156	- READ
	157	- CLOSED
	158	- PRELIMINARY
	159	- HIDDEN
1.1	160	- DELETED
	161
3.1	162	> *Hinweis:*\
1.1	163	> Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
	164
	165	___
	166
	167	## Nachrichtenanhang
	168
	169	Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.
	170
	171	### Hinzuzufügen
	172
3.1	173	Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
1.1	174	`/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.
	175
	176	### Übersicht
	177
	178	Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.
	179
	180	___
	181
	182	## Abruf
	183
3.1	184	Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
	185	`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
1.1	186	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.
	187
	188	### Löschen
	189
	190	Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.