Submission-API

Unter dem `submission`-Endpunkt lassen sich Informationen zu eingegangenen Formularen abrufen. Zusätzlich kann Bearbeitungsstatus zurückgemeldet werden.

22

23

### Übersicht

24

25

`/submission/<Mandant>/<Formularnummer>`\

26

Mittels der Mandantennummer und der Formularnummer lässt sich eine Übersicht an eingegangenen Formularen abrufen. Dabei sind nur Metadaten enthalten, z. B.

```

[{

"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",

"npa":false

},

"payload":null,

"pdf":null,

"xml":null,

"attachments":null,

"submissionDate":1455801335305

}]

```

Wird beim Assistentenstart eine Ordnungsziffer mitgegeben enthält das Attribut payload die übergebene Ordnungsziffer als eingebettetes JSON Element.

50

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

53

1. `?status=NEW&status=READ`

54

2. `?status=NEW,READ`

55

56

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:\

70

`/submission/<Mandant>/<Formularnummer>/<Transaktions-ID>/metadata`

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

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.

#### PDF

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`

#### XML

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

...

</form>

```

#### Anhänge

Um alle Dateianhänge in einem Zip-Archiv abzurufen, wird der Pfad mit der Endung `zip` verwendet:\

99

`/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:

- NEW

- READ

- CLOSED

- PRELIMINARY

- HIDDEN

- DELETED

> ***Hinweis:***\

> Wird der Status auf `DELETED` gesetzt, werden die Inhaltsdaten (payload, pdf, xml, attachments) unwiderruflich gelöscht.

___

## Nachricht

Unter dem `message`-Endpunkt lassen sich Nachrichten zu einzelnen Transaktionen austauschen.

120

121

### Neue Nachricht erzeugen

122

123

Eine Nachricht kann über einen POST an eine Url mit folgendem Muster erzeugt werden:\

124

`/message/<Mandant>/<Transaktions-ID>/create`\

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.

### Ü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:

```

[{

"id":"581754a5bf962e5318d90f7b",

134

"transID":"AS_940000-gsh7ntqS",

135

"changedDate":1477924005742,

"status":"NEW",

"text":null,

"size":0,

"files":[]

}]

```

### Details

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>`

### Text

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.

### 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:

- NEW

- READ

- CLOSED

- PRELIMINARY

- HIDDEN

- DELETED

> ***Hinweis:***\

> Wird der Status auf `DELETED` gesetzt, werden der Text und alle Dateianhänge unwiderruflich gelöscht.

___

## Nachrichtenanhang

Zu jeder Nachricht können auch Dateien hinterlegt werden. Dies erfolgt unter dem `file`-Endpunkt.

### Hinzuzufügen

Um eine neue Datei einer Nachricht hinzuzufügen, kann diese an eine URL der Form:\

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.

### Übersicht

Die Dateien, die zu einer Nachricht vorhanden sind, können der Detailansicht der Nachricht entnommen werden.

___

## Abruf

Die Metadaten der einzelnen Dateien sind unter URLs der folgenden Form abrufbar:\

185

`/file/<Mandant>/<Nachricht-ID>/<Datei-ID>`.\

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.

### Löschen

Einzelne Dateien können über die Detail-URL auch wieder gelöscht werden. Dazu ist die HTTP-Methode DELETE zu verwenden.

Wiki-Quellcode von Submission-API

Navigation