API-Dokumentation

Übersicht zur Web-Schnittstelle

Die Web-Schnittstelle von Documents basiert auf einer REST-Architektur. Sie nutzt HTTP im JSON-Format.

Grundprinzipien

Jeder Endpunkt (Resource) der API hat eine eigene URL. Alle Anfragen sind zustandslos. Nur ein Authentifizierungs-Cookie wird benötigt.

HTTP-Methoden

Die HTTP-Methode bestimmt die Aktion:

GET: Sie lesen einen Datensatz ohne ihn zu verändern
POST: Sie erzeugen einen neuen Datensatz
PUT: Sie ändern Daten eines bestehenden Datensatzes
DELETE: Sie löschen einen Datensatz

Nicht alle Resources unterstützen alle Methoden. Ein DELETE wird verweigert, wenn Datensätze nicht gelöscht werden dürfen.

Zeichenkodierung

Sie müssen UTF-8 verwenden. Dies gilt für Anfragen und Antworten.

Datenformat

JSON-Struktur

Alle Daten werden in einem Dictionary übertragen. Der Haupt-Datensatz befindet sich unter dem Schlüssel data.

Beispiel eines komplexen JSON-Datensatzes:

{
  "data": {
    "active": true,
    "admin": false,
    "email": "[email protected]",
    "fullname": "Max Mustermann",
    "id": "00547d70-8009-3ea4-2f7c-3b8c78126ca9",
    "permissions": [
      {
        "archive_id": "0053f461-3a8c-94cc-4838-2b944a76f459",
        "permission": "write"
      },
      {
        "archive_id": "005472d9-c7e0-f3a4-6fa4-e790612a30b8",
        "permission": "read"
      }
    ],
    "roles": [
      "Archivierer",
      "Benutzer"
    ],
    "username": "max"
  }
}

Alternatives Format: multipart/form-data

Die API versteht bei POST- und PUT-Requests auch multipart/form-data. Browser verwenden dieses Format.

Einschränkungen:

Verschachtelte Datensätze sind nicht möglich
Dieses Format ist erforderlich, wenn Sie Dateien hochladen

URL-Format und Versionierung

Basis-URL

Sie erreichen die API unter dem Pfad /api/v1/. Die v1 steht für die Versionsnummer.

Beispiel:

Basis-URL: http://archiv.example.com/
API-Pfad: http://archiv.example.com/api/v1/

Versionsunterstützung

Die API unterstützt unterschiedliche Versionen. Aktuell ist nur v1 verfügbar. Innerhalb einer Version garantiert die API Rückwärtskompatibilität.

Versionen abfragen

Sie können die unterstützten Versionen abfragen:

Endpunkt: /api/info

Beispiel-Antwort:

{
  "data": {
    "versions": [
      {
        "deprecated": false,
        "num": 1
      }
    ]
  }
}

Empfohlenes Vorgehen

Sie sollten zu Beginn einer Session die unterstützten Versionen abfragen.

Wenn die Version als deprecated markiert ist:

Geben Sie eine Warnung aus

Wenn die Version nicht mehr unterstützt wird:

Geben Sie eine Fehlermeldung aus

Sie können den Info-Request überspringen und direkt auf die unterstützte Version zugreifen.

Fehlerbehandlung bei veralteten Versionen

Wenn Sie auf eine nicht unterstützte Version zugreifen, erhalten Sie:

HTTP-Statuscode: 410 Gone
Sie müssen eine eindeutige Fehlermeldung ausgeben

Relative URLs

Alle URLs in dieser Dokumentation sind relativ zur versionierten Basis-URL angegeben.

Beispiel:

GET /login bedeutet GET http://archiv.example.com/api/v1/login

Allgemeine API-Struktur

Standard-Endpunkte

Die meisten API-Endpunkte unterstützen vier HTTP-Methoden:

GET /items - Liste aller Datensätze
GET /items/<item_id> - Einzelner Datensatz
POST /items - Neuen Datensatz erstellen
PUT /items/<item_id> - Bestehenden Datensatz ändern
DELETE /items/<item_id> - Datensatz löschen

GET-Requests

Ohne ID:

Sie erhalten eine Liste von Datensätzen
Sie können die Liste sortieren und filtern

Mit ID:

Sie erhalten Daten zu einem einzelnen Datensatz
Diese Antwort ist detaillierter als die Listen-Antwort

