Integrations-API

Referenz: Abgleich-Manifest

GET /sync – alles, was ein Schlüssel sieht, in einer Liste, um Gelöschtes zu finden.

GET /sync

Berechtigung Lesen. Jedes Dokument und jede Kategorie, die der Schlüssel sieht, mit nur den Feldern, die man zum Vergleichen braucht. Damit finden Sie, was weg ist: gelöscht, aus der freigegebenen Sicht archiviert, oder außer Reichweite der handelnden Person.

complete
boolean
false, wenn es mehr als 50.000 Dokumente gibt und die Liste abgeschnitten wurde. Dann löschen Sie danach nichts.
documents[].checksum
string | null
SHA-256 der aktuellen Version. Weicht Ihre ab, laden Sie die Datei neu.
documents[].categoryIds
uuid[]
Wo es abgelegt ist, unter den Kategorien, die der Schlüssel sieht. So fällt auch eine Neuablage im CMS auf.

Anfrage

curl https://ddm.example.com/api/ext/v1/sync \
  -H "Authorization: Bearer $DDM_API_KEY"

Antwort · 200 OK

{
  "generatedAt": "2026-10-27T20:01:47.990Z",
  "complete": true,
  "documents": [
    {
      "id": "dc8594e0-0ead-4049-aaee-2ef899bcf76f",
      "externalRef": "PIM-4711",
      "sourceId": "5d02b7aa-5175-42e9-9277-aa19063833f2",
      "status": "draft",
      "currentVersionId": "1730e7bb-2f98-4761-aa9b-964c521351b3",
      "checksum": "0bcb7c3b4886f699a985563d7bc9476bf75b4af35a57ff959f46c37e386cf54f",
      "categoryIds": [
        "078a554f-19a2-4285-b854-8546de01f815"
      ],
      "updatedAt": "2026-10-27T20:01:47.284Z"
    }
  ],
  "categories": [
    {
      "id": "7a7afae0-f77b-478b-975d-d29eace15d51",
      "parentId": null,
      "externalRef": "CAT-10",
      "updatedAt": "2026-10-27T20:01:46.086Z"
    },
    {
      "id": "078a554f-19a2-4285-b854-8546de01f815",
      "parentId": "7a7afae0-f77b-478b-975d-d29eace15d51",
      "externalRef": "CAT-11",
      "updatedAt": "2026-10-27T20:01:46.138Z"
    },
    {
      "id": "45dc485e-d982-466a-8ab6-e8ac328b800f",
      "parentId": "7a7afae0-f77b-478b-975d-d29eace15d51",
      "externalRef": null,
      "updatedAt": "2026-10-27T20:01:46.200Z"
    }
  ]
}

Beispiel: gelöschte Dokumente finden

Bewahren Sie das Manifest jedes Laufs auf. Beim nächsten Lauf holen Sie ein neues und vergleichen: Jede id, die im alten stand und im neuen fehlt, ist für diesen Schlüssel weg. Das Dokument kann gelöscht, aus der freigegebenen Sicht archiviert oder dorthin verschoben worden sein, wo die Person des Schlüssels es nicht sieht.

# Das Manifest des letzten Laufs liegt in manifest-previous.json.
curl -s https://ddm.example.com/api/ext/v1/sync \
  -H "Authorization: Bearer $DDM_API_KEY" > manifest.json

# Über 50.000 Dokumenten abgeschnitten? Dann nichts vergleichen.
if [ "$(jq .complete manifest.json)" != "true" ]; then
  echo "Manifest unvollständig – es wird nichts gelöscht" >&2; exit 1
fi

# Die IDs, die beim letzten Mal da waren und jetzt nicht mehr.
jq -r '.documents[].id' manifest-previous.json | sort > previous.txt
jq -r '.documents[].id' manifest.json | sort > current.txt
comm -23 previous.txt current.txt > gone.txt

while read -r id; do
  echo "weg: $id"   # hier aus Ihrem System entfernen
done < gone.txt

mv manifest.json manifest-previous.json

„Weg“ bedeutet in allen drei Fällen dasselbe: Entfernen Sie das Dokument aus Ihrem System, oder blenden Sie es dort aus. Wenn Sie wissen müssen, warum es weg ist, fragen Sie GET /documents/{id} mit einem Schlüssel, der alles sieht. 404 heißt gelöscht; sonst sagen status und categoryIds, was sich geändert hat.

Vergleichen Sie nur ein Manifest, dessen completetrue ist. Und misstrauen Sie einem Manifest, das plötzlich leer oder viel kleiner ist – ein entzogenes Recht oder eine andere handelnde Person lässt alles auf einmal „verschwinden“. Eine sinnvolle Sicherung: anhalten und jemanden benachrichtigen, wenn in einem Lauf mehr als etwa 10 % der Dokumente gelöscht würden.

Änderungsfeed oder Manifest?

FrageNehmen Sie
Was ist seit meinem letzten Lauf neu oder geändert?GET /documents?updatedSince=… – klein, schnell, seitenweise
Was ist weg?GET /sync – vollständig, aber größer
Wurde im CMS etwas neu abgelegt oder neu verschlagwortet?GET /sync für die Ablage, GET /documents/{id} für die Schlagwörter

Ein guter Rhythmus: der Änderungsfeed alle paar Minuten, das Manifest einmal pro Stunde oder pro Nacht.