API-Dokumentation

Funktionsumfang der API

Die REST-API bietet folgende Funktionen:

Die API wird unter einer Adresse nach dem Muster https://<server>/<webapp>/api/v1/ erreicht. Mit den nachfolgend angegebenen Pfaden wird die URL ergänzt.

Authentifizierung

Um einen Client zu berechtigen, muss zunächst im DMS eine entsprechende Berechtigung eingetragen werden. Dies geschieht mit der Funktion Client-Zugangscode anlegen.

Der für den Client zuständige Administrator bzw. Benutzer, kann sich mit diesem Zugangscode registrieren. Bei der Registrierung erhält er eine Client-ID und ein Client-Secret. Mit diese Angaben kann er mit dem Client Credential Flow aus OAuth2 ein Access Token anfordern.

Das so ermittelte Access Token kann für die Nutzung der API entspreched der im DMS eingetragenen Rolle verwendet werden. Das Token ist 360 Tage gültig. Falls es nicht mehr benötigt wird oder der Verdacht auf Offenbarung besteht, kann es im DMS deaktiviert werden.

Status Codes

Folgende Status Codes werden bei erfolgreicher Verarbeitung zurückgesendet:

Status Beschreibung
200 Ok
206 Teilergebnis
207 Multipart Request (Ergebis zur einzelnen Verarbeitung im Body)

Folgende allgemeine Status Codes können bei jedem Request als Antwort kommen:

Status Beschreibung
400 Fehlerhafter Request
401 Request ohne gültige Autorisierung
405 Ungültige Methode für den Aufruf verwendet
429 Zu viele Requests je Zeitintervall
500 Interner Serverfehler
501 Funktion nicht implementiert oder API im DMS nicht aktiviert

Weitere verwendete Status Codes sind bei den einzelnen Funktionen aufgezählt.

Token anfragen

Diese Funktion ermöglicht die Anfrage eines Tokens zur Authentifizierung.

Request

Endpunkt

POST /oauth2/token

keine

Parameter

Parameter Beschreibung cURL-Beispiel
grant_type Autorisierungstyp grant_type=client_credentials
client_id Client-ID client_id=<id>
client_secret Client-Geheimnis client_secret=<secret>

Beispiel

curl -X POST \
"https://www.example.com/dms12345/api/v1/oauth2/token" \
-F grant_type=client_credentials \
-F client_id=<id> \
-F client_secret=<secret>

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Allgemeine Status Codes

Beispiel

{
  "access_token": "612b1fc5206fcf357ca2f5e06924ec7a",
  "token_type": "bearer",
  "expires_in": 31104000
}

Informationen zur API erhalten

Durch diese Funktion können Informationen zu den Endpunkten der API erhalten werden.

Request

Endpunkt

GET /info

Header

Authorization: Bearer <token>

Parameter

keine

Beispiel

curl -X GET \
"https://www.example.com/dms12345/api/v1/info" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Allgemeine Status Codes

Model

endpoints Liste von Endpoints mit methods und path

Beispiel

{
  "endpoints": [
    {
      "methods": "POST",
      "path": "/oauth2/token"
    },
    {
      "methods": "GET",
      "path": "/info"
    },
    {
      "methods": "GET",
      "path": "/permissions"
    },
    {
      "methods": "GET",
      "path": "/teams/Administration/info"
    },
    {
      "methods": "POST",
      "path": "/teams/Administration/admin_message"
    },
    {
      "methods": "GET, PUT",
      "path": "/teams/{team_name}/boxes/{box_name}/documents/{document_no}"
    },
    {
      "methods": "GET, POST",
      "path": "/teams/{team_name}/boxes/{box_name}/documents"
    },
    {
      "methods": "GET, PUT",
      "path": "/teams/{team_name}/boxes/{box_name}/documents/{document_no}/info"
    },
    {
      "methods": "POST",
      "path": "/teams/{team_name}/document_move"
    }
  ]
}

Endpunkte