POST, PUT und DELETE

POST /items: Sie erzeugen einen neuen Datensatz
PUT: Sie benötigen immer eine ID für bestehende Datensätze
DELETE: Sie benötigen immer eine ID für bestehende Datensätze

Listen-Antworten

Struktur

Bei Listenantworten enthält data immer eine Liste von Dictionaries:

{
  "data": [
    {
      "key": "value"
    },
    {
      "key": "value"
    }
  ],
  "total": 2
}

Limits und Paginierung

Die Anzahl der Elemente ist standardmäßig auf 100 begrenzt. Der Parameter total gibt die Gesamtzahl an Datensätzen aus (bis zu 10.000).

URL-Parameter:

start: Ab welchem Datensatz die Liste beginnt (erster Datensatz hat Index 0)
limit: Anzahl der zu übergebenden Datensätze

Beispiele:

GET /items?start=0&limit=100 - Die ersten 100 Datensätze
GET /items?start=100&limit=50 - Die nächsten 50 Datensätze

Sortierung

Sie können nach jedem Feld sortieren.

URL-Parameter:

sort: Das Feld, nach dem sortiert werden soll
direction: ASC (aufsteigend) oder DESC (absteigend), Standard ist ASC

Beispiele:

GET /items?sort=_rechnungsnummer - Aufsteigend nach Rechnungsnummer
GET /items?sort=_rechnungsnummer&direction=DESC - Absteigend nach Rechnungsnummer

Alternative Syntax:

Sie können die Sortierungsreihenfolge direkt im sort-Parameter angeben. Mehrere Sortierungen trennen Sie durch Komma.

Beispiel:

_rechnungsnummer DESC, _name ASC
Mit URL-Encoding: /items?sort=_rechnungsnummer%20DESC%2C%20_name%20ASC

Filterung

Sie können alle Felder filtern, die sortierbar sind. Verwenden Sie den Parameter query mit dem Filter-Query.

Syntax:

Die Syntax ähnelt einem SQL-WHERE-Ausdruck. Sie können Ausdrücke mit AND oder OR verknüpfen. Klammerungen werden unterstützt.

Unterstützte Operatoren:

=
!=
>
>=
<
<=
in_quarter
in_year

Beispiele:

_rechnungsnummer = 123456 AND _kunde = "Muster*"

creation_date in_year 2014

Einzelne Datensätze

Wenn Sie einen Datensatz explizit per ID anfragen, enthält data direkt ein Dictionary:

{
  "data": {
    "key": "value"
  }
}

Benutzer-Authentifizierung

Authentifizierungspflicht

Fast alle HTTP-Anfragen benötigen einen authentifizierten Benutzer.

Ohne Authentifizierung:

Sie erhalten HTTP-Status 401 Unauthorized
Sie sollten eine Anmeldung durchführen und die Anfrage wiederholen

Zwei Benutzertypen

Dienstbenutzer:

Können sich nicht in der Oberfläche anmelden
Verwenden ein Token aus der Administrationsoberfläche
Senden das Token in einem Cookie namens t bei jedem Request

Reguläre Benutzer:

Haben Benutzername und Passwort
Müssen sich über einen zusätzlichen Anmeldeschritt authentifizieren

Anmeldung für reguläre Benutzer

POST /login

Sie melden einen Benutzer an.

Request-Parameter:

username: Der Benutzername
password: Das Passwort im Klartext

Beispiel-Request:

{
  "username": "max",
  "password": "mypassword"
}

Erfolgreiche Anmeldung:

HTTP-Status: 204 No Content
Der Server setzt ein Cookie
Sie müssen dieses Cookie bei allen weiteren Requests mitsenden

Fehlerhafte Anmeldung:

HTTP-Status: 403 Forbidden

Zwei-Faktor-Authentifizierung

Wenn ein Benutzer Zwei-Faktor-Authentifizierung aktiviert hat, benötigen Sie zusätzlich ein "one-time password" (OTP). Dies ist meist ein 6-stelliger Zahlencode, der sich alle 30 Sekunden ändert.

Wenn ein zweiter Faktor benötigt wird:

HTTP-Status: 400 Bad Request
Im errors-Array finden Sie die Ursache

Beispiel-Fehlerantwort:

{
  "errors": [
    {
      "id": "otp_code",
      "msg": "errorRequired"
    }
  ]
}

Request mit OTP-Code wiederholen:

