Herkunft aus Ihrem ERP erfassen

Geschäftssysteme erfassen Ereignisse, die DICE nie selbst beobachtet: einen Wareneingang in SAP, die Freigabe einer Prüfung in Ihrem MES oder einen in Ihrer Handelsplattform abgeschlossenen Verkauf. Mit Deklarierten Transaktionen kann Ihre Integration solche Ereignisse unmittelbar in den Verlauf eines Datensatzes schreiben — jeweils als zugeordneter, dauerhafter Eintrag, der mit der Herkunft des Objekts weitergegeben wird und auf dessen Öffentlicher Seite erscheinen kann.

Diese Anleitung verbindet ein ERP (nach demselben Muster lassen sich auch ein WMS, MES oder jedes andere führende System anbinden) mit POST /api/v1/events/declare. Die Authentifizierung erfolgt über ein Dienstkonto, und jeder Eintrag wird dem menschlichen Bediener zugeordnet, der die Aktion in Ihrem System ausgeführt hat.

Hinweis

Ein deklarierter Eintrag ist die zugeordnete Aussage Ihrer Organisation — niemals eine von der Plattform verifizierte Tatsache. DICE erfasst, wer die Aussage wann gemacht hat, zeigt sie als deklariert gekennzeichnet an und stellt sie niemals als etwas dar, das die Plattform selbst beobachtet hat. Der Eintrag ist außerdem dauerhaft: Er wird zusammen mit dem übrigen Verlauf des Datensatzes an nachgelagerte Eigentümer weitergegeben und kann nicht gelöscht, sondern nur zurückgezogen werden — und ein Zurückziehen erzeugt einen zweiten sichtbaren Eintrag, statt den ursprünglichen zu entfernen.

Der Ablauf im Überblick

1. Ihre Integration tauscht die Anmeldedaten ihres Dienstkontos gegen ein kurzlebiges Bearer-Token aus (Authentifizierung).
2. In Ihrem System geschieht etwas — ein Warenausgang, eine Prüfung oder der Abschluss einer Reparatur.
3. Ihre Integration ruft POST /api/v1/events/declare mit der Datensatz-ID, einer Überschrift sowie Zeitpunkt und Ort der Aussage auf und sendet die Identität des Bedieners im Header Dust-Ctx-Declared-Actor.
4. Der Eintrag erscheint im Transaktionsprotokoll des Datensatzes in DICE, ist als Deklariert gekennzeichnet und dem Dienstkonto zugeordnet, das im Namen Ihres Bedieners handelt.

Voraussetzungen

• Ein Dienstkonto mit einem API-Schlüssel oder OAuth-Client — siehe Authentifizierung. Das Dienstkonto benötigt Bearbeitungszugriff auf die Datensätze, in die es schreiben soll. Gewähren Sie ihm dazu Zugriff auf das Team, dem diese Datensätze gehören.
• Ihre Organisations-ID für den Header Dust-Ctx-Org-Id sowie die Team-ID, falls das Dienstkonto als bestimmtes Team handeln soll — siehe Konventionen für Anfragen.
• Die Datensatz-IDs der beteiligten Objekte. Eine Integration ermittelt diese normalerweise über eine Suche nach dem Feld, das Ihr System und DICE gemeinsam verwenden — etwa eine Serien-, Chargen- oder Auftragsnummer — mittels GET /api/v1/threads (siehe den Leitfaden zur Datensatz-API).

Eine Transaktion deklarieren

Ein Aufruf erfasst einen Eintrag in einem Datensatz:

curl

curl -fsS "https://apid.dustid.io/api/v1/events/declare" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    "title": "Incoming inspection passed",
    "note": "Visual and dimensional inspection against PO 4500012345.",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

TypeScript

const response = await fetch("https://apid.dustid.io/api/v1/events/declare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": orgId,
    "Dust-Ctx-Declared-Actor": JSON.stringify({
      id: "JDOE",
      system: "SAP",
      displayName: "Jane Doe",
    }),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    threadId: "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    title: "Incoming inspection passed",
    note: "Visual and dimensional inspection against PO 4500012345.",
    kind: "inspection",
    edtf: "2026-08-06",
    location: { name: "Plant 1710, Springfield" },
  }),
});
if (!response.ok) throw new Error(`declare failed: ${response.status}`);
const claim = await response.json();

