File

Dateiverwaltung: Dateien zweistufig hochladen (Registrierung per file/set, anschließender Upload an den separaten Datei-Service), Downloads abrufen, Metadaten lesen und Dateien löschen.

Datei registrieren (Upload vorbereiten)

POST KUNDEN-HMAC /file/set

Registriert eine neue Datei und liefert den Upload-Endpunkt sowie einen zeitlich befristeten securekey zurück. Der eigentliche Dateiinhalt wird in Schritt 2 an den separaten Upload-Service gesendet (siehe unten).

Request-Body (form-data)

Feld	Beschreibung	Beispiel
associated_type	Verknüpfungstyp (nur erlaubte Werte, z. B. postboxitem)	postboxitem
associated_type_ID	ID des verknüpften Objekts (Pflicht, wenn associated_type gesetzt; max. 100)	6bd525df-5b16-4a55-b5d9-ee4cf5277d7b
file_name	Dateiname (Pflicht, max. 300)	Anlage-EK-Einkommenserklaerung-kn.pdf

Response

Upload-Endpunkt und zeitlich befristeter Upload-Schlüssel – securekey und file_ID für den Upload (Schritt 2) sowie spätere Zugriffe verwenden:

{
  "url": "https://file.ebonaut.io/upload",
  "securekey": "2g%2F0ubw%2BGM8GPnXwzCC8BO3LiOaYhhnvI%2F1NS5zkJg2p%2FU6CLCXRlt%2BBlu2Xwc%2FF8vpbgPDsKG4foyegpFyf3xu%2BTBUoUspcFuT8npFm2c4MzUZ0DEAyQHBb%2FY5M7M4wQfb2iQAHmNd648%2F9HHbJFvbqgK0XDtUgGuvEj3oOoyd2njjOW5AaDT8uF8FsC0pMBBU4o8pZ6p9wHmkCL8m92y%2FDqpp0owYElAKJoiZiFAd9IBrwcSjTB%2ByhfKtwA4VL5Ew5dAmKJxR0XmKsa2qTm9fRrJkvBhrzaNNKEuz9zcxUantASBnH%2F%2FXMN12c39QCKWe323T5JVf9DLV%2FeX%2FhDg9qDZdXMOIyfRBIyloBGDW4AYAN0OpVVQ%2F7uNxX99BU9M7nRHqa3yhAWNQjR9RWKjge%2B2vh3mJF5fJnI%2BfpqdGIPHKdBQCkVrFPubUZR5F1iksfG80WL9b1EiBudHKbGTpmLDm1GXZ7F9g3NoO4KqE9FJVQeFx%2FzuGTuS8qp1TMPFoXkFtOxKijMGPvLnTzjmd7bofxkHDVIXQrzwpknzpIqFOV5ymspuMWwB0fXpyDoWSDswFGRleNqviUzD%2BepFAIczV4l1IajNER8tPOE98%3D",
  "file_ID": "jfszVDQcdwkFSXGJHEFqkfmGDAKrJU"
}

Mögliche Fehler

Code	Meldung	Bedingung
406	requiredduetodependency	associated_type gesetzt, aber associated_type_ID fehlt
406	validationinvalid	file_name fehlt/zu lang oder Werte außerhalb der erlaubten Listen
500	failed to save file data	Datenbankfehler beim Registrieren
500	not all data items were inserted correctly	Datenfelder nicht vollständig gespeichert
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Datei hochladen (Upload-Service)

POST https://file.dev.ebonaut.io/upload

Externer Endpunkt

Dieser Endpunkt läuft auf einem separaten Service-Host (je nach Umgebung, z. B. file.dev.ebonaut.io).

Schritt 2 des Uploads: sendet den Dateiinhalt als multipart/form-data an den separaten Upload-Service. Die URL steht in der url-Antwort von file/set (Host je nach Umgebung, z. B. file.dev.ebonaut.io). Der securekey aus file/set legitimiert den Upload (ca. 25 Minuten gültig). Kein HMAC – dieser Request darf nicht mit HMAC signiert/verschlüsselt werden.

Request-Body (form-data)

Feld	Beschreibung	Beispiel
securekey	securekey aus der file/set-Response	wKm%2FTY2n0hwrIba7BK5TrW44QX%2BqfNPo%2F8NFLvAL6lBmZm%2FL7BdzZfZ43q83kiCHkvyLe6MqIq2nkNKYQJdef0e%2BlYILZTQ9Vo0d91vdFOx6zrRnrYYnCFX0R6SSebMyubJ3HxslsA6Z655e3MDUR7z0ziuf%2B9F9dFSx7eplDVablfZ0M7NnzYWlxI52H9ofuODC%2FCWfFEeIwCFSZsw32U5cOnwqzie9ukiTuzvKvlJFb8N9mUwtdN6jFJEvO78GmZ3LuheRkCPE2A3LpaX9oOr7otJx9e%2BVWSm9lw3d8uizixK2O%2BzUTwkU9QLaceBIKIVVpGiacbWCRVbmL0CiAwlcvbNfHDwEVleTL4UMvamlxjwLFUFTNuJAEUsHJ1emdFTPfXaB6DgACSNzFLn6injjO47uOA%2FA26hcpMX%2BHx4p%2F2HRAlQB6Ma2Uyz9xCqfAJdfPRD1C5%2F5JqqQUpetOaQlu7SKWcAogMzwm%2FB2tW2pkixomrOLlE%2Btt%2BRLcZTIC3MSWCfP2149kPKzzKsSxJ6dCXbxWsHHPJdEfu5ux8s%3D
file	Binärer Dateiinhalt (form-data file field)	Datei-Upload