{
  "username": "max",
  "password": "mypassword",
  "otp_code": "123456"
}

Bei falschem Code:

HTTP-Status: 400 Bad Request
Fehlermeldung: errorInvalidValue

{
  "errors": [
    {
      "id": "otp_code",
      "msg": "errorInvalidValue"
    }
  ]
}

Bei erfolgreicher Anmeldung:

HTTP-Status: 200 OK
Der Server setzt zwei Cookies
Sie müssen diese Cookies bei allen weiteren Requests mitsenden

Vertrauenswürdige Geräte

Wenn der Benutzer "Vertrauenswürdige Geräte zulassen" aktiviert hat, erhalten Sie ein otp_token:

{
  "data": {
    "otp_token": "5gQugwcyvs-syH4UF5JbQAV1"
  }
}

Sie können dieses Token auf vertrauenswürdigen Geräten dauerhaft speichern.

Zukünftige Anmeldungen mit Token:

{
  "username": "max",
  "password": "mypassword",
  "otp_token": "5gQugwcyvs-syH4UF5JbQAV1"
}

Wenn das Token ungültig wird:

Sie erhalten wieder errorRequired für otp_code
Sie müssen einen neuen Code beim Benutzer abfragen

Archive abfragen

GET /viewer_archives

Sie erhalten eine Liste aller Archive und Views, auf die Sie zugreifen dürfen.

Beispiel-Antwort:

{
  "data": [
    {
      "archive_type": "archive",
      "id": "00547da9-30f3-28c0-4402-24020c1fd8be",
      "identifier": "dokumente",
      "name": "Dokumente"
    },
    {
      "archive_type": "view",
      "id": "0053f47c-1d7d-bad0-5b5b-4f132863030b",
      "identifier": "pdf",
      "name": "PDF-Dokumente"
    }
  ],
  "total": 2
}

GET /viewer_archives/<archive_id>

Sie erhalten Detailinformationen zu einem Archiv.

Parameter:

archive_id: Die ID des Archivs (oder alternativ der identifier)

Wichtige Informationen:

identifier: Der Kurzname des Archivs
name: Der Langname des Archivs
recordcolumns: Liste der Spalten im Archiv

Wichtige Felder der recordcolumns:

name: Langname der Spalte (z.B. für Spaltentitel)
identifier: Kurzname für die Übertragung von Metadaten
columntype: Datentyp (string, integer, float, datetime, date, boolean)

Beispiel-Antwort:

{
  "data": {
    "description": null,
    "id": "00547da9-30f3-28c0-4402-24020c1fd8be",
    "identifier": "dokumente",
    "name": "Dokumente",
    "recordcolumns": [
      {
        "columntype": "string",
        "id": "00547da9-30f7-82e0-f132-b6219cd9bb90",
        "identifier": "kunde",
        "length": 0,
        "lookup_restriction": false,
        "lookup_type": "none",
        "name": "Kundenname",
        "required": false
      },
      {
        "columntype": "integer",
        "id": "00547da9-30fa-123c-cbb3-365cdfdcec3f",
        "identifier": "rechnungsnummer",
        "length": 0,
        "lookup_restriction": false,
        "lookup_type": "none",
        "name": "Rechnungs-Nummer",
        "required": false
      }
    ]
  }
}

Vorgänge abfragen

GET /records?archive_id=<archive_id>

Sie erhalten eine Liste von Vorgängen in einem Archiv.

Erforderlicher Parameter:

archive_id: Die ID des Archivs

Felder mit Unterstrich (_):

Alle Felder, die mit _ beginnen, sind konfigurierte Spalten im Archiv. Nach dem Unterstrich steht der identifier der Spalte.

Standardfelder (immer vorhanden):

attachments_count: Anzahl der angehängten Dokumente
creation_date: Zeitpunkt der Archivierung (datetime-Format)
creator: Benutzer, der die Archivierung durchgeführt hat
hash_id: Unveränderlicher Hash des Vorgangs
id: Eindeutige ID des Vorgangs für die API

Beispiel-Antwort:

