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

Beim Umlegen werden Zielakte und Zielregister vorab geprüft: gibt es die Akte nicht oder hat sie das angegebene Register nicht, ist die Antwort 404 NOT_FOUND mit einer Meldung, die das Fehlende benennt. targetTrayId darf 0 sein – das legt das Dokument direkt in die Akte, in kein Register.

Register und Registerstruktur im Detail

Die Dokumentliste einer Akte ist flach – sie nennt nicht, in welchem Register ein Dokument liegt. Die Untergliederung liefert .../filing-tray, und zwar die gesamte Registerstruktur der Akte in einer Antwort, nicht nur die oberste Ebene.

Ein Eintrag nennt trayId, name und displayText, dazu drei Felder, die die Struktur tragen:

Register sind also verschachtelbar, und die Schnittstelle bildet das vollständig ab. Ein einzelnes Register wird über .../filing-tray/{trayId}/documents gelesen; mit ?recursive=true liefert der Aufruf zusätzlich die Dokumente aller darunter liegenden Register. Damit lässt sich ein Teilbaum der Akte gezielt übernehmen, statt alle Dokumente der Akte zu holen und anschließend auszusortieren.

trayId=0 ist kein Register, sondern die Ablage direkt in der Akte – die Dokumente, die in keinem Register einsortiert sind. In der Registerliste erscheint 0 deshalb nicht, und recursive bleibt dort ohne Wirkung.

Beim Import und beim Umlegen benennt trayId bzw. targetTrayId das Zielregister; 0 legt das Dokument direkt in die Akte. Welchem Register ein einzelnes Dokument zugeordnet ist, steht in seinen Stammdaten unter filing.

Versionen und Renditions im Detail

Ein Dokument kann mehrere Versionen haben – jede Version ist ein eigener Inhaltsstand, die neueste ist die aktuelle. Zu jeder Version kann es zusätzlich Renditions geben: alternative Darstellungen desselben Inhalts, etwa eine PDF-Vorschau oder ein Volltextauszug.

Die Stammdaten nennen neben Titel, Kommentar und Klasse auch, wie das Dokument ins Dokumentenmanagement gelangt ist (source, etwa bea oder scan), ob es Ein- oder Ausgang ist (mailRoute), das Datum des Schreibens – und ob eine Änderung derzeit abgelehnt würde (lockState). Letzteres lohnt sich vor dem Bereitstellen einer Datei: ein gesperrtes Dokument nimmt keine neue Version an.

Wer ein Dokument angelegt oder zuletzt geändert hat, wird bewusst nicht ausgegeben. Das Dokumentenmanagement führt dort Benutzerkonten Ihrer Kanzlei; die Schnittstelle nennt Zeitpunkte, keine Namen.

Beim Einstellen einer neuen Version ändert sich nur der Inhalt: Akte, Register, Titel und Dokumentklasse bleiben, wie sie sind. Das Feld comment beschreibt die neue Version – anders als beim Import eines neuen Dokuments wird daraus nicht der Titel des Dokuments. Ohne comment wird der Kommentar der bisherigen Version übernommen.

Ist das Dokument gerade von jemand anderem in Bearbeitung, wurde es zwischenzeitlich geändert, ist es eingefroren oder zum Löschen vorgemerkt, scheitert der Vorgang mit errorCode: "CONFLICT". Dann das Dokument erneut lesen und den Aufruf wiederholen.

Zu beachten:

• Renditions können nur abgerufen werden. Diese Schnittstelle bietet keinen Weg, eine Rendition zu hinterlegen oder zu löschen; sie entstehen im Dokumentenmanagement selbst – bekannte Namen sind stp.doc.preview (PDF-Vorschau) und stp.doc.fulltext.txt (Volltext).
• Ohne version gilt die neueste Version. Welche es war, steht im Ergebnis des Vorgangs.
• Welche Versionen und Renditions es gibt, sagt Ihnen die Schnittstelle. Der Versionsverlauf nennt die Versionsnummern, die Renditions-Liste die Namen – beides ist genau das, was ?version= und ?rendition= beim Abruf erwarten. Eine Nummer oder einen Namen, den es nicht gibt, beantwortet die Schnittstelle mit 404.
• Der Versionsverlauf nennt je Version nur die Anzahl der Renditions, nicht deren Namen – so bleibt die Antwort auch bei vielen Versionen kompakt. Die Namen liefert GET …/{documentId}/renditions.

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:

Ein Suchparameter, der zwar mitgeschickt wird, aber leer ist oder nur aus Leerzeichen besteht, wird mit 400 VALIDATION_FAILED abgelehnt. Wer alle Akten durchblättern möchte, lässt ihn weg – sonst wäre nicht zu unterscheiden, ob nichts gefunden wurde oder ohne Kriterium gesucht wurde.

Beim Durchblättern wird immer genau eine Art gelistet: Akten und Ordner liegen im Dokumentenmanagement in getrennten Beständen mit eigener Zählung, eine gemischte Liste beider Arten gibt es deshalb nicht. Wer beides braucht, blättert zweimal – einmal ohne containerType und einmal mit containerType=folder. Ein anderer Wert als dossier oder folder wird mit 400 VALIDATION_FAILED abgelehnt, ebenso containerType zusammen mit einem der drei Suchparameter: name und fileReference suchen ausschließlich in Akten, und bei searchTerm entscheidet das Dokumentenmanagement selbst über die Arten.

containerType=folder setzt einen aktualisierten Connector voraus. Ein Connector, der diesen Parameter noch nicht kennt, meldet trotzdem 200 – blättert dann aber unbemerkt Akten statt Ordner, ohne Fehlermeldung. Bleiben die zurückgegebenen Treffer bei containerType=folder unerwartet vom Typ Akte, zunächst die installierte Connector-Version prüfen, bevor die eigene Integration verdächtigt wird.

Der continuationToken gehört zu genau der Abfrage, die ihn erzeugt hat: zur Betriebsart und zu den Suchkriterien, beim Durchblättern einschließlich containerType. Wird er mit einem anderen Kriterium weiterverwendet, ist die Antwort 400 VALIDATION_FAILED und nicht etwa eine Seite aus der falschen Treffermenge. Eine Seite aus dem Ordner-Durchblättern lässt sich also nicht im Akten-Durchblättern fortsetzen. Dasselbe gilt für die beiden Dokumentlisten – dort ist der Zeiger an die Akte und, beim Register, zusätzlich an Register und recursive gebunden. Die Seitengröße der beiden Dokumentlisten reicht von 1 bis 200, Voreinstellung 50.

Ein Treffer nennt Kennung, Bezeichnung, das kanzleiinterne Aktenzeichen, das gerichtliche Aktenzeichen und die Art (Akte oder Ordner) – dazu accessLevel, also was der aufrufende Benutzer mit dieser Akte darf (none, read, write, full). Damit lässt sich ein nur lesbarer Treffer erkennen, bevor ein Schreibversuch daran scheitert. Fehlt das Feld, meldet das Dokumentenmanagement eine Berechtigung, die diese Schnittstelle nicht kennt – dann sagt erst der Aufruf selbst, was erlaubt ist.

Ein Eintrag der beiden Dokumentlisten nennt Kennung, name, title, documentType, sizeBytes, modifiedAt und letterDate. name und title beantworten zwei verschiedene Fragen und werden deshalb beide ausgegeben:

Für eine Übersicht ist title die richtige Anzeigespalte und letterDate das fachlich richtige Sortierkriterium; modifiedAt ist ein technischer Zeitstempel und sagt nichts darüber, wann ein Schreiben verfasst wurde.

title und letterDate setzen einen aktualisierten Connector voraus. Ein Connector, der die beiden Felder noch nicht kennt, meldet trotzdem 200 – dann trägt title denselben Wert wie name und letterDate bleibt bei allen Dokumenten leer. Sieht eine Übersicht durchgehend nach Dateinamen aus und bleibt die Datumsspalte leer, zuerst die installierte Connector-Version prüfen, bevor die eigene Integration verdächtigt wird.

Ist im Dokumentenmanagement kein Titel erfasst, trägt title die Kennung des Dokuments – denselben Wert wie documentId, und damit auch hier den Wert, den der Einzelabruf meldet. Eine Anzeige, die das nicht erwartet, zeigt in solchen Zeilen eine lange Zeichenfolge.

Beteiligte einer Akte – Mandant, Gegner, Sachbearbeiter – gibt die Schnittstelle bewusst nicht aus. Es sind personenbezogene Daten, und keine Funktion dieser Schnittstelle braucht sie.

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.

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

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

Welche Aufrufe synchron und welche asynchron sind

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

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

Weiterführend

• Schnellstart
• Fehlercodes