SecureFiles-Schnittstelle: Transfers lesen, anlegen und widerrufen

Über die Schnittstelle bindet ein Fachverfahren, ein Ticketsystem oder ein eigener Ablauf SecureFiles an. Sie liest den Zustand von Transfers, Anforderungen und Pools, holt eingegangene Dateien ab und legt Transfers an.

Schlüssel

Ein Schlüssel entsteht unter Einstellungen, Anbindungen. Den Zugang zu SecureFiles vergibt, wer dort alle Transfers verwaltet.

Jeder Aufruf trägt den Schlüssel im Kopf Authorization: Bearer <Schlüssel>. Ein Schlüssel lässt sich auf Adressen einschränken, befristen und widerrufen.

In wessen Namen ein Schlüssel schreibt

Ein Schlüssel mit Schreibzugang handelt im Namen der Person, die ihn angelegt hat.

• Es gelten die Regel und das Kontingent dieser Person.
• Die Transfers stehen in ihrer Liste und im Protokoll, mit dem Vermerk der Schnittstelle.
• Verlässt die Person den Mandanten oder verliert sie das Senderecht, schreibt der Schlüssel nicht mehr.
• Fortsetzen, abschließen und widerrufen lässt sich nur, was über diesen Schlüsselinhaber entstanden ist.
• In einen Pool lädt der Schlüssel nur, wenn diese Person dort Mitglied ist und im Zielordner schreiben darf.

Lesen

kind ist transfer, public_link oder request. Die Liste blättert über nextCursor.

Jeder Transfer nennt mit encrypted, ob er Ende-zu-Ende verschlüsselt ist. Mit Inhaltszugang trägt der einzelne Transfer dann zusätzlich encryption und jede Datei ihr eigenes encryption: die Hüllen, wie sie gespeichert sind. Der Dateiname der Zeile ist dort ein Platzhalter, der echte steht versiegelt in der Hülle.

Transfer anlegen

Der Weg hat drei Schritte: anlegen, hochladen, abschließen.

1. Anlegen

POST /api/v1/securefiles/transfers

{
  "kind": "transfer",
  "recipients": ["empfaenger@example.org"],
  "subject": "Unterlagen",
  "retention": "7d",
  "maxDownloads": 5,
  "files": [{ "filename": "bericht.pdf", "sizeBytes": 482113 }]
}

Die Antwort nennt die Kennung, die Abrufadresse und je Datei den Weg des Uploads. Die Abrufadresse steht nur in dieser Antwort.

{
  "id": "…",
  "link": "https://…/l/…",
  "expiresAt": "2026-10-12T10:00:00.000Z",
  "files": [
    { "id": "…", "mode": "single", "uploadUrl": "https://…", "uploadHeaders": {} }
  ]
}

2. Hochladen

• mode: single: die Datei mit PUT an uploadUrl senden, mit den Köpfen aus uploadHeaders.
• mode: multipart: die Datei in Teile der Größe partSize schneiden. Adressen für die Teile liefert POST /api/v1/securefiles/transfers/parts mit transferId, fileId und partNumbers. Jeden Teil mit PUT senden und den Kopf ETag der Antwort festhalten.

3. Abschließen

POST /api/v1/securefiles/transfers/finalize

{
  "transferId": "…",
  "files": [
    { "id": "…", "mode": "single" },
    { "id": "…", "mode": "multipart", "parts": [{ "partNumber": 1, "etag": "…" }] }
  ]
}

Danach läuft die Virenprüfung, sofern die Übertragung nicht Ende-zu-Ende verschlüsselt ist. Erst wenn sie bestanden ist oder entfällt, wird der Transfer abrufbar und die Empfänger erhalten ihre Nachricht. Den Zustand zeigt GET /api/v1/securefiles/transfers?id=.

Anforderung aus einer Vorlage

POST /api/v1/securefiles/requests

{
  "templateId": "<Kennung der Vorlage>",
  "subject": "Unterlagen zum Vorgang",
  "recipients": ["empfaenger@example.org"],
  "retention": "30d"
}

Die Struktur der Anforderung kommt aus der Vorlage, die im Portal gespeichert wurde. Die Antwort nennt id und link zur Upload-Seite. Jeder genannte Empfänger erhält die Einladung mit dem Link. Ohne Empfänger geht keine Nachricht hinaus, der Link lässt sich selbst weitergeben.

Den Stand und die Eingänge zeigt GET /api/v1/securefiles/transfers?id=. Antworten auf Felder stehen dort nur mit Inhaltszugang.

Datei in einen Pool legen

