API | risscore

Endpoints

Alle API-Endpoints sind unter https://rissc.demo.printformer.net/docs/ zu finden.

Beispielsweise können Informationen (wie DataKeys und CustomAttributes) aus einem printformer Template ausgelesen werden:

Weiteres Beispiel für einen API-Call Ablauf:

api-samples.http

Server zu Server Kommunikation

Für alle Anfragen an /api-ext/* müssen ein Authorization: Bearer und Accept: application/json Header vorhanden sein. Der Authorization Header beinhaltet den API-Schlüssel des Mandanten, als welcher die API angesprochen werden soll.

Beispiel

curl -X POST "https://demo.printformer.net/api-ext/user" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer 6d74fe54e5dfc6380928966d9dbda33d"

Der API-Schlüssel ist im printformer Admin-Menü unter Integrationen > API-Keys in den einzelnen Mandanten (> API) zu finden.

Dateiabruf

Für den Dateiabruf mittels der API-Endpoints unter /api-ext/files/* ist die Generierung eines JWT notwendig. Durch die von der externen Plattform modifizierbaren Parameter jti, exp und urlPath kann die Gültigkeit der Datei-URL je nach Anwendungsfall passend eingestellt werden.

Die API-Endpoints liefern nicht direkt die Datei aus, sondern einen nur kurz gültigen Redirect auf die eigentliche Datei-URL.

Benutzer Authentifizierung

Um einen Benutzer von einer externen Plattform im printfomer einzuloggen (z.B. für den Editor-Aufruf) muss ein JWT generiert werden.

JSON Web Token

Unterstützte JWT Claims

Claim	Position	Beschreibung	Beispiel	Pflicht	Verwendung
client	Payload	Mandanten Identifier	oU4dL51h	ja	printformer > Integrationen > API-Keys in den einzelnen Mandanten (> API)
user	Payload	User Identifier	oxrboJwf	nein	Wird von der API beim Anlegen eines Nutzers zurückgegeben. Pflicht sobald ein Nutzer authentifiziert werden soll, z.B. beim Editor-Aufruf
urlPath	Payload	URL-Pfad	`/api-ext/files/draft/$draftId/print`	nein	Wird validiert sobald sich der Claim im Token befindet. Sollte z.B. bei der Generierung des Tokens für den Dateiabruf gesetzt werden, um zu verhindern, dass ein Token für mehrere Dateiabruf-URLs gültig ist.
redirect	Payload	URL zu welcher der User nach erfolgreichem Login weitergeleitet werden soll	`https://demo.printformer.net/editor/$draftId/edit`	nein	Muss die externe Plattform generieren
jti	Header	Nonce, darf nicht doppelt verwendet werden, muss für jedes JWT neu generiert werden	K1jKpIZSiS08TtX3XixI6dPZ91jBVS23tp8z2uiA7RjQxcBk0pCwC9d6FrU2	nein	Pflicht sobald ein Nutzer authentifiziert werden soll, z.B. beim Editor-Aufruf
exp	Payload	Expiration Date (Timestamp UTC) wie lange dieses JWT gültig ist	1511430662	nein	Wird validiert sobald sich der Claim im Token befindet.

Das JWT wird mit einem Sha256 signiert (als Schlüssel wird wieder der API-Schlüssel des Mandanten verwendet)

Im Browser wird dann https://demo.printformer.net/auth?jwt={JWT} aufgerufen.

Anleitung: User-Anlage bis Editor-Aufruf

printformer-api-example (PHP)

Step	API-Referenz	Voraussetzung	Ergibt	Beschreibung
1	https://rissc.demo.printformer.net/docs/#/User/post_api_ext_user	Mandanten API-Schlüssel	User Identifier	Als erstes wird ein neuer User angelegt. Der neue User wird automatisch dem Mandanten, der ihn angelegt hat, zugewiesen.
2	https://rissc.demo.printformer.net/docs/#/Draft/post_api_ext_draft	Mandanten APi-Schlüssel User Identifier Master Id	DraftHash	Für den neu angelegten User, wird ein neuer Draft erzeugt.
3	https://rissc.demo.printformer.net/docs/#/User/post_api_ext_user	Mandanten API-Schlüssel Mandanten Identifier User Identifier DraftHash	JWT	Die Externe Plattform muss ein JWT generieren
4		JWT	Editor-Aufruf	Mit diesem JWT kann der User einmalig eingeloggt werden