Dokumentation
Inhalt
- Allgemeines
- Aus Sicht eines Empfängers von digitalen Druckunterlagen
- Aus Sicht eines Versenders von digitalen Druckunterlagen
Allgemeines zur Benutzung der Schnittstelle
Zur Authentifizierung werden Zugriffstokens verwendet (JWT). Werden API-Methoden aufgerufen, ohne ein solches Token zu übergeben, oder wenn die zeitliche Gültigkeit des Tokens (eine Stunde nach Ausstellung) abgelaufen ist, wird implizit der Demo-Klient als Aufrufer angenommen.
Um Zugriffstokens abrufen zu können, benötigt man bestimmte Anmeldeinformationen, die auf Anfrage beim Mediaservice Wasmuth erhältlich sind. Mit diesen Informationen kann dann über einen Secure Token Server ein solches Token abgerufen werden. Dieses Token hat eine begrenzte Gültigkeitsdauer von einer Stunde und muß bei jedem Aufruf der Schnittstelle im Authorization-Header mit angegeben werden. In den verfügbaren Demo-Downloads wird dies anhand von Skripten / C#-Anwendungen / POSTMAN-Requests gezeigt.
Aus Empfängersicht
Hier gibt es prinzipiell mehrere Möglichkeiten, um die abholbereiten Druckaufträge von der API abzufragen. Verschiedene Endpunkte können verwendet werden, um auf der Empfänger- / Abholerseite die gewünschten Abläufe realisieren zu können.
Beispiel 1: Abrufen empfangsbereiter Aufträge, herunterladen und markieren der Aufträge als bereits abgeholt
Die generelle Vorgehensweise ist hier, in regelmäßigen Abständen ( bspw. alle 5 Minuten ) den entsprechenden Endpunkt /Auftraege/NachStatus/ZurAbholungBereit aufzurufen ( Polling ):
und im Falle des Vorhandensein eines oder mehrerer Aufträge diese iterativ zu durchlaufen und dabei die gewünschten Daten von einem weiteren Endpunkt abzurufen. Je nach Anwendungsfall können diverse Dateien / Infos pro Auftrag abgerufen werden. Dazu zählen u.a.:
-
Das sogenannte Job-Ticket enthält in einer Zip-Datei neben der eigentlichen Druckunterlage [ Du.pdf ]
auch diverse Reports und zusätzliche Metadaten ( Auftraege/{id}/Ticket.json ) - Die Metadaten als separate JSON-Datei ( Auftraege/{id}/Ticket.json )
- Die Druckunterlage als einzelne PDF-Datei ( Auftraege/{id}/DU.pdf )
- ..
Nachdem alle gewünschten Daten für den jeweiligen Auftrag erfolgreich heruntergeladen wurden, wird dieser über den Endpunkt /Auftraege/{id}/IstAbgeholt entsprechend markiert, so dass er bei einem späteren Aufruf des oben genannten Endpunktes nicht mehr aufgelistet wird.
Beispiel 2: Aufträge werden nicht verändert, sondern mit Referenzdatum und oder Filtern ausgewählt
Soll der Status eines abgeholten Auftrages nicht über die API geändert werden, kann der Endpunkt /Auftraege/EmpfangsUebersicht mit einem Referenzzeitpunkt
( typischerweise derjenige des vorrangegangenen API-Aufrufes ) verwendet werden. Die dann ggfs. zurückgegebene Liste mit Aufträgen kann dann analog zu Beispiel 1 abgearbeitet werden.