{
  "data": [
    {
      "_kunde": "Musterfirma 1",
      "_rechnungsnummer": 123456,
      "attachments_count": 1,
      "creation_date": "2014-12-02T12:08:01.138839+00:00",
      "creator": "Max Mustermann",
      "hash_id": "6c2bcd91549c0621d86f94c0b6761c86369e6ea603a5e0635a94be2fd4f6436e",
      "id": "00547dab-a0cf-0d48-8a9d-3de79ba5fd09"
    },
    {
      "_kunde": "Musterkunde 2",
      "_rechnungsnummer": 654321,
      "attachments_count": 2,
      "creation_date": "2014-12-02T12:08:30.202461+00:00",
      "creator": "Max Mustermann",
      "hash_id": "fd105279ee06ed9cdae675af986e3812a56bd2be4b4601ab3239f6808fb7679c",
      "id": "00547dab-bddf-56d0-7b9d-228f22a5e107"
    }
  ],
  "total": 2
}

GET /records/<record_id>

Sie rufen einen einzelnen Vorgang auf.

Unterschied zur Listen-Antwort:

Die Liste attachments enthält detaillierte Informationen zu den angehängten Dokumenten. Die übrigen Daten sind identisch.

Beispiel-Antwort:

{
  "data": {
    "_kunde": "Musterfirma 1",
    "_rechnungsnummer": 123456,
    "archive_id": "00547da9-30f3-28c0-4402-24020c1fd8be",
    "attachments": [
      {
        "custom_date": "2014-10-31",
        "custom_description": null,
        "custom_name": "TIF",
        "filename": "9pages.tif",
        "hash_id": "67050b052824c51bf290fafbf92ec6d980fd245e5e095f49dda6f2d7fac0c638",
        "id": "00547dab-a0d6-bb5c-55b5-f941a18f042b",
        "page_count": 9,
        "viewable": "9pages.pdf"
      }
    ],
    "creation_date": "2014-12-02T12:08:01.138839+00:00",
    "creator": "Max Mustermann",
    "hash_id": "6c2bcd91549c0621d86f94c0b6761c86369e6ea603a5e0635a94be2fd4f6436e",
    "id": "00547dab-a0cf-0d48-8a9d-3de79ba5fd09"
  }
}

Neueste Vorgangsversion ermitteln

Wenn eine neue Version eines Vorgangs erzeugt wird, erhält die neue Version eine neue id. Die alte Version wird versteckt und ist nur noch für Administratoren sichtbar.

GET /record_version/<record_id>

Sie erhalten die id der neuesten Version, wenn diese für Sie sichtbar ist.

Beispiel-Antwort:

{
  "data": {
    "id": "0065aa53-a0d9-6407-eb98-1d2d5bc010bb",
    "release_id": "0065aa53-5373-8c30-ce99-88075066a658",
    "release_version": 2
  }
}

Wenn die id identisch ist:

Der Vorgang ist bereits die neueste Version.

Workflow-Übergang ausführen

Was ist ein Workflow-Übergang?

Regelbasierte Workflows ermöglichen es, von einem Status aus einen oder mehrere Übergänge zu einem Zielstatus festzulegen.

Nach der Ausführung eines Übergangs:

wechselt der Vorgang in den definierten Zielstatus.
führt der Server alle für diesen Übergang konfigurierten Workflow-Aktionen aus.

Request-Parameter

Für die Ausführung eines Workflow-Übergangs benötigen Sie folgende Parameter:

Parameter	Beschreibung
`context_id`	Eine zufällige UUID
`record_id`	Die ID des Vorgangs, dessen Status gewechselt werden soll
`transition_id`	Die ID des gewünschten Übergangs

Übergangs-ID ermitteln

Sie haben zwei Möglichkeiten, die transition_id zu ermitteln:

Möglichkeit 1: Über eine Vorgangs-Abfrage (GET /records)

Die Antwort enthält in __attributes__ eine Liste möglicher Übergangs-IDs:

json

{
    "data": {
        "__attributes__": {
            "transitions": [
               "0067b74e-7b76-1a91-757f-d9aad0174775"
            ]
        },
        "_belegnr": "2025 - 001",
        "_krednr": null
    }
}

Möglichkeit 2: Über GET /transitions

Dieser Endpunkt liefert eine Liste aller verfügbaren Übergänge mit ID und Name:

{
    "data": [
       {
          "background_color": "8BCA21",
          "id": "1541e3f2-4fb8-4254-933e-a901518c8b44",
          "name": "Buchhaltung"
       },
       {
          "background_color": "F82F65",
          "id": "f0f89484-fa3e-499b-8462-c4876655fa3e",
          "name": "Fehlerhaftes Dokument"
       }
    ],
    "total": 2
}

Übergang ausführen: `POST /execute_transition`

Senden Sie einen POST-Request mit den erforderlichen Parametern:

Beispiel-Request:

{
    "context_id": "FFFFFFFF-0000-0000-0000-000000000001",
    "record_id": "006899d2-5e36-d9e5-866d-c641aec19381",
    "transition_id": "00614c76-b703-a9ad-4c46-ec9adaf95f4a"
}

Antwort des Servers

Bei erfolgreicher Ausführung gibt der Server folgende Felder zurück:

data

Enthält die Metadaten des Vorgangs (analog zur Vorgangs-Abfrage).
Falls der Benutzer keine Berechtigung für den Vorgang im nächsten Status hat, wird stattdessen gone übermittelt.

state – mögliche Werte:

Wert	Bedeutung
`completed`	Der Übergang wurde erfolgreich ausgeführt.
`pending`	Der Übergang erfordert eine Benutzerinteraktion. Der Statuswechsel erfolgt nicht automatisch.
`cancelled`	Der Server hat den Übergang abgebrochen.

message

Ein optionaler Infotext vom Server, z. B. eine Fehlermeldung.

Fehlerfall

Bei einem Fehler sendet der Server eine direkte Fehlermeldung:

{
   "error": "Der Vorgang wird gerade von einem anderen Benutzer bearbeitet."
}

Dokumente herunterladen

GET /attachments/<attachment_id>

Sie laden die Datei eines Dokuments herunter.

Parameter:

attachment_id: Die ID des Dokuments

Vorgänge archivieren

Archivierungsprozess

Ein Vorgang besteht aus zwei Komponenten:

Angehängte Dokumente (z.B. PDF- oder Word-Dateien)
Metadaten (Daten der Archivspalten, die die Dokumente zu einem Vorgang zusammenfassen)

Reihenfolge:

Sie laden die Dateien hoch
Sie referenzieren die Dateien bei der Archivierungsanfrage

Große Dateien:

Sie können große Dateien in kleine Stücke (Chunks) zerteilen. Der Server setzt diese wieder zusammen.

Sicherheit:

Sie müssen bei der Archivierung die SHA-256-Prüfsumme der Datei übergeben. Der Server prüft damit, ob die Datei korrekt empfangen wurde.

POST /chunk

Sie laden eine Datei hoch, die später archiviert werden soll.

Request-Body:

Der Inhalt der Datei als Binär-Stream.

Beispiel-Antwort:

Wichtig: Die Antwort ist nicht in data gekapselt.

{
  "id": "e5247f56-7555-472f-b5f6-5d0381be7371",
  "success": true
}

POST /upload

Sie laden eine Datei hoch. Dieser Endpunkt unterstützt nur multipart/form-data.

Parameter:

file (erforderlich): Die Datei oder der Chunk, der hochgeladen werden soll
calculate_checksum (optional): Setzen Sie diesen Wert auf true, wenn der Server die SHA-256-Prüfsumme berechnen soll

Hinweis zur Prüfsumme:

Sie sollten die SHA-256-Prüfsumme selbst berechnen. Nur wenn dies nicht möglich ist (z.B. bei Webbrowsern), lassen Sie sie vom Server berechnen.

Beispiel-Antwort:

Wichtig: Die Antwort ist nicht in data gekapselt.

{
  "checksum": "e0eb20abe0f7f3affe92cb4c0d040dfcf7b3080477e978cb2eba42508ed929b3",
  "filename": "archives.png",
  "id": "e5247f56-7555-472f-b5f6-5d0381be7371",
  "success": true
}

POST /records

Sie archivieren einen neuen Vorgang.

Request-Parameter:

archive_id (erforderlich): Die ID des Archivs
files (erforderlich): Liste von Dokumenten, die angehängt werden sollen (kann leer sein)
_<identifier>: Metadaten mit vorangestelltem Unterstrich (einige können Pflichtfelder sein)

Parameter für die files-Liste:

chunks (erforderlich): Liste von Chunk-IDs aus POST /upload (darf nicht leer sein)
checksum (erforderlich): SHA-256-Prüfsumme der Datei
filename (erforderlich): Dateiname des Dokuments
custom_name (optional): String-Feld (max. 255 Zeichen)
custom_description (optional): String-Feld (max. 2048 Zeichen)
custom_date (optional): Datums-Feld

Hinweis zu chunks:

Wenn Sie eine Datei im Ganzen hochgeladen haben, enthält die Liste nur eine ID. Bei zerteilten Dateien müssen die IDs in der richtigen Reihenfolge sein. Der Server setzt die Chunks von links nach rechts zusammen.

Beispiel-Request:

{
  "archive_id": "00547da9-30f3-28c0-4402-24020c1fd8be",
  "_kunde": "Musterfirma",
  "_rechnungsnummer": 123,
  "files": [{
    "chunks": ["c9b67df8-d8de-4209-8e4b-485196048bd4"],
    "checksum": "e0eb20abe0f7f3affe92cb4c0d040dfcf7b3080477e978cb2eba42508ed929b3",
    "filename": "archives.png"
  }]
}

Beispiel-Antwort:

Identisch mit der Antwort von GET /records/<record_id>.

PUT /records/<record_id>

Sie ändern einen existierenden Vorgang.

Was Sie ändern können:

Metadaten (wenn als "Änderbar" konfiguriert)
Angehängte Dokumente (wenn im Archiv erlaubt)

Nicht erlaubte Änderungen:

Der Server ignoriert diese.

Bei revisionssicheren Daten:

Dieser Request erzeugt eine neue Version des Vorgangs.

Dokumente ändern:

Sie müssen die Liste attachments übergeben:

Bestehende Dokumente referenzieren Sie über deren id
Neue Dokumente fügen Sie im gleichen Format wie in POST /records hinzu
Die Reihenfolge bestimmt die Anzeige in der Oberfläche
Nicht referenzierte Dokumente werden entfernt

Beispiel-Request:

{
  "_kunde": "Musterfirma",
  "_rechnungsnummer": 123,
  "attachments": [{
    "id": "005ba9e2-885b-99fc-a951-92db3a22e238"
  },{
    "chunks": ["181ba316-309d-4df8-8728-1090295743bf"],
    "checksum": "ac4f0d97368365b30f0398d32783b7ca47c2ed6993cd1696ca8401d9d1fea31d",
    "filename": "Rechnung.pdf"
  }]
}

Beispiel-Antwort:

Identisch mit der Antwort von GET /records/<record_id>.

Bei neuer Version:

Die Antwort enthält eine neue id. Der Wert in release_version wird hochgezählt.

Öffentliche Links

Wichtiger Hinweis:

Ein Statuswechsel kann einen erzeugten Link ungültig machen. Dies passiert beispielsweise, wenn der Dienstbenutzer im neuen Status keinen Zugriff mehr auf den Vorgang hat.

Öffentliche Links für Dokumente

Sie können Links für einzelne Dokumente erzeugen. Diese Links ermöglichen den Download ohne Benutzeranmeldung.

Wichtig:

Links sind mit dem erzeugenden Benutzer verknüpft
Links funktionieren nur, solange der Benutzer Zugriff auf das Dokument hat

Verfügbare Endpunkte:

GET /shared_attachments
GET /shared_attachments/<id>
PUT /shared_attachments/<id>

POST /shared_attachments

Sie erzeugen einen neuen Link für ein Dokument.

Request-Parameter:

attachment_id (erforderlich): Die ID des Dokuments
category (optional): "original" oder "viewable" (Standard: "original")
valid_until (optional): Gültigkeitsdatum im ISO-Format (ohne Angabe: unbegrenzt gültig)
description (optional): String-Feld (max. 255 Zeichen)

Hinweis zu category:

"original": Download des Original-Dokuments
"viewable": Download einer PDF-Vorschau (falls erzeugt)

Erforderliche Berechtigung:

Sie benötigen in Ihrer Rolle Zugriff auf den Befehl "Dokumente teilen".

Beispiel-Request:

{
  "attachment_id": "006246fb-95ec-ed9f-de79-79604a88c85d",
  "category": "original",
  "valid_until": "2030-05-31"
}

Beispiel-Antwort:

{
  "data": {
    "id": "690035fc-d9f4-4229-8667-6b0e1eefd7d2",
    "attachment_id": "006246fb-95ec-ed9f-de79-79604a88c85d",
    "category": "original",
    "url": "http://archiv.example.com/public/attachment/690035fc-d9f4-4229-8667-6b0e1eefd7d2/Test.pdf",
    "valid_until": "2030-05-31"
  }
}

Die URL in der Antwort:

Dies ist der serverseitig erzeugte Link. Die zufällige id im Link ermöglicht den Zugriff. Sie können diese id verwenden, um den Link zu löschen.

DELETE /shared_attachments/<id>

Sie löschen den Dokumenten-Link mit der angegebenen ID.

Öffentliche Links für Vorgänge

Sie können Links für einzelne Vorgänge erzeugen. Diese Links ermöglichen den Zugriff auf Vorgangsinformationen und Dokumente ohne Benutzeranmeldung.

Wichtig:

Links sind mit dem erzeugenden Benutzer verknüpft
Links funktionieren nur, solange der Benutzer Zugriff auf den Vorgang hat

Verfügbare Endpunkte:

GET /shared_records
GET /shared_records/<id>
PUT /shared_records/<id>

POST /shared_records

Sie erzeugen einen neuen Link für einen Vorgang.

Request-Parameter:

record_id (erforderlich): Die ID des Vorgangs
valid_until (optional): Gültigkeitsdatum im ISO-Format (ohne Angabe: unbegrenzt gültig)
description (optional): String-Feld (max. 255 Zeichen)

Erforderliche Berechtigung:

Sie benötigen in Ihrer Rolle Zugriff auf den Befehl "Vorgänge teilen".

Beispiel-Request:

{
  "description": "Kunde: XYZ",
  "record_id": "006246fb-95ec-ed9f-de79-79604a88c46f",
  "valid_until": "2030-05-31"
}

Beispiel-Antwort:

{
  "data": {
    "creation_date": "2023-10-24T09:58:32.348974+02:00",
    "description": "Kunde: XYZ",
    "id": "690035fc-d9f4-4229-8667-6b0e1eefd7f6",
    "record_id": "006246fb-95ec-ed9f-de79-79604a88c46f",
    "url": "http://archiv.example.com/public/record/690035fc-d9f4-4229-8667-6b0e1eefd7f6",
    "valid_until": "2030-05-31"
  }
}

Die URL in der Antwort:

Dies ist der serverseitig erzeugte Link. Die zufällige id im Link ermöglicht den Zugriff. Sie können diese id verwenden, um den Link zu löschen.

DELETE /shared_records/<id>

Sie löschen den Vorgangs-Link mit der angegebenen ID.

Verwandte Artikel

Konfiguration - Allgemeine Archivstruktur

Einrichten einer Hotfolder.ini

Hotfolder-Ausführung mit pa_hotfolder.exe

SmartSafe

Generischer API-Client

API - Übersicht

API-Dokumentation

Übersicht zur Web-Schnittstelle

Grundprinzipien

HTTP-Methoden

Zeichenkodierung

Datenformat

JSON-Struktur

Alternatives Format: multipart/form-data

URL-Format und Versionierung

Basis-URL

Versionsunterstützung

Versionen abfragen

Empfohlenes Vorgehen

Fehlerbehandlung bei veralteten Versionen

Relative URLs

Allgemeine API-Struktur

Standard-Endpunkte

GET-Requests

POST, PUT und DELETE

Listen-Antworten

Struktur

Limits und Paginierung

Sortierung

Filterung

Einzelne Datensätze

Benutzer-Authentifizierung

Authentifizierungspflicht

Zwei Benutzertypen

Anmeldung für reguläre Benutzer

POST /login

Zwei-Faktor-Authentifizierung

Vertrauenswürdige Geräte

Archive abfragen

GET /viewer_archives

GET /viewer_archives/<archive_id>

Vorgänge abfragen

GET /records?archive_id=<archive_id>

GET /records/<record_id>

Neueste Vorgangsversion ermitteln

GET /record_version/<record_id>

Workflow-Übergang ausführen

Was ist ein Workflow-Übergang?

Request-Parameter

Übergangs-ID ermitteln

Übergang ausführen: POST /execute_transition

Antwort des Servers

Fehlerfall

Dokumente herunterladen

GET /attachments/<attachment_id>

Vorgänge archivieren

Archivierungsprozess

POST /chunk

POST /upload

POST /records

PUT /records/<record_id>

Öffentliche Links

Öffentliche Links für Dokumente

POST /shared_attachments

DELETE /shared_attachments/<id>

Öffentliche Links für Vorgänge

POST /shared_records

DELETE /shared_records/<id>

Übergang ausführen: `POST /execute_transition`