API-Dokumentation

Dokumentation zu Advernet.de DMS 2.4

Funktionsumfang der API
Authentifizierung
Status Codes
Token anfragen
Informationen zur API erhalten
Berechtigungen abfragen
Administrator-Informationen
Administratornachricht
Dokumenteninformationen abfragen
Metadaten ändern
Dokument herunterladen
Dokumente hochladen
Dokumentensuche
Dokument verschieben
Dokumente versionieren

Funktionsumfang der API

Die REST-API bietet folgende Funktionen:

Access Token abfragen
Informationen zu den Endpunkten abfragen
Eigene Berechtigungen abfragen
Version und Instanz-ID der Anwendung abfragen
Nachricht an alle angemeldeten Benutzer senden
Dokument herunterladen
Neue Dokumentenversion hochladen
Dokument suchen
Neues Dokument hochladen
Metadaten eines Dokumentes abfragen
Metadaten eines Dokumentes aktualisieren
Dokument in ein anderes Ablagefach verschieben

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 Benutzer und Rollen oder 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
}

Zurück zum Seitenanfang

Stand 10.10.2024