Zum Inhalt springen

Änderungen von Dokument Submission-API

Zuletzt geändert von MACH ProForms GmbH am 25.06.2024
Von Version 1.1
bearbeitet von MACH ProForms GmbH
am 07.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",
... ... @@ -46,37 +46,70 @@
46 46  }]
47 47  ```
48 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.
49 +Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
50 50  
51 -Gültige Statuswerte sind:
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:
52 52  
53 -- NEW
54 -- READ
55 -- CLOSED
56 -- PRELIMINARY
57 -- HIDDEN
58 -- DELETED
53 +1. `?status=NEW&status=READ`
54 +2. `?status=NEW,READ`
59 59  
56 +Gültige Statuswerte sind:
57 +
58 +- NEW
59 +- READ
60 +- CLOSED
61 +- PRELIMINARY
62 +- HIDDEN
63 +- DELETED
64 +
60 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 61  
62 62  ### Detailauskunft
63 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>`
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`
66 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 67  
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 +
68 68  ### Statusänderung
69 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:
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:
71 71  
72 -- NEW
73 -- READ
74 -- CLOSED
75 -- PRELIMINARY
76 -- HIDDEN
105 +- NEW
106 +- READ
107 +- CLOSED
108 +- PRELIMINARY
109 +- HIDDEN
77 77  - DELETED
78 78  
79 -> ***Hinweis:***
112 +> ***Hinweis:***\
80 80  > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
81 81  
82 82  ___
... ... @@ -87,15 +87,15 @@
87 87  
88 88  ### Neue Nachricht erzeugen
89 89  
90 -Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
91 -`/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`\
92 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 93  
94 94  ### Übersicht
95 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:
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:
97 97  
98 -```json
131 +```
99 99  [{
100 100   "id":"581754a5bf962e5318d90f7b",
101 101   "transID":"AS_940000-gsh7ntqS",
... ... @@ -117,16 +117,16 @@
117 117  
118 118  ### Status
119 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:
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:
121 121  
122 -- NEW
123 -- READ
124 -- CLOSED
125 -- PRELIMINARY
126 -- HIDDEN
155 +- NEW
156 +- READ
157 +- CLOSED
158 +- PRELIMINARY
159 +- HIDDEN
127 127  - DELETED
128 128  
129 -> ***Hinweis:***
162 +> ***Hinweis:***\
130 130  > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
131 131  
132 132  ___
... ... @@ -137,7 +137,7 @@
137 137  
138 138  ### Hinzuzufügen
139 139  
140 -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:\
141 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 142  
143 143  ### Übersicht
... ... @@ -148,12 +148,10 @@
148 148  
149 149  ## Abruf
150 150  
151 -Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
152 -`/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>`.\
153 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 154  
155 155  ### Löschen
156 156  
157 157  Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
158 -
159 -