Änderungen von Dokument Submission-API

Zuletzt geändert von MACH ProForms GmbH am 25.06.2024

Von 4.1 nach 3.1

Von Version 3.1

bearbeitet von MACH ProForms GmbH
am 19.12.2020

Änderungskommentar: Es gibt keinen Kommentar für diese Version

Auf Version 1.1

bearbeitet von MACH ProForms GmbH
am 07.10.2020

Änderungskommentar: Es gibt keinen Kommentar für diese Version

Rohform
Im Layout

Zusammenfassung

Seiteneigenschaften (1 geändert, 0 hinzugefügt, 0 gelöscht)

Details

Seiteneigenschaften

Inhalt

@@ -1,8 +1,8 @@
  ## Authentifizierung
--Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
++Im Folgenden aufgeführte Schnittstelle erfordert eine Authentifizierung der ausführenden Stelle.
--Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
++Hierbei kommt eine preemptive Basic-Authentifizierung zum Einsatz.
  - Als Benutzername ist die Nummer des Mandanten zu verwenden, in dessen Namen der Aufruf durchgeführt wird.
  - Als Passwort dient ein CMS-Key wie er auch an anderen Stellen im System zur Anwendung kommt.
@@ -11,7 +11,7 @@
  ## Base-URL
--Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:\
++Für alle URL-Endpunkte ist ein Prefix im folgenden Stil zu verwenden:
  `https://<Server-Name>/submission/api/v2/`
  ___
@@ -22,10 +22,10 @@
  ### Übersicht
--`/submission/<Mandant>/<Formularnummer>`\
++`/submission/<Mandant>/<Formularnummer>`
  Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.
--```
++```json
  [{
    "transID":"AS_940000-gsh7ntqS",
    "userID":"22222222-2222-0126",
@@ -46,70 +46,37 @@
  }]
  ```
--Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.
++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.
--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:
++Gültige Statuswerte sind:
--1. `?status=NEW&status=READ`
--2. `?status=NEW,READ`
++- NEW
++- READ
++- CLOSED
++- PRELIMINARY
++- HIDDEN
++- DELETED
--Gültige Statuswerte sind:
--
--- NEW
--- READ
--- CLOSED
--- PRELIMINARY
--- HIDDEN
--- DELETED
--
  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.
  ### Detailauskunft
--Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL um die Transaktions-ID zu ergänzen:\
--`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/metadata`
++Sollen alle Daten eines einzelnen Formulareingangs abgerufen werden, ist die URL lediglich um die Transaktions-ID zu ergänzen:
++`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
  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.
--Der bis zum Release 4.60.0 gültige Aufruf mittels:\
--`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>`
--sollte mit der obige aufgeführten Endung ergänzt werden. Der damalige Aufruf behält bis auf Weiteres seine Gültigkeit.
--
--#### PDF
--
--Um ausschließlich die generierte oder befüllte PDF-Datei abzurufen, wird der Pfad mit der Endung `pdf` verwendet:\
--`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/pdf`
--
--
--#### XML
--
--Um ausschließlich die generierte XML-Datei abzurufen, wird der Pfad mit der Endung `xml` verwendet:\
--`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/xml`
--
--```
--<?xml version="1.0" encoding="UTF-8"?>
--<!--Sonderzeichen in Feldnamen wurden ersetzt bzw. entfernt!-->
--<form template="AS_940000">
--...
--</form>
--```
--
--#### Anhänge
--
--Um alle Dateianhänge in einem Zip-Archiv abzurufen, wird der Pfad mit der Endung `zip` verwendet:\
--`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/zip`
--
  ### Statusänderung
--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:
++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:
--- NEW
--- READ
--- CLOSED
--- PRELIMINARY
--- HIDDEN
++- NEW
++- READ
++- CLOSED
++- PRELIMINARY
++- HIDDEN
  - DELETED
--> ***Hinweis:***\
++> ***Hinweis:***
  > Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.
  ___
@@ -120,15 +120,15 @@
  ### Neue Nachricht erzeugen
--Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\
--`/message/<Mandant>/<Transaktions-ID>/create`\
++Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:
++`/message/<Mandant>/<Transaktions-ID>/create`
  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.
  ### Übersicht
--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:
++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:
--```
++```json
  [{
    "id":"581754a5bf962e5318d90f7b",
    "transID":"AS_940000-gsh7ntqS",
@@ -150,16 +150,16 @@
  ### Status
--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:
++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:
--- NEW
--- READ
--- CLOSED
--- PRELIMINARY
--- HIDDEN
++- NEW
++- READ
++- CLOSED
++- PRELIMINARY
++- HIDDEN
  - DELETED
--> ***Hinweis:***\
++> ***Hinweis:***
  > Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.
  ___
@@ -170,7 +170,7 @@
  ### Hinzuzufügen
--Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\
++Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:
  `/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.
  ### Übersicht
@@ -181,10 +181,12 @@
  ## Abruf
--Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\
--`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\
++Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:
++`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.
  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.
  ### Löschen
  Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.
++
++