Integrations-API

Referenz: Dokumente

Alle Endpunkte für Dokumente – Parameter, Felder, Beispiele und Fehler.

Basisadresse: https://<Ihre CMS-Adresse>/api/ext/v1. Jede Anfrage braucht Authorization: Bearer <Schlüssel>. Berechtigung sagt, was der Schlüssel braucht.

Das Dokument-Objekt

uuid

Die ID in DDM.

externalRef

string | null

Die Referenz, mit der es eingespielt wurde.

sourceId

uuid | null

Die Push-Quelle oder der Konnektor, über die es kam.

name

string

Der Dateiname, mit Endung.

fileType

string

Die Endung, z. B. pdf.

mimeType

string | null

sizeBytes

integer

status

draft | in_review | approved | archived

shareable

boolean

Ob Leser es weitergeben, in anderen Apps öffnen oder herunterladen dürfen.

highlighted

boolean

Jetzt hervorgehoben: von jemandem nach vorn gestellt, oder innerhalb seines Hervorhebungs-Zeitraums.

availableFrom, availableUntil

date-time | null

Leser sehen das Dokument nur in diesem Zeitraum. Jedes Ende darf offen bleiben.

highlightFrom, highlightUntil

date-time | null

In diesem Zeitraum ist das Dokument von selbst hervorgehoben.

watermarked

boolean

Jede Kopie, die ein Leser ansieht oder herunterlädt, trägt seine E-Mail-Adresse quer über jede Seite. Nur PDFs und Office-Dateien; ein Dokument mit Wasserzeichen kann nicht per Link geteilt werden.

titles

object

Ein Titel pro Marktcode.

`PUT /documents/ref/{ref}` – einspielen

Berechtigung Schreiben. Legt das Dokument mit dieser Referenz in der Push-Quelle des Schlüssels an, oder aktualisiert es. Siehe Dokumente einspielen.

Inhalt: multipart/form-data mit

file

file required

Die Datei. Bis zur maximalen Dateigröße des Tarifs.

metadata

JSON-Text

name, categoryPath, categoryIds, categoryRefs, mimeType, tags, titles, groupName – alle optional. Mit categoryIds und/oder categoryRefs liegt das Dokument genau dort, mit categoryPath zusätzlich in der Kategorie des Pfads.

oder application/json mit denselben Feldern wie metadata, plus

fileUrl

string required

Eine HTTP(S)-Adresse, von der DDM die Datei lädt – bis zur maximalen Dateigröße des Tarifs, wie beim Hochladen.

Antwort: 201 (angelegt) oder 200, mit { "outcome": "created" | "versioned" | "unchanged" | "skipped", "document": Dokument | null }.

Fehler: 400 ungültige Angaben · 403 Nur-Lesen-Schlüssel, Push-Quelle fehlt oder ist aus, fehlende Rechte · 409 eine Freigabe läuft · 413 Datei zu groß oder Speicher voll · 415 falscher Content-Type · 422 fileUrl nicht ladbar.

Anfrage

curl -X PUT "https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711" \
  -H "Authorization: Bearer $DDM_API_KEY" \
  -F "file=@Price-list-2026.pdf;type=application/pdf" \
  -F 'metadata={"categoryPath": "Products/Price lists", "tags": ["Prices", "2026"], "titles": {"DE": "Preisliste 2026"}};type=application/json'

Antwort · 201 Created

{
  "outcome": "created",
  "document": {
    "id": "dc8594e0-0ead-4049-aaee-2ef899bcf76f",
    "externalRef": "PIM-4711",
    "sourceId": "5d02b7aa-5175-42e9-9277-aa19063833f2",
    "name": "Price-list-2026.pdf",
    "fileType": "pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 589,
    "status": "draft",
    "shareable": true,
    "highlighted": false,
    "titles": {
      "DE": "Preisliste 2026"
    },
    "tags": [
      "2026",
      "Prices"
    ],
    "categoryIds": [
      "078a554f-19a2-4285-b854-8546de01f815"
    ],
    "currentVersion": {
      "id": "b5a8ce67-c8f1-439a-aadb-86e1b73223e2",
      "versionNo": 1,
      "checksum": "5db6ba22797a193286fdebf4919730b4571146bde75bb4ad3dc856a38f2f71c1",
      "sizeBytes": 589,
      "mimeType": "application/pdf",
      "createdAt": "2026-10-27T20:01:46.510Z"
    },
    "createdAt": "2026-10-27T20:01:46.510Z",
    "updatedAt": "2026-10-27T20:01:46.838Z"
  }
}

Dieselbe Datei noch einmal, dann eine geänderte:

