Dokumente einspielen

Einspielen heißt: Das andere System schickt jedes Dokument selbst an DDM, mit seiner eigenen Referenz. Dasselbe Dokument noch einmal geschickt ist in DDM dasselbe Dokument: Unveränderte Bytes bewirken nichts, neue Bytes werden eine neue Version.

1. Eine Push-Quelle einrichten

Unter Einstellungen › Externe Quellen auf Neue Quelle klicken und den Systemtyp Push (externe API) wählen. Eine Push-Quelle hat nichts, womit sie sich verbindet. Ihre Einstellungen legen fest, wie eingespielte Dokumente abgelegt werden, genau wie bei einem Konnektor:

Schalten Sie die Quelle ein. Eingespieltes an eine ausgeschaltete Quelle wird mit 403 abgewiesen.

Die Einstellungen im Einzelnen stehen unter Externe Quellen.

2. Einen schreibenden Schlüssel anlegen

Unter Einstellungen › API-Zugang einen Schlüssel mit Schreiben anlegen und die Push-Quelle wählen. Eingespielte Dokumente gehören zu dieser Quelle, und ihre Referenzen sind darin eindeutig. Lassen Sie den Schlüssel als eine Person handeln, die in den Zielkategorien Dokumente anlegen darf – siehe Authentifizierung.

3. Ein Dokument einspielen

PUT /documents/ref/{ref} legt das Dokument an oder aktualisiert es. Schicken Sie die Datei als Multipart, die Angaben als JSON im Teil metadata:

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

import { readFile } from 'node:fs/promises'

const form = new FormData()
form.append('file', new Blob([await readFile('Preisliste-2026.pdf')], { type: 'application/pdf' }), 'Preisliste-2026.pdf')
form.append('metadata', JSON.stringify({
  categoryPath: 'Produkte/Preislisten',
  tags: ['Preise', '2026'],
  titles: { DE: 'Preisliste 2026', AT: 'Preisliste 2026' }
}))

const response = await fetch(`https://ddm.example.com/api/ext/v1/documents/ref/${encodeURIComponent('PIM-4711')}`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${process.env.DDM_API_KEY}` },
  body: form
})
const { outcome, document } = await response.json()

import json, os, requests
from urllib.parse import quote

with open("Preisliste-2026.pdf", "rb") as file:
    response = requests.put(
        f"https://ddm.example.com/api/ext/v1/documents/ref/{quote('PIM-4711', safe='')}",
        headers={"Authorization": f"Bearer {os.environ['DDM_API_KEY']}"},
        files={
            "file": ("Preisliste-2026.pdf", file, "application/pdf"),
            "metadata": (None, json.dumps({
                "categoryPath": "Produkte/Preislisten",
                "tags": ["Preise", "2026"],
                "titles": {"DE": "Preisliste 2026", "AT": "Preisliste 2026"},
            }), "application/json"),
        },
    )
result = response.json()

$form = @{
  file     = Get-Item "Preisliste-2026.pdf"
  metadata = '{"categoryPath":"Produkte/Preislisten","tags":["Preise","2026"]}'
}
Invoke-RestMethod -Method Put -Form $form `
  -Uri "https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711" `
  -Headers @{ Authorization = "Bearer $env:DDM_API_KEY" }

Die Antwort sagt, was geschehen ist, und zeigt das Dokument:

{
  "outcome": "created",
  "document": {
    "id": "8d0c1f5e-6c43-4f0e-9a52-0b7f1a2c3d4e",
    "externalRef": "PIM-4711",
    "name": "Preisliste-2026.pdf",
    "status": "draft",
    "tags": ["2026", "Preise"],
    "titles": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" },
    "categoryIds": ["2b5e…"],
    "currentVersion": { "versionNo": 1, "checksum": "9f86d0…", "sizeBytes": 48211 }
  }
}

Die Angaben (metadata)

Alle optional:

Oder: von einer URL

Statt hochzuladen, schicken Sie JSON mit einer fileUrl. DDM lädt die Datei selbst:

curl -X PUT "https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711" \
  -H "Authorization: Bearer $DDM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl":"https://pim.example.com/export/4711.pdf","categoryPath":"Produkte/Preislisten"}'

Die Adresse muss für DDM über HTTP(S) erreichbar sein; Weiterleitungen werden nicht verfolgt. Die Datei darf so groß sein wie beim Hochladen – die maximale Dateigröße des Tarifs –, und DDM schreibt sie beim Empfang auf die Festplatte. Der Download darf bis zu 15 Minuten dauern. Schlägt er fehl, lautet die Antwort 422, mit dem Grund; ist die Datei zu groß, 413.

DDM spricht nie Adressen von Cloud-Metadaten-Diensten an. Bei einem gehosteten DDM kann der Betrieb zusätzlich Adressen in privaten Netzen sperren; die Datei muss dann von außen erreichbar sein.

4. Ändern und löschen

• PATCH /documents/ref/{ref} ändert name, status (archived oder draft), shareable, highlighted, tags, titles oder categoryIds, ohne die Datei noch einmal zu schicken.
• DELETE /documents/ref/{ref} löscht das Dokument, genau wie das Löschen im CMS. Ein Dokument unter Aufbewahrungsschutz oder in einer laufenden Freigabe wird mit 409 abgewiesen.

curl -X PATCH "https://ddm.example.com/api/ext/v1/documents/ref/PIM-4711" \
  -H "Authorization: Bearer $DDM_API_KEY" -H "Content-Type: application/json" \
  -d '{"status":"archived"}'

5. Kategorien, wenn Sie sie selbst pflegen

Hat das andere System einen eigenen Baum, spielen Sie ihn von oben nach unten über Referenzen ein. parentRef nennt die übergeordnete Kategorie über ihre Referenz:

curl -X PUT "https://ddm.example.com/api/ext/v1/categories/ref/CAT-10" \
  -H "Authorization: Bearer $DDM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Produkte"}'

curl -X PUT "https://ddm.example.com/api/ext/v1/categories/ref/CAT-11" \
  -H "Authorization: Bearer $DDM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Preislisten","parentRef":"CAT-10","titles":{"DE":"Preislisten","AT":"Preislisten"}}'

Dann legen Sie Dokumente mit categoryIds ab (PATCH), oder stellen die Kategorie-Zuordnung der Push-Quelle auf Feste Kategorie.

Was nach dem Einspielen geschieht

Ein eingespieltes Dokument ist ein Dokument wie jedes andere:

• Es beginnt mit dem Standardstatus für Uploads der Organisation – oder mit dem Status, den die Push-Quelle unter Status neuer Dokumente festlegt. Ist sie vertrauenswürdig, sind ihre Dokumente und neuen Versionen sofort freigegeben (mehr).
• Neue Bytes an einem Dokument in Freigabe beenden diese Freigabe, wie ein Upload im CMS.
• Wer daran gearbeitet hat, bekommt die übliche E-Mail „Neue Version“.
• Mit Verteilung erst nach Freigabe sehen Leser es, sobald es freigegeben ist.