Anfragefelder — mit Ausnahme von threadId sind alle optional, eine vollständig leere Deklaration wird jedoch abgelehnt:

Feld	Typ	Hinweise
threadId	UUID	Der Datensatz, zu dem der Eintrag gehört. Erfordert Bearbeitungszugriff.
title	string ≤ 80	Kurze Überschrift — sie wird in Feeds und auf Seiten als Titel des Eintrags angezeigt.
note	string ≤ 4000	Freitext mit Einzelheiten zum Geschehen.
kind	string ≤ 64	Frei definierbare Klassifizierung: sale, inspection, repair, service, … gemäß Ihrem Vokabular. Standardwert ist other.
edtf	string ≤ 64	Der Zeitpunkt des Ereignisses mit genau der Genauigkeit, die Ihnen tatsächlich bekannt ist — siehe unten. Lassen Sie das Feld weg, um es mit dem aktuellen Zeitpunkt zu erfassen.
location	object	Der angegebene Ort: { "name": string, "latitude"?: number, "longitude"?: number }. name wird angezeigt.
resIds	UUID[] ≤ 25	Nachweise: IDs von Dateien, die bereits an den Datensatz angehängt sind und den Eintrag dokumentieren — etwa ein Prüfbericht oder ein Zertifikat. IDs von Dateien, die nicht an diesen Datensatz angehängt sind, werden abgelehnt.

Die Antwort gibt die angelegte Aussage zurück — kind, title, note sowie ein strukturiertes when-Objekt mit der Anzeigezeichenfolge display, der Genauigkeit und den Grenzen der Aussage.

Zeitpunkt mit der bekannten Genauigkeit angeben

edtf akzeptiert eine Teilmenge von EDTF (ISO 8601-2), sodass die Aussage genau die in Ihrem System vorhandene Genauigkeit enthält — ein Jahr, einen Monat, einen Tag, einen Zeitraum oder eine ungefähre Angabe:

Aussage	edtf	Anzeige
Ein genauer Tag	2026-07-14	14. Juli 2026
Ein Monat	2026-07	Juli 2026
Ein Jahr	1968	1968
Ein abgeschlossener Zeitraum	1968/1970	1968–1970
Ungefähr	1835~	Etwa 1835
Vor einem Datum	../1970-03	Vor März 1970
Nach einem Datum	2019/..	Nach 2019

Die Aussage wird überall mit der von Ihnen angegebenen Genauigkeit angezeigt — ein Zeitraum wie 1968/1970 wird niemals auf ein erfundenes genaues Datum reduziert. Übermitteln Sie die Genauigkeit, über die Sie tatsächlich verfügen, und keine mit Mitternacht als Zeitstempel versehene Schätzung.

Tipp

ERP-Dokumente enthalten normalerweise ein Buchungsdatum und keinen Zeitstempel. Übermitteln Sie das Datum (2026-08-06) statt eines erfundenen Zeitpunkts — dadurch ist der Eintrag aussagekräftiger und lässt sich im Datensatz sowie auf dessen Öffentlicher Seite besser lesen.

Den menschlichen Bediener zuordnen

Ein Dienstkonto authentifiziert Ihr System. Der Header Dust-Ctx-Declared-Actor benennt für jede Anfrage die Person, die darin gehandelt hat:

Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe", "role": "Quality Inspector"}

id ist erforderlich; system, displayName und role sind optional. Der JSON-Wert muss kleiner als 1 KB bleiben; URI-codieren Sie ihn, wenn er Nicht-ASCII-Zeichen enthält. Der deklarierte Akteur wird bei jedem von der Anfrage geschriebenen Eintrag unverändert erfasst und im Verlauf als deklarierte Zuordnung angezeigt — von Ihrer Integration bereitgestellt, nicht von DICE verifiziert und ohne Auswirkung auf Berechtigungen. Ein Organisationsadministrator kann diese Angabe verpflichtend machen. In diesem Fall werden Schreibvorgänge ohne den Header mit 403 ATTRIBUTION_REQUIRED abgelehnt. Die vollständige Semantik finden Sie unter Zuordnung des deklarierten Akteurs.