Response

Bei Erfolg 200 mit HTML-Body OK. Danach ist die Datei über file/get und file/getdata abrufbar.

Mögliche Fehler

Code	Meldung	Bedingung
410	Gone	securekey abgelaufen oder Datei bereits hochgeladen
403	Forbidden	securekey ungültig oder fehlt
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Datei herunterladen

GET KUNDEN-HMAC /file/get/{file_ID}

Liefert einen Download für die Datei. Ohne function-Parameter antwortet der Endpunkt mit 302-Redirect auf eine ca. 5 Minuten gültige Download-URL. Mit function=url oder function=print wird stattdessen die URL als JSON geliefert (für print ohne Dateinamen-Anhang).

Pfad-Parameter

Parameter	Beispiel	Beschreibung
file_ID	NexXEGKTFZRVmFnMBAmmSqmxRAsjWX	Datei-ID (30 Zeichen)

Response

Standardmäßig antwortet der Endpunkt mit 302 und Location-Header auf die Download-URL. Mit function=url oder function=print wird die URL stattdessen als JSON geliefert (bei print ohne Dateinamen-Anhang):

{
  "url": "<download-url>"
}

Mögliche Fehler

Code	Meldung	Bedingung
404	file not found, or no rights	Datei unbekannt, falsche Firma oder Inhalt nicht im Speicher
406	validationinvalid	file_ID nicht exakt 30 Zeichen oder function ungültig
500	an error occurred during processing	Interne Verarbeitung fehlgeschlagen
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Metadaten einer Datei abrufen

POST KUNDEN-HMAC /file/getdata

Liefert den Datei-Datensatz inklusive aller Metadaten-Felder. Mit file_data_type_group_function kann auf eine Metadaten-Gruppe gefiltert werden.

Request-Body (form-data)

Feld	Beschreibung	Beispiel
file_ID	Datei-ID (Pflicht, exakt 30 Zeichen)	mYctycsqxNFMqZfQfSejJvehjSfcuW

Weitere Request-Felder (form-data/JSON)

Feld	Beschreibung	Beispiel
file_data_type_group_function	Optional: Funktion einer Metadaten-Gruppe (nur Buchstaben, max. 50)	–

Response

Datei-Datensatz plus file_data (Map: Datentyp-Key → Wert), hier u. a. Content-Type, Seitenzahl, Vorschau als data-URI, Größe und Quelle:

{
  "file_ID": "RUenxFhSrnEQsCUzPhDqFEffRFvGsR",
  "associated_type": "",
  "associated_type_ID": "",
  "file_status": "2",
  "file_create": "2026-10-26 22:07:09",
  "file_function": "",
  "file_name": "Anlage-EK-Einkommenserklaerung-kn.pdf",
  "file_data": {
    "file_content_type": "image/png",
    "file_name": "Anlage-EK-Einkommenserklaerung-kn.pdf",
    "file_page": "1",
    "file_preview": "data:image/jpeg;base64,/9j/2wBDAAEBAQEBAQEBAQEB…",
    "file_size": "22104",
    "file_source": "upload",
    "file_title": "Anlage-EK-Einkommenserklaerung-kn.pdf"
  }
}

Feld	Typ	Beschreibung
file_ID	string	Datei-ID (30 Zeichen)
associated_type / associated_type_ID	string	Verknüpfung zu einem Objekt (kann leer sein)
file_status	string	Datei-Status (2 = hochgeladen)
file_create	string	Upload-Zeitpunkt (YYYY-MM-DD HH:MM:SS)
file_function	string	Funktion/Zweck der Datei
file_name	string	Dateiname
file_data	object	Metadaten-Map (Datentyp-Key → Wert), z. B. file_content_type, file_page, file_preview (data-URI), file_size, file_source, file_title

Mögliche Fehler

Code	Meldung	Bedingung
404	file not found, or no rights	Datei unbekannt oder falsche Firma
404	file_data_type_group_function not found, or no rights	Angegebene Gruppe existiert nicht
406	validationinvalid	file_ID ungültig
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Datei löschen

POST KUNDEN-HMAC /file/delete/{file_ID}

Löscht eine Datei (Status 0) und entfernt sie aus dem Suchindex. Geschützte Dateien (file_status = 3) können nicht gelöscht werden.

Pfad-Parameter

Parameter	Beispiel	Beschreibung
file_ID	eXYzRwbVmJCHGeSCURdWRKSVXZtqwb	Datei-ID (30 Zeichen)

Response

Der Response-Body enthält bei Erfolg [true].

Mögliche Fehler

Code	Meldung	Bedingung
404	file not found, or no rights	Datei unbekannt oder falsche Firma
423	file is protected	Datei ist schreibgeschützt (file_status = 3)
500	failed to delete file	Löschung fehlgeschlagen
406	validationinvalid	file_ID nicht exakt 30 Zeichen
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)