POST /oauth2/token Token zur Authentifizierung anfragen
GET /info Informationen zu den Endpunkten
GET /permissions Teamnamen und Berechtigungen
GET /teams/Administration/info Version und Instanz der API
POST /teams/Administration/admin_message Nachricht an angemeldete Benutzer
GET /teams/{team_name}/boxes/{box_name}/documents/{document_no} Herunterladen von Dokumenten
PUT /teams/{team_name}/boxes/{box_name}/documents/{document_no} Versionieren von Dokumenten
GET /teams/{team_name}/boxes/{box_name}/documents Suchen von Dokumenten
POST /teams/{team_name}/boxes/{box_name}/documents Hochladen von Dokumenten
GET /teams/{team_name}/boxes/{box_name}/documents/{document_no}/info Abfrage der Metainformationen
PUT /teams/{team_name}/boxes/{box_name}/documents/{document_no}/info Dokument-Metadaten bearbeiten
POST /teams/{team_name}/document_move Verschieben von Dokumenten

Berechtigungen abfragen

Mit dieser Funktion können die Berechtigungen der verschiedenen Teams des DMS abgefragt werden.

Request

Endpunkt

GET /permissions

Header

Authorization: Bearer <token>

Parameter

keine

Beispiel

curl -X GET \
"https://www.example.com/dms12345/api/v1/permissions" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Allgemeine Status Codes

Model

permissions Zuordnung von Teamnamen zu Berechtigungslisten

Beispiel

{
  "permissions": {
    "Verwaltung": [
      "writeinbox",
      "readrecent",
      "writeshelf"
    ],
    "Buchhaltung": [
      "writeinbox"
    ]
  }
}

Berechtigungen

Die Berechtigungen können der Dokumentation des DMS entnommen werden, u. a. unter https://www.advernet.de/rollen.html.

Administrator-Informationen

Über diese Funktion können Informationen zur Version und Instanz der API abgefragt werden.

Request

Endpunkt

GET /teams/Administration/info

Header

Authorization: Bearer <token>

Parameter

keine

Beispiel

curl -X GET \
"https://www.example.com/dms12345/api/v1/teams/Administration/info" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt

Beispiel

{
  "application": "Advernet.de DMS",
  "version": "2.1.0",
  "instance": "0123-4567",
  "testversion": true
}

Administratornachricht

Diese Funktion ermöglicht das Senden einer Nachricht an alle angemeldeten Benutzer.

Request

Endpunkt

POST /teams/Administration/admin_message

Header

Authorization: Bearer <token>

Parameter

Parameter Beschreibung cURL-Beispiel
message Nachricht message=“Testnachricht”

Beispiel

curl -X POST \
"https://www.example.com/dms12345/api/v1/teams/Administration/admin_message" \
-F message="Testnachricht" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
503 Service steht derzeit nicht zur Verfügung

Beispiel

{
  "success": true
}

Dokumenteninformationen abfragen

Diese Funktion ermöglicht die Abfrage der Metainformationen eines Dokumentes.

Request

Endpunkt

GET /teams/<team>/boxes/<box>/documents/<document_no>/info

Header

Authorization: Bearer <token>

Parameter

Parameter Beschreibung Beispiel
team Team Verwaltung
box Ablagefach Eingang
document_no Dokumentennummer 35

Beispiel

curl -X GET \
"https://www.example.com/dms12345/api/v1/teams/Verwaltung/boxes/Eingang/documents/35/info" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden

Model

Liste der Suchergebnisse

documents Liste mit Info zu Einzeldokument

Info zu Einzeldokument

document_no Integer
document_type String
document_date String (yyyy-mm-dd)
document_tags Liste von Strings
document_stamp_text String
document_stamp_color String
document_is_locked Boolean
document_note String
file_name String
file_size String
file_hash String
meta_hash String

Beispiel

{
  "documents": [
    {
      "document_no": 35,
      "document_type": "Bericht",
      "document_date": "2019-09-11",
      "document_tags": [
        "Statusbericht"
      ],
      "document_stamp_text": "neu",
      "document_stamp_color": "red",
      "document_is_locked": false,
      "file_name": "Status_und_Konfiguration.pdf",
      "file_size": 26310,
      "file_hash": "26ac87b094e2575d8fb35fa087fba70b7d530ec5ece46e2971844d09f3126278",
      "meta_hash": "84f848e4b1e58f4d314428a9179774d9d03bc781fed30907864f7b798dbd6ae9"
    }
  ]
}

Metadaten ändern

Diese Funktion ermöglicht das Bearbeiten der Metadaten eines Dokumentes.

Request

Endpunkt

PUT /teams/<team>/boxes/<box>/documents/<document_no>/info

Header