Für deklarierte Herkunft sollten Sie diesen Header in Ihrem eigenen Code als erforderlich behandeln: Die Aussage „Geprüft — bestanden“ ist wesentlich aussagekräftiger, wenn ihr „Jane Doe, Qualitätsprüferin“ zugeordnet ist, als wenn lediglich „SAP Connector“ angegeben wird.

Eine ganze Charge deklarieren

Wenn ein einzelnes Geschäftsereignis viele Objekte betrifft — etwa den Wareneingang von 200 serialisierten Einheiten oder eine Prüfung auf Chargenebene — deklarieren Sie es einmal für alle:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/batch" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…", "4f1d22c0-…", "9a8b11de-…"],
    "title": "Incoming inspection passed",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

• threadIds akzeptiert 1–500 Datensatz-IDs. Der Schreibvorgang wird nach dem Prinzip Alles oder nichts ausgeführt und erfordert Bearbeitungszugriff auf jeden Datensatz im Batch.
• Dieselbe Aussage wird in jedem Datensatz angelegt — innerhalb eines Batchs sind keine datensatzspezifischen Abweichungen möglich. Daten, die sich je Objekt unterscheiden (Seriennummer, Charge, Messergebnisse), gehören in Datensatzfelder und nicht in die Aussage.
• Die Antwort enthält eine gemeinsame operationId. Speichern Sie sie: Sie dient als Referenz zum Korrigieren des Batchs (siehe unten).

Tipp

Der Batch-Endpunkt funktioniert auch mit einer einzelnen Datensatz-ID und gibt im Gegensatz zum Endpunkt für einzelne Einträge eine operationId zurück. Falls Ihre Integration einen Eintrag möglicherweise später programmgesteuert korrigieren muss, erhalten Sie eine dauerhafte Referenz, indem Sie die Deklaration über den Batch-Endpunkt vornehmen und die operationId zusammen mit Ihrem Quelldokument speichern.

Viele Einträge auf einmal nachtragen

/declare/batch schreibt eine Aussage in viele Datensätze. Wenn Sie viele unterschiedliche Aussagen veröffentlichen müssen — etwa bei der Nachtragung historischer Daten, einer Migration aus einem tabellenbasierten System oder den Ereignissen eines ganzen Tages in der Fertigung — verwenden Sie stattdessen /declare/rows. Jede Zeile wird in jeden Datensatz aus threadIds geschrieben, und alle Einträge verwenden gemeinsam eine operationId:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/rows" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…"],
    "rows": [
      { "title": "Inspected", "kind": "inspection", "edtf": "2024-03-01", "location": { "name": "Geneva" } },
      { "title": "Sealed for shipment", "kind": "shipment", "edtf": "2024-03-04" },
      { "title": "Customs cleared", "edtf": "2024-03-11" }
    ]
  }'

• Pro Anfrage sind bis zu 100 Zeilen und 500 Datensätze zulässig, begrenzt auf insgesamt 2.000 Einträge (threadIds.length × rows.length). Teilen Sie größere Nachtragungen auf.
• Alles oder nichts für die gesamte Anfrage: Ein einziges nicht erkanntes Datum führt zur Ablehnung aller Zeilen, statt eine unvollständige Nachtragung mit Einträgen zu hinterlassen, die nur einzeln zurückgezogen werden können.
• Zeilen enthalten weder anchor noch Nachweis-resIds — beide Angaben gelten jeweils für eine einzelne Aussage. Verwenden Sie dafür /declare.
• /declare/batch entspricht dem Fall mit einer Zeile bei diesem Endpunkt. Verwenden Sie ihn weiterhin, wenn es sich tatsächlich nur um eine Aussage handelt.

Dies ist derselbe Endpunkt, an den auch der DICE-eigene CSV-Import Daten sendet. Wenn Ihre Kunden Daten manuell statt aus einem System nachtragen, verweisen Sie sie auf Vergangene Ereignisse erfassen, statt eine Integration zu entwickeln.

Einen Fehler korrigieren