200, "outcome": "unchanged" – dieselbe Version
200, "outcome": "versioned" – currentVersion.versionNo ist jetzt 2

`PUT /documents/{id}` – neue Bytes über die id

Berechtigung Schreiben. Dieselben Inhalte wie beim Einspielen – Multipart mit file und metadata oder JSON mit fileUrl –, aber für ein Dokument, das Sie über die id von DDM ansprechen:

Gehört es zur Push-Quelle des Schlüssels, ist es dasselbe wie PUT /documents/ref/{ref} mit seiner Referenz – mit den Regeln der Quelle.
Jedes andere Dokument, z. B. eines, das im CMS hochgeladen wurde, bekommt eine neue Version wie bei einem Upload. tags, titles, categoryIds und categoryRefs gelten wie beim Einspielen.

Antwort: 200 mit outcome und dem Dokument.

`GET /documents` – Liste und Änderungsfeed

Berechtigung Lesen. Die Dokumente, die der Schlüssel sieht, älteste Änderung zuerst.

limit

1–500

Seitengröße, Standard 100.

cursor

string

nextCursor der vorigen Seite.

updatedSince

date-time

Nur Dokumente, die zu oder nach diesem Zeitpunkt geändert wurden.

categoryId

uuid

Nur Dokumente in dieser Kategorie.

categoryRef

string

Dieselbe Kategorie über ihre Referenz, statt categoryId.

deep

boolean

Mit categoryId oder categoryRef: die Kategorien darunter einschließen.

externalRef

string

Nur Dokumente mit dieser Referenz.

tag

string

Nur Dokumente mit diesem Schlagwort.

status

draft | in_review | approved | archived

own

boolean

Nur Dokumente, die über die Push-Quelle dieses Schlüssels kamen.

Antwort: { "data": Dokument[], "nextCursor": string | null }.

Anfrage

curl "https://ddm.example.com/api/ext/v1/documents?limit=2&own=true" \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK

{
  "data": [
    {
      "id": "dc8594e0-0ead-4049-aaee-2ef899bcf76f",
      "externalRef": "PIM-4711",
      "sourceId": "5d02b7aa-5175-42e9-9277-aa19063833f2",
      "name": "Price-list-2026.pdf",
      "fileType": "pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 605,
      "status": "draft",
      "shareable": true,
      "highlighted": false,
      "titles": {
        "DE": "Preisliste 2026"
      },
      "tags": [
        "2026",
        "Prices"
      ],
      "categoryIds": [
        "078a554f-19a2-4285-b854-8546de01f815"
      ],
      "currentVersion": {
        "id": "1730e7bb-2f98-4761-aa9b-964c521351b3",
        "versionNo": 2,
        "checksum": "0bcb7c3b4886f699a985563d7bc9476bf75b4af35a57ff959f46c37e386cf54f",
        "sizeBytes": 605,
        "mimeType": "application/pdf",
        "createdAt": "2026-10-27T20:01:46.904Z"
      },
      "createdAt": "2026-10-27T20:01:46.510Z",
      "updatedAt": "2026-10-27T20:01:47.169Z"
    }
  ],
  "nextCursor": null
}

`GET /documents/{id}` · `GET /documents/ref/{ref}`

Berechtigung Lesen. Ein Dokument. 404, wenn es nicht existiert oder der Schlüssel es nicht sieht. Über die Referenz nur innerhalb der Push-Quelle des Schlüssels.

Anfrage

curl https://ddm.example.com/api/ext/v1/documents/dc8594e0-0ead-4049-aaee-2ef899bcf76f \
  -H "Authorization: Bearer $DDM_API_KEY"

curl https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711 \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK

{
  "id": "dc8594e0-0ead-4049-aaee-2ef899bcf76f",
  "externalRef": "PIM-4711",
  "sourceId": "5d02b7aa-5175-42e9-9277-aa19063833f2",
  "name": "Price-list-2026.pdf",
  "fileType": "pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 605,
  "status": "draft",
  "shareable": true,
  "highlighted": false,
  "titles": {
    "DE": "Preisliste 2026"
  },
  "tags": [
    "2026",
    "Prices"
  ],
  "categoryIds": [
    "078a554f-19a2-4285-b854-8546de01f815"
  ],
  "currentVersion": {
    "id": "1730e7bb-2f98-4761-aa9b-964c521351b3",
    "versionNo": 2,
    "checksum": "0bcb7c3b4886f699a985563d7bc9476bf75b4af35a57ff959f46c37e386cf54f",
    "sizeBytes": 605,
    "mimeType": "application/pdf",
    "createdAt": "2026-10-27T20:01:46.904Z"
  },
  "createdAt": "2026-10-27T20:01:46.510Z",
  "updatedAt": "2026-10-27T20:01:47.169Z"
}