Authorization: Bearer <token>

Content-Type: application/json; charset=utf-8

Parameter

Parameter Beschreibung cURL-Beispiel
info.json JSON-Datei mit Informationen zum zu bearbeitenden Dokument @info.json
team Team Verwaltung
box Ablagefach Eingang
document_no Dokumentennummer 29

Beispiel

curl -X PUT \
"https://www.example.com/dms12345/api/v1/teams/Verwaltung/boxes/Eingang/documents/29/info" \
-d @info.json \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json; charset=utf-8"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

JSON-Datei

{
  "documents": [
    {
      "meta_hash": "<meta_hash>"
    },
    {
      "document_type": "<document_type>"
    }
  ]
}

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden
409 Request kann aufgrund von Konflikten nicht bearbeitet werden
415 Nicht unterstütztes Format
423 Ressource ist gesperrt

Beispiel

{
  "success": true
}

Dokument herunterladen

Diese Funktion ermöglicht das Herunterladen eines Dokumentes aus einem bestimmten Ablagefach.

Request

Endpunkt

GET /teams/<team>/boxes/<box>/documents/<document_no>

Header

Authorization: Bearer <token>

Parameter

Parameter Beschreibung Beispiel
team Team Einkauf
box Ablagefach Ablage
document_no Dokumentennummer 7

Beispiel

curl -X GET \
"https://www.example.com/dms12345/api/v1/teams/Einkauf/boxes/Ablage/documents/7" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden

Beispiel

Das Ergebnis ist die angeforderte Datei.

Dokumente hochladen

Diese Funktion ermöglicht das Hochladen von Dokumenten.

Request

Endpunkt

POST /teams/<team>/boxes/Eingang/documents/

Header

Authorization: Bearer <token>

Content-Type: multipart/form-data

Parameter

Parameter Beschreibung cURL-Beispiel
file Hochzuladende Datei file=@files/testB1.pdf
team Team Einkauf

Beispiel

curl -X POST \
"https://www.example.com/dms12345/api/v1/teams/Einkauf/boxes/Eingang/documents/" \
-F file=@files/testB1.pdf \
-F file=@files/testB2.pdf \
-F file=@files/testB3.pdf \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
415 Nicht unterstütztes Format

Bei Erfolg wird der Status 207 gesendet. Nähere Angaben zur Verarbeitung der einzelnen Teile ist im Body angegeben.

Model

results Liste von Statusobjekten für die einzelnen Dateien

Beispiel

{
  "results": [
    {
      "status": 201,
      "description": "uploaded",
      "file_name": "testB1.pdf",
      "hash": "c856c9141f909a1365345c604f43bc2f9ceab52a06049442eee1f833c6acde26",
      "href": "/teams/Einkauf/boxes/Eingang/documents/36"
    },
    {
      "status": 201,
      "description": "uploaded",
      "file_name": "testB2.pdf",
      "hash": "44060cb32a2f0159686cf1d3e79102b0c83660fd8a702fdb2a3d3ad42d667ea5",
      "href": "/teams/Einkauf/boxes/Eingang/documents/37"
    },
    {
      "status": 201,
      "description": "uploaded",
      "file_name": "testB3.pdf",
      "hash": "8655d776d190dff808c8ab4f8811694a2d6a225127aaf8fd8aad8ba993a0f891",
      "href": "/teams/Einkauf/boxes/Eingang/documents/38"
    }
  ]
}

Dokumentensuche

Diese Funktion ermöglicht das Suchen von Dokumenten in einem bestimmten Ablagefach eines Teams im DMS.

Request

Endpunkt

GET /teams/<team>/boxes/<box>/documents

Header

Authorization: Bearer <token>

Parameter

Parameter Beschreibung cURL-Beispiel
date Dokumentendatum date=2019-09-11
date_from Anfang Datumsbereich date_from=2019-03-12
date_to Ende Datumsbereich date_to=2019-05-27
document_type Dokumententyp document_type=Bericht
tag Schlagwort (mehrere möglich) tag=Testfall
team Team Einkauf
box Ablagefach Aktuell
no_metadata Suchergebnis ohne Metadaten* no_metadata=true

* Bei Verwendung des optionalen Parameters no_metadata=true kann die Liste der Dokumente im Suchergebnis auf die Angabe von Dokumentennummer (document_no) und Dateiname (file_name) eingeschränkt werden. file_name wird dabei aus Dokumentennummer und Dateinamenserweiterung, wenn vorhanden, zusammengesetzt.