Deklarierte Einträge sind unveränderlich — sie können weder bearbeitet noch gelöscht werden. Die Korrektur erfolgt durch Zurückziehen: Ein zweiter zugeordneter Eintrag erklärt, dass der erste falsch war. Das Original bleibt als zurückgezogen gekennzeichnet im Verlauf erhalten, und beide Einträge werden mit dem Datensatz weitergegeben — eine Berichtigung, niemals eine Löschung.

Um alle Einträge zurückzuziehen, die ein Batch geschrieben hat, etwa weil der Wareneingang in Ihrem ERP storniert wurde, übermitteln Sie die gespeicherte operationId:

curl -fsS "https://apid.dustid.io/api/v1/events/retract/by-operation" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "7c3f0f9e-5b7a-4a4f-8f7d-2f1d0e6a9b21",
    "reason": "Goods receipt reversed (movement type 102)."
  }'

Dadurch werden alle noch aktiven Einträge zurückgezogen, die der Vorgang geschrieben hat. Bereits einzeln zurückgezogene Einträge werden übersprungen. Der Vorgang erfordert Bearbeitungszugriff auf alle beteiligten Datensätze. Ein einzelner Eintrag wird stattdessen über seine Ereignis-ID zurückgezogen: POST /api/v1/events/{event_id}/retract mit einem optionalen reason. Ereignis-IDs stammen aus dem Verlauf des Datensatzes (GET /api/v1/events?threadId=…).

Erfassen Sie nach dem Zurückziehen mit einer neuen Deklaration einen korrigierten Eintrag — dieses Paar aus fehlerhaftem Eintrag und Korrektur bildet den tatsächlichen Verlauf nachvollziehbar ab.

Achtung

Eine Öffentliche Seite veröffentlicht eine Momentaufnahme. Daher erreicht ein neuer Eintrag oder eine Zurückziehung die Seite erst bei ihrer erneuten Veröffentlichung. Wenn das Seitendesign die Richtlinie für den dynamischen Produktpass verwendet, wird die Seite nach einer erfolgreichen Deklaration oder Zurückziehung automatisch mit der bereits bereitgestellten Version erneut veröffentlicht. Andernfalls zeigt die Seite weiterhin die vorherige Momentaufnahme, wird als gegenüber ihrem Datensatz veraltet aufgeführt und bei der nächsten Veröffentlichung aktualisiert. In beiden Fällen wird die zurückgezogene Aussage durchgestrichen und als zurückgezogen gekennzeichnet, statt zu verschwinden — veröffentlichte Herkunft wird niemals stillschweigend umgeschrieben.

Fehlerfälle

Antwort	Bedeutung
400 INVALID_DATA	Der Wert von edtf liegt außerhalb der unterstützten Teilmenge oder ist kein gültiges Kalenderdatum, die Deklaration ist leer oder eine Nachweis-ID ist nicht an diesen Datensatz angehängt.
400 INVALID_REQUEST	Fehlerhafter Anfrageinhalt — beispielsweise überschreitet ein Feld seine Längenbegrenzung.
403 ATTRIBUTION_REQUIRED	Die Richtlinie des Dienstkontos erfordert einen deklarierten Akteur, die Anfrage enthielt jedoch keinen.
404 NOT_FOUND	Eine Datensatz-ID, die für den Aufrufenden nicht sichtbar ist oder nicht existiert. Beim Batch-Endpunkt führt jede einzelne derartige ID zum Fehlschlagen des gesamten Batchs.

Fehlerantworten folgen dem Standardvertrag — siehe Konventionen für Anfragen sowie Fehler und Scanergebnisse für sämtliche Codes einschließlich Status und Hinweisen zu Wiederholungsversuchen.

Nächste Schritte

• Authentifizierung und API-Schlüssel — Dienstkonten, Token-Austausch und Semantik des deklarierten Akteurs.
• Fehler und Scanergebnisse — der vollständige Fehlervertrag einschließlich des Aktualisierungsverhaltens bei 401.
• Leitfaden zur Datensatz-API — Zuordnung der Seriennummern und Aufträge Ihres Systems zu Datensatz-IDs.
• Vergangene Ereignisse erfassen — dieselbe Funktion aus Sicht Ihrer Bediener in DICE.
• Öffentliche Seiten — wie deklarierte Einträge im öffentlichen Produktpass des Objekts erscheinen.