`PATCH /documents/{id}` · `PATCH /documents/ref/{ref}`

Berechtigung Schreiben. Ändert nur, was gesendet wird:

name

string

status

archived | draft

Archivieren oder zurückholen. Freigabe-Status setzt nur der Freigabeablauf.

shareable

boolean

highlighted

boolean

availableFrom, availableUntil, highlightFrom, highlightUntil

date-time | null

Verfügbarkeits- und Hervorhebungs-Zeitraum; null entfernt ein Ende.

watermarked

boolean

Die E-Mail-Adresse jedes Lesers auf die Seiten setzen, die er bekommt. Nur PDFs und Office-Dateien.

`DELETE /documents/{id}` · `DELETE /documents/ref/{ref}`

Berechtigung Schreiben. Löscht das Dokument. Antwort: 204. Fehler: 403, 404, 409 (Aufbewahrungsschutz, Freigabe läuft).

Anfrage

curl -X DELETE https://ddm.example.com/api/ext/v1/documents/dc8594e0-0ead-4049-aaee-2ef899bcf76f \
  -H "Authorization: Bearer $DDM_API_KEY"

curl -X DELETE https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711 \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 204 No Content – Kein Inhalt.

`GET /documents/{id}/content` · `GET /documents/ref/{ref}/content`

Berechtigung Lesen. Die Datei.

versionId

uuid

Eine bestimmte Version; Standard ist die aktuelle.

Header: Range, If-None-Match. Antwort: 200, 206 oder 304, mit Content-Type, Content-Length, ETag und Content-Disposition. Mit einem Schlüssel für freigegebene Inhalte lassen sich nur Dokumente herunterladen, die die App verlassen dürfen (shareable), sonst 403.

Anfrage

curl -o Price-list-2026.pdf -D - \
  https://ddm.example.com/api/ext/v1/documents/dc8594e0-0ead-4049-aaee-2ef899bcf76f/content \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK – Header der Antwort – der Inhalt ist die Datei selbst:

HTTP/1.1 200 OK
accept-ranges: bytes
content-disposition: attachment; filename="Price-list-2026.pdf"; filename*=UTF-8''Price-list-2026.pdf
content-length: 605
content-type: application/pdf
etag: "1730e7bb-2f98-4761-aa9b-964c521351b3"

Mit dem letzten ETag als If-None-Match antwortet eine unveränderte Datei ohne Inhalt:

HTTP/1.1 304 Not Modified
cache-control: private, max-age=300, must-revalidate
etag: "1730e7bb-2f98-4761-aa9b-964c521351b3"

Mit Range: bytes=0-99 nur ein Teil davon:

HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-disposition: attachment; filename="Price-list-2026.pdf"; filename*=UTF-8''Price-list-2026.pdf
content-length: 100
content-range: bytes 0-99/605
content-type: application/pdf
etag: "1730e7bb-2f98-4761-aa9b-964c521351b3"

`GET /documents/{id}/text` · `GET /documents/ref/{ref}/text`

Berechtigung Lesen. Der Text, den DDM aus der aktuellen Version gelesen hat, für einen Suchindex: { "versionId", "versionNo", "language", "content" }. Folgt den Regeln für Leser, auch bei einem Schlüssel, der alles sieht.

Anfrage

curl https://ddm.example.com/api/ext/v1/documents/dc8594e0-0ead-4049-aaee-2ef899bcf76f/text \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK

{
  "versionId": "1730e7bb-2f98-4761-aa9b-964c521351b3",
  "versionNo": 2,
  "language": null,
  "content": "Price list 2026, second edition"
}

`GET /documents/{id}/thumbnail` · `GET /documents/ref/{ref}/thumbnail`

Berechtigung Lesen. Das Vorschaubild der ersten Seite. versionId wie bei content.

Anfrage

curl -o preview.webp https://ddm.example.com/api/ext/v1/documents/dc8594e0-0ead-4049-aaee-2ef899bcf76f/thumbnail \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK – Header der Antwort – der Inhalt ist die Datei selbst:

HTTP/1.1 200 OK
cache-control: private, max-age=300, must-revalidate
content-length: 5052
content-type: image/webp
etag: "1730e7bb-2f98-4761-aa9b-964c521351b3"

Inhalte abrufen

Schritt für Schritt – ein Export-Skript, das die Dokumente von DDM in ein anderes System kopiert und es aktuell hält.

Referenz: Kategorien, Schlagwörter, Märkte

Die Endpunkte für Kategorien, und die Schlagwörter und Märkte, auf die sich Dokumente und Kategorien beziehen.