Ressource: files (DMS) #

Zugriff auf die Dokumente des EULANDA-DMS je Datensatz. Der physische Ordner wird serverseitig über die EulandaXtools-Kette aufgelöst (Get-DmsFolderAddress, Get-DmsFolderInvoice, …); Clients sehen nur relative Pfade. Existiert das DMS-Plugin (esol.DMS) in der Installation nicht, antworten alle Routen mit 409 DMS_NOT_AVAILABLE - geprüft wird das über den Registry-Key des Plugins.

Endpunkte #

Dieselben vier Routen gibt es je Entität unter deren Ressourcen-Pfad:

Ressource	Basis-Pfad	EULANDA-Objekt
Adressen	`/api/v1/addresses/{id}/files`	Adresse
Artikel	`/api/v1/articles/{id}/files`	Artikel
Angebote	`/api/v1/quotes/{id}/files`	Angebot
Aufträge	`/api/v1/sales-orders/{id}/files`	Auftrag
Lieferscheine	`/api/v1/delivery-notes/{id}/files`	Lieferschein
Rechnungen	`/api/v1/invoices/{id}/files`	Rechnung

{id} ist jeweils die interne Id des Datensatzes.

Methode	Pfad (relativ zum Basis-Pfad)	Scope	Zweck
GET	``	`dms:read`	Dateien und Unterordner listen
GET	`/download?path=...`	`dms:read`	Datei binär herunterladen
POST	`?name=...[&path=...][&overwrite=true]`	`dms:write`	Datei hochladen (Body = Roh-Inhalt)
DELETE	`?path=...`	`dms:delete`	Einzelne Datei löschen

Upload und Löschen haben bewusst eigene Scopes - ein reiner Lese-Client bekommt dms:read, ein Scanner-Arbeitsplatz zusätzlich dms:write, und dms:delete nur, wer wirklich aufräumen darf.

Sicherheitsregeln #

Endungs-Whitelist: nur pdf png jpg jpeg gif json xml md txt csv doc docx xls xlsx zip. Andere Dateien werden weder gelistet noch ausgeliefert, hochgeladen oder gelöscht (422 DMS_TYPE_NOT_ALLOWED).
Traversal-Schutz: relative Pfade werden kanonisiert; .., absolute Pfade und Sonderzeichen führen zu 400 DMS_PATH_INVALID. Die API kommt nie aus dem DMS-Ordner des Datensatzes heraus.
Upload-Limit: 25 MB (konfigurierbar, UploadLimitBytes).
Gelöscht werden nur Dateien, nie Ordner.

Beispiele #

Dateien der Adresse 14 (EULANDA) listen:

$h = @{ Authorization = "Bearer $key" }
Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/14/files' -Headers $h

curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses/14/files"

Antwort:

{
  "items": [
    {
      "name": "Anhängerlast.pdf",
      "path": "Anhängerlast.pdf",
      "sizeBytes": 249244,
      "modifiedAt": "2026-05-12T09:15:00",
      "mimeType": "application/pdf"
    }
  ],
  "folders": [],
  "total": 1,
  "path": ""
}

Unterordner listen bzw. rekursiv über alles:

Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/14/files?path=Eingang' -Headers $h
Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/14/files?recursive=true' -Headers $h

curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses/14/files?path=Eingang"
curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses/14/files?recursive=true"

Herunterladen (Umlaute im Namen URL-kodieren):

$name = [uri]::EscapeDataString('Anhängerlast.pdf')
Invoke-WebRequest "http://localhost:8100/api/v1/addresses/14/files/download?path=$name" `
    -Headers $h -OutFile 'C:\Temp\Anhängerlast.pdf'

curl.exe -H "Authorization: Bearer %KEY%" -o Anhaengerlast.pdf "http://localhost:8100/api/v1/addresses/14/files/download?path=Anh%C3%A4ngerlast.pdf"

Hochladen (Body = Dateiinhalt, kein Multipart nötig):

Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/14/files?name=vertrag.pdf&path=Eingang' `
    -Method Post -Headers $h -ContentType 'application/pdf' `
    -InFile 'C:\Scans\vertrag.pdf'

curl.exe -X POST -H "Authorization: Bearer %KEY%" -H "Content-Type: application/pdf" --data-binary "@C:\Scans\vertrag.pdf" "http://localhost:8100/api/v1/addresses/14/files?name=vertrag.pdf&path=Eingang"

Löschen (braucht dms:delete):

Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/14/files?path=Eingang/vertrag.pdf' `
    -Method Delete -Headers $h

curl.exe -X DELETE -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses/14/files?path=Eingang/vertrag.pdf"

Fehlercodes dieser Ressource #

HTTP	Code	Bedeutung
400	`DMS_PATH_INVALID`	Pfad ungültig oder außerhalb des DMS-Ordners
400	`VALIDATION_QUERY_MISSING`	Pflicht-Parameter (`path` bzw. `name`) fehlt
404	`DMS_FILE_NOT_FOUND`	Datei existiert nicht
404	`NOT_FOUND`	Datensatz (z.B. Adresse) existiert nicht
409	`DMS_NOT_AVAILABLE`	DMS-Plugin in dieser Installation nicht vorhanden
409	`DMS_FILE_EXISTS`	Datei existiert, `overwrite=true` fehlt
413	`PAYLOAD_TOO_LARGE`	Upload über dem Limit
422	`DMS_TYPE_NOT_ALLOWED`	Endung nicht auf der Whitelist