Wiki-Quellcode von Submission-API

Version 5.1 von MACH ProForms GmbH am 15.02.2021

version	line-number	content
1.1	1	## Authentifizierung
	2
5.1	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.
1.1	4
5.1	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:
1.1	7
5.1	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
1.1	13
5.1	14	> *Hinweis:*
	15	> Die verwendete Authentifizierungsart ist eine [Basis-Authentifizierung](https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication).
	16
1.1	17	___
	18
	19	## Base-URL
	20
3.1	21	Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
1.1	22	`https://<Server-Name>/submission/api/v2/`
	23
	24	___
	25
	26	## Einreichungen
	27
	28	Unter dem `submission`-Endpunkt lassen sich Informationen zu eingegangenen Formularen abrufen. Zusätzlich kann Bearbeitungsstatus zurückgemeldet werden.
	29
	30	### Übersicht
	31
3.1	32	`/submission/<Mandant>/<Formularnummer>`\
1.1	33	Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
	34
3.1	35	```
1.1	36	[{
	37	"transID":"AS_940000-gsh7ntqS",
	38	"userID":"22222222-2222-0126",
	39	"identifier":"AS_940000",
	40	"applicantName":"Mustermann",
	41	"applicantEMail":null,
	42	"status":"NEW",
	43	"options": {
	44	"submissionType":"REGULAR",
	45	"paymentType":"NONE",
	46	"npa":false
	47	},
	48	"payload":null,
	49	"pdf":null,
	50	"xml":null,
	51	"attachments":null,
	52	"submissionDate":1455801335305
	53	}]
	54	```
3.1	55
2.1	56	Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
1.1	57
2.1	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:
1.1	59
2.1	60	1. `?status=NEW&status=READ`
	61	2. `?status=NEW,READ`
	62
3.1	63	Gültige Statuswerte sind:
1.1	64
3.1	65	- NEW
	66	- READ
	67	- CLOSED
	68	- PRELIMINARY
	69	- HIDDEN
	70	- DELETED
1.1	71
	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
	74	### Detailauskunft
	75
3.1	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`
1.1	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
3.1	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
1.1	108	### Statusänderung
	109
3.1	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:
1.1	111
3.1	112	- NEW
	113	- READ
	114	- CLOSED
	115	- PRELIMINARY
	116	- HIDDEN
1.1	117	- DELETED
	118
4.1	119	> *Hinweis:*
1.1	120	> Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
	121
	122	___
	123
	124	## Nachricht
	125
	126	Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.
	127
	128	### Neue Nachricht erzeugen
	129
3.1	130	Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
	131	`/message/<Mandant>/<Transaktions-ID>/create`\
1.1	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
	134	### Übersicht
	135
3.1	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:
1.1	137
3.1	138	```
1.1	139	[{
	140	"id":"581754a5bf962e5318d90f7b",
	141	"transID":"AS_940000-gsh7ntqS",
	142	"changedDate":1477924005742,
	143	"status":"NEW",
	144	"text":null,
	145	"size":0,
	146	"files":[]
	147	}]
	148	```
	149
	150	### Details
	151
	152	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>`
	153
	154	### Text
	155
	156	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.
	157
	158	### Status
	159
3.1	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:
1.1	161
3.1	162	- NEW
	163	- READ
	164	- CLOSED
	165	- PRELIMINARY
	166	- HIDDEN
1.1	167	- DELETED
	168
4.1	169	> *Hinweis:*
1.1	170	> Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
	171
	172	___
	173
	174	## Nachrichtenanhang
	175
	176	Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.
	177
	178	### Hinzuzufügen
	179
3.1	180	Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
1.1	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
	183	### Übersicht
	184
	185	Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.
	186
	187	___
	188
	189	## Abruf
	190
3.1	191	Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
	192	`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
1.1	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
	195	### Löschen
	196
	197	Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
5.1	198
	199	___
	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