Der Weg hat dieselben drei Schritte wie beim Transfer.

Ohne folderId landet die Datei in der Wurzel des Pools. Nach dem Abschließen sehen die Mitglieder sie nach den Rechten des Ordners.

Ende-zu-Ende über die Schnittstelle

Ein Transfer lässt sich auch Ende-zu-Ende verschlüsselt anlegen. Verschlüsselt wird beim Aufrufer, der Server erhält Hüllen, die er nicht öffnen kann, und statt des Kennworts einen daraus abgeleiteten Nachweis.

• Ohne Kennwort steht der Schlüssel im Teil des Links hinter der Raute. Der Server kennt ihn nicht und kann ihn nicht noch einmal nennen.
• An Empfänger geht Ende-zu-Ende nur mit Kennwort, weil der Server die Nachricht an die Empfänger schreibt.
• Der Mandant muss die Schutzart in den Einstellungen erlaubt haben. Eine Regel kann sie erzwingen, dann weist die Schnittstelle unverschlüsselte Transfers ab.

Wer selbst verschlüsselt, sendet beim Anlegen encryption am Transfer und an jeder Datei.

Eigene verschlüsselte Einträge abholen

Wer im Portal einen eigenen Schlüssel angelegt hat, holt eigene verschlüsselte Einträge auch ohne Browser über die Schnittstelle ab.

• Das gilt für selbst gesendete Transfers und für verschlüsselte Posteingänge samt ihrer Einreichungen.
• Der Schlüssel der Schnittstelle braucht den Inhaltszugang und muss von der Person stammen, deren Einträge abgeholt werden.
• GET /api/v1/securefiles/user-key liefert nur den versiegelten Schlüssel. Geöffnet wird er beim Aufrufer mit Schlüsselkennwort oder Wiederherstellungsschlüssel. Beides erreicht den Server nie.
• Jede Ausgabe des versiegelten Schlüssels steht im Protokoll, Aktion api_user_key_issued.
• Ein Transfer öffnet sich so nur mit einem Umschlag für den eigenen Schlüssel. Das Portal legt ihn beim Senden an.

Widerrufen

POST /api/v1/securefiles/transfers/revoke mit transferId. Der Link wird sofort ungültig, die Dateien werden gelöscht. Ein zweiter Widerruf ist kein Fehler.

Fehler

Jede Fehlerantwort hat die Form { "error": { "code": "…", "message": "…" } }.

Beschreibung nach OpenAPI

Eine maschinenlesbare Beschreibung im Format OpenAPI 3 liegt unter /assets/securefiles-openapi.json.

Ereignisse

Was in SecureFiles geschieht, liefert der Mandant als Ereignis securefiles.<aktion> über Webhooks. Sie stehen unter SecureFiles, Ereignisse und Anbindungen, zusammen mit dem Katalog der Ereignisse. Eine Anbindung reagiert auf das Ereignis und liest danach den Zustand über diese Schnittstelle.

Jedes davon ist in einem Webhook einzeln wählbar, securefiles.* liefert alle, auch künftige.

Eine Zustellung trägt bis zu 100 Ereignisse in events und ist signiert. X-Conbool-Signature enthält sha256= und den HMAC-SHA256 über Zeitstempel, Punkt und Körper. Der Zeitstempel steht in X-Conbool-Timestamp.

Nach einem Fehlschlag folgt der nächste Versuch nach 1, 5, 30 und dann je 120 Minuten. Fehlerserie und Zeitpunkt des nächsten Versuchs stehen in der Liste der Webhooks, dort lässt sich die Zustellung auch sofort wiederholen. Nach zehn Fehlschlägen ruht der Webhook, bis er wieder eingeschaltet wird.

Fertige Anbindungen

Unter SecureFiles, Ereignisse und Anbindungen liegen Vorlagen mit der Adresse der eigenen Installation.

Schlüssel und Signaturgeheimnis stehen in keiner Vorlage, beide werden nach dem Import eingetragen. Im Connector ist die Anmeldung die Kopfzeile Authorization mit dem Wert Bearer und dem Schlüssel. Power Automate prüft keine Signatur, dort schützt die geheime Adresse des Auslösers.

Nicht über die Schnittstelle

• Anforderungen frei zusammenstellen. Die Schnittstelle legt Anforderungen nur aus gespeicherten Vorlagen an.
• Dateien aus einem Pool abholen. Der Abruf dort hängt an der Rolle eines Mitglieds.

Die protokollierten Einträge beschreibt die Seite Protokoll. Zurück zur SecureFiles-Übersicht.