Endpunktübersicht

Alle Pfade dieser Seite hängen an der Basisadresse des Mandanten:

https://<mandant>.stp-cloud.de/documents/dms-cloud-api/api

Die Basisadresse trägt keine Versionsangabe – die steht am Anfang jedes Pfades. Der vollständige Aufruf der Aktensuche lautet also https://<mandant>.stp-cloud.de/documents/dms-cloud-api/api/v1/dms/documents/container. Der Vorteil dieser Aufteilung: Adressen, die die Schnittstelle selbst zurückgibt – etwa die statusUrl eines Vorgangs – lassen sich unverändert an die Basisadresse hängen.

Jeder Aufruf braucht zwei Scopes im Token: den Lizenz-Scope des Mandanten (dms.cloud.api.standalone oder die partnergebundene Entsprechung) und den in der Spalte Benötigter Scope genannten Capability-Scope des Endpunkts.

„Scope“ meint hier genau das, was im Zugriffstoken steht – dieselben Zeichenketten, die auch in der Client-Registrierung unter erlaubte Bereiche auswählbar sind. Fehlt einer der beiden, wird der Aufruf abgelehnt; welcher davon fehlt, sagt der Fehlercode (403 LICENSE_MISSING bzw. 403 INSUFFICIENT_SCOPE). Einzelheiten in Lizenzen und Berechtigungen.

Akten, Ordner und Dokumente

Verfahren und Adresse	Zweck	Benötigter Scope	Antwort
`GET /v1/dms/documents/container`	Akten und Ordner suchen oder durchblättern	`dms.cloud.api.documents.read`	`200`
`GET /v1/dms/documents/container/{containerId}/documents`	Alle Dokumente einer Akte oder eines Ordners	`dms.cloud.api.documents.read`	`200`
`GET /v1/dms/documents/container/{containerId}/filing-tray`	Register einer Akte oder eines Ordners	`dms.cloud.api.documents.read`	`200`
`GET /v1/dms/documents/container/{containerId}/filing-tray/{trayId}/documents`	Dokumente eines einzelnen Registers	`dms.cloud.api.documents.read`	`200`
`POST /v1/dms/documents`	Ein bereitgestelltes Dokument importieren	`dms.cloud.api.documents.write`	`202`
`GET /v1/dms/documents/{documentId}/content`	Ein Dokument exportieren	`dms.cloud.api.documents.read`	`202`
`POST /v1/dms/documents/{documentId}/move`	Ein Dokument in eine andere Akte bzw. einen anderen Ordner umlegen	`dms.cloud.api.documents.write`	`200`

Die Suche nach Akten und Ordnern im Detail

GET /v1/dms/documents/container kennt vier Betriebsarten. Es darf höchstens einer der drei Suchparameter gesetzt sein:

Parameter	Wirkung
`name`	Exakte Suche über den Aktennamen
`fileReference`	Exakte Suche über das Aktenzeichen
`searchTerm`	Präfixsuche über Name und Aktenzeichen
(keiner)	Seitenweises Durchblättern aller Akten und Ordner
`pageSize`	Anzahl der Treffer je Seite
`continuationToken`	Der Wert aus `nextContinuationToken` der vorherigen Seite

Bereitstellung von Dateien

Diese Endpunkte gehören zur Plattform und sind unabhängig vom Dokumentenmanagement. Sie erzeugen zeitlich befristete, signierte Adressen; die Dateibytes laufen nicht über die Schnittstelle.

Verfahren und Adresse	Zweck	Benötigter Scope
`POST /v1/platform/uploads/single`	Eine Ablageadresse für eine Datei erzeugen	`dms.cloud.api.uploads`
`DELETE /v1/platform/uploads/{objectKey}`	Ein bereitgestelltes, nicht mehr benötigtes Objekt löschen	`dms.cloud.api.uploads`
`POST /v1/platform/multipart/initiate`	Mehrteilige Ablage beginnen, Adressen je Teil erzeugen	`dms.cloud.api.uploads`
`POST /v1/platform/multipart/complete`	Mehrteilige Ablage aus den Teilen zusammenführen	`dms.cloud.api.uploads`
`DELETE /v1/platform/multipart/abort`	Mehrteilige Ablage abbrechen und Teile verwerfen	`dms.cloud.api.uploads`
`GET /v1/platform/multipart/refresh`	Abgelaufene Teil-Adressen neu erzeugen	`dms.cloud.api.uploads`
`GET /v1/platform/multipart/parts`	Bereits abgelegte Teile auflisten, um fortzusetzen	`dms.cloud.api.uploads`

Die mehrteilige Variante ist für große Dateien gedacht. Für alles, was in einem Zug übertragen werden kann, genügt uploads/single.

Vorgänge und Betriebszustand

Verfahren und Adresse	Zweck	Benötigter Scope
`GET /v1/platform/operations/{operationId}`	Zustand und Ergebnis eines mit `202` angenommenen Vorgangs	derjenige des auslösenden Aufrufs
`GET /v1/platform/connector/heartbeat`	Verbindungszustand des Connectors dieser Kanzlei	`dms.cloud.api.connector.read`

Die Vorgangsabfrage verlangt genau denselben Scope wie der Aufruf, der den Vorgang ausgelöst hat. Ein Abruf verrät also nie mehr, als der ursprüngliche Aufruf gedurft hätte.

Der Zustandsabruf des Connectors verlangt einen eigenen Scope (dms.cloud.api.connector.read), der bewusst nicht mit dem Bereitstellen von Dateien zusammenfällt: Wer nur wissen will, ob der Connector läuft, soll dafür keine Schreibberechtigung brauchen. Der Bereich muss der Rolle ausdrücklich zugewiesen sein – ohne ihn antwortet der Endpunkt mit 403 INSUFFICIENT_SCOPE, auch wenn alle übrigen Aufrufe funktionieren.

Zustände eines Vorgangs

`status`	Bedeutung
`pending`	Läuft noch. Später erneut abfragen.
`succeeded`	Fertig. `result` enthält die Antwort des auslösenden Aufrufs.
`failed`	Gescheitert. `reason` und `errorCode` nennen den Grund.
(`404`)	Unbekannte Kennung, oder der Abrufzeitraum von sieben Tagen ist abgelaufen.

Welche Aufrufe synchron und welche asynchron sind

Art	Endpunkte	Grund
Synchron (`200`)	Alle Suchen und Auflistungen, Umlegen	Antwort in Sekundenbruchteilen
Asynchron (`202` und Abfrage)	Import und Export von Dokumenten	Kann bei großen Dateien länger dauern, als das Zeitlimit der Schnittstelle zulässt

Ein 202 bedeutet angenommen, nicht erledigt. Die Prüfung der Anfrage findet trotzdem sofort statt: Eine fehlerhafte Anfrage ist ein 400 auf diesen Aufruf und wird nie zu einem gescheiterten Vorgang.

Immer sinnvolle Kopfzeilen

Kopfzeile	Zweck
`Authorization: Bearer …`	Pflicht bei jedem Aufruf
`X-Correlation-Id`	Eigene Vorgangskennung, erscheint in Antwort und Protokollen
`Idempotency-Key`	Bei verändernden Aufrufen – siehe Idempotenz und Wiederholungen

Es gibt keine Kopfzeile für den Mandanten. Der Mandant wird ausschließlich dem Token entnommen.