Beispiel

curl -G -X GET \
"https://www.example.com/dms12345/api/v1/teams/Einkauf/boxes/Aktuell/documents/" \
-d "document_type=Bericht&tag=Testfall&tag=Beispiel" \
-H "Authorization: Bearer <token>"

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden
422 Request kann nicht verarbeitet werden

Model

Liste der Suchergebnisse

documents Liste mit Info zu Einzeldokument

Info zu Einzeldokument

document_no Integer
document_type String
document_date String (yyyy-mm-dd)
document_tags Liste von Strings
document_stamp_text String
document_stamp_color String
document_is_locked Boolean
document_note String
file_name String
file_size String
file_hash String
meta_hash String

Beispiel

{
  "documents": [
    {
      "document_no": 46,
      "document_type": "Bericht",
      "document_date": "2019-04-25",
      "document_tags": [
        "Testfall"
      ],
      "document_is_locked": false,
      "file_name": "testB8.pdf",
      "file_size": 10180,
      "file_hash": "47e9183b6890a9363b7d9ee035d1d70d83995e8c00799e5b16717ca8e37ddc77",
      "meta_hash": "6af50eca4628ef117f49bdef27b0aed4e9b263425577cc83c80627ea9297e546"
    },
    {
      "document_no": 1,
      "document_type": "Bericht",
      "document_date": "2019-09-20",
      "document_tags": [
        "Statusbericht",
        "Testfall"
      ],
      "document_is_locked": false,
      "file_name": "Status_und_Konfiguration.pdf",
      "file_size": 26169,
      "file_hash": "40b93a1b317ed0aaf7fa373f01566ae372440d101cb6e2f57f897e66d44a6b69",
      "meta_hash": "add00761005de6d08af750ba44f7256698c44802b9fed2e57f9cbabba32c601b"
    }
  ]
}

Dokument verschieben

Diese Funktion ermöglicht das Verschieben eines Dokumentes in ein anderes Ablagefach.

Request

Endpunkt

POST /teams/<team>/document_move/

Header

Authorization: Bearer <token>

Content-Type: multipart/form-data

Parameter

Parameter Beschreibung cURL-Beispiel
document_no Dokumentennummer document_no=29
from_box Start-Ablagefach from_box=Eingang
to_box Ziel-Ablagefach to_box=Aktuell
team Team Buchhaltung

Beispiel

curl -X POST \
"https://www.example.com/dms12345/api/v1/teams/Buchhaltung/document_move/" \
-F "document_no=29" \
-F "from_box=Eingang" \
-F "to_box=Aktuell" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden
422 Request kann nicht verarbeitet werden
423 Ressource ist gesperrt

Beispiel

{
  "success": true
}

Dokumente versionieren

Diese Funktion ermöglicht das Versionieren von Dokumenten.

Request

Endpunkt

PUT /teams/<team>/boxes/<box>/documents/<document_no>

Header

Authorization: Bearer <token>

Parameter

Parameter Beschreibung cURL-Beispiel
hash meta-hash des zu versionierenden Dokumentes hash=@hash.json; type=application/json
file neue Version des Dokumentes file=@files/testA32.pdf
team Team Administration
box Ablagefach Eingang
document_no Dokumentennummer 3

Beispiel

curl -X PUT \
"https://www.example.com/dms12345/api/v1/teams/Administration/boxes/Eingang/documents/3" \
-F "hash=@hash.json; type=application/json" \
-F "file=@files/testA32.pdf" \
-H "Authorization: Bearer <token>"

[Zeilenumbrüche dienen lediglich der besseren Lesbarkeit.]

JSON-Datei

{
      "meta_hash": "<meta_hash>"
}

Response

Status

Status Beschreibung
403 Zugriff nicht erlaubt
404 Ressource nicht gefunden
409 Request kann aufgrund von Konflikten nicht verarbeitet werden
415 Nicht unterstütztes Format
422 Request kann nicht verarbeitet werden
423 Ressource ist gesperrt

Beispiel

{
  "success": true
}

Bei Fragen zur API nehmen Sie bitte Kontakt zu uns auf!

040 228692950 oder info@advernet.de
(Informationen zu E-Mail-Verschlüsselung)