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 3.1
bearbeitet von MACH ProForms GmbH
am 19.12.2020
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -1,8 +1,8 @@
1 1  ## Authentifizierung
2 2  
3 -Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
3 +Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
4 4  
5 -Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
5 +Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
6 6  
7 7  - Als Benutzername ist die Nummer des Mandanten zu verwenden, in dessen Namen der Aufruf durchgeführt wird.
8 8  - Als Passwort dient ein CMS-Key wie er auch an anderen Stellen im System zur Anwendung kommt.
... ... @@ -11,7 +11,7 @@
11 11  
12 12  ## Base-URL
13 13  
14 -Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:
14 +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>`
25 +`/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
28 +```
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  ```
48 +
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,35 +52,63 @@
52 52  1. `?status=NEW&status=READ`
53 53  2. `?status=NEW,READ`
54 54  
55 -Gültige Statuswerte sind:
56 +Gültige Statuswerte sind:
56 56  
57 -- NEW
58 -- READ
59 -- CLOSED
60 -- PRELIMINARY
61 -- HIDDEN
62 -- DELETED
58 +- NEW
59 +- READ
60 +- CLOSED
61 +- PRELIMINARY
62 +- HIDDEN
63 +- 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>`
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`
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  
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 +
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:
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:
75 75  
76 -- NEW
77 -- READ
78 -- CLOSED
79 -- PRELIMINARY
80 -- HIDDEN
105 +- NEW
106 +- READ
107 +- CLOSED
108 +- PRELIMINARY
109 +- HIDDEN
81 81  - DELETED
82 82  
83 -> ***Hinweis:***
112 +> ***Hinweis:***\
84 84  > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
85 85  
86 86  ___
... ... @@ -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`
123 +Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
124 +`/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:
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:
101 101  
102 -```json
131 +```
103 103  [{
104 104   "id":"581754a5bf962e5318d90f7b",
105 105   "transID":"AS_940000-gsh7ntqS",
... ... @@ -121,16 +121,16 @@
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:
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:
125 125  
126 -- NEW
127 -- READ
128 -- CLOSED
129 -- PRELIMINARY
130 -- HIDDEN
155 +- NEW
156 +- READ
157 +- CLOSED
158 +- PRELIMINARY
159 +- HIDDEN
131 131  - DELETED
132 132  
133 -> ***Hinweis:***
162 +> ***Hinweis:***\
134 134  > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
135 135  
136 136  ___
... ... @@ -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:
173 +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,12 +152,10 @@
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>`.
184 +Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
185 +`/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 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 -
163 -