Kernmodell

Die DUST-Plattform-API bildet Workflows für physische Gegenstände als kleine Gruppe kombinierbarer Ressourcen ab. Ein Datensatz ist der digitale Eintrag für einen physischen Gegenstand; alles andere – Kennungen, Dateien, Ordner, Baugruppen, Freigaben und Sendungen – wird Datensätzen zugeordnet, organisiert sie oder verschiebt sie. Diese Seite dient als Übersicht: ein kurzer Abschnitt pro Konzept mit den wichtigsten Endpunkten und einem Link zur ausführlicheren Anleitung.

Namenszuordnung

Einige API-Namespaces stammen aus der Zeit vor dem aktuellen Produktvokabular. Die DICE-Web-App und diese Dokumentation verwenden die Bezeichnungen auf der linken Seite; die API-Pfade behalten die Bezeichnungen auf der rechten Seite bei.

Bezeichnung in DICE / der Dokumentation	API-Namespace	Hinweise
Datensätze	/api/v1/threads	—
Kennungen	/api/v1/tags	Veraltete Bezeichnung tags in Pfaden
Dateien	/api/v1/files	In einigen Schemas als Ressourcen bezeichnet
Ordner & Kategorien	/api/v1/bundles	Bundle ist die Implementierungsbezeichnung
Baugruppen	/api/v1/assemblies	Baugruppen sind Datensätze der Art assembly
Teams	/api/v1/teams	Pro Anfrage über den Header Dust-Ctx-Team-Id ausgewählt (der veraltete Header Dust-Ctx-Grp-Id wird weiterhin akzeptiert)
Verbindungen	/api/v1/connections	Übertragungsschemas behalten die veraltete Bezeichnung team link bei
Freigaben	/api/v1/sharing	—
Sendungen	/api/v1/transfers	Veraltete Bezeichnung transfers in Pfaden
Aufteilungen	/api/v1/slices	—
Fabric	/api/v1/fabric	Organisationsübergreifender Herkunftsgraph
Zertifikate	/api/v1/certificates, /api/v1/certificate-forms	—
Öffentliche Seiten	/api/v1/public-pages, /api/v1/public-page-designs	Die Veröffentlichung erfordert die Team-Berechtigung publisher
Ereignisse	/api/v1/events	—

Jede Anfrage enthält ein AuthD-Bearer-Token; Endpunkte im Organisationsumfang – also nahezu alle – erfordern zusätzlich den Header Dust-Ctx-Org-Id (und optional Dust-Ctx-Team-Id, um ein Team auszuwählen). Siehe Authentifizierung und Konventionen. Die vollständige Referenz auf Parameterebene finden Sie in der API-Referenz.

Datensätze

Ein Datensatz ist der Eintrag für einen physischen Vermögenswert, ein Bauteil, ein Dokument oder ein Workflow-Objekt: Er enthält einen Namen und eine Beschreibung, typisierte Felddaten, angehängte Dateien, verknüpfte Kennungen und einen Ereignisverlauf. Datensätze besitzen eine kind – gewöhnliche Einheiten oder assembly (siehe unten).

• POST /api/v1/threads — einen oder mehrere Datensätze erstellen
• GET /api/v1/threads — suchen und auflisten (Cursor-Paginierung)
• GET /api/v1/threads/{thread_id} — einen Datensatz einschließlich Felddaten abrufen
• POST /api/v1/threads/{thread_id}/data — Feldwerte einfügen, aktualisieren oder entfernen
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — Archivierungslebenszyklus

Ausführliche Informationen: API-Anleitung für Datensätze.

Felder und Vorlagen

Feldwerte sind typisiert (text, number, date, select, Ressourcenreferenzen und sogar Felder mit Datensätzen als Wert) und nach Typ verschachtelt. Vorlagen definieren die erwarteten Felder für eine wiederverwendbare Art von Datensatz.

• POST /api/v1/templates / GET /api/v1/templates — Vorlagen erstellen und auflisten
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — lesen und aktualisieren

Kennungen

Eine Kennung verknüpft eine physische Markierung – ein DUST-Tag, einen QR-Code, Barcode, ein Data-Matrix-Symbol oder einen NFC-Chip – mit einem Datensatz, sodass ein Scan vor Ort zum digitalen Eintrag aufgelöst wird. Der API-Namespace lautet /api/v1/tags (veraltete Bezeichnung).

• POST /api/v1/tags/extract — eine DUST-Aufnahme ohne Verknüpfung in einen kanonischen Fingerabdruck parsen
• POST /api/v1/tags/bind — eine Kennung mit einem Datensatz verknüpfen
• POST /api/v1/tags/identify — den mit einem Scan übereinstimmenden Datensatz finden
• POST /api/v1/tags/verify — bestätigen, dass ein Scan mit den Kennungen eines bestimmten Datensatzes übereinstimmt
• POST /api/v1/tags/unbind — die Verknüpfung einer Kennung lösen

Ausführliche Informationen: API-Anleitung für Kennungen.

Dateien

Dateien (in einigen Schemas als Ressourcen bezeichnet) werden in einem Objektspeicher gespeichert und entweder direkt oder über Felder des Typs „Ressource“ an Datensätze angehängt. Große Uploads verwenden das fortsetzbare tus-Protokoll; kleine Uploads erfolgen über einen einzelnen mehrteiligen POST-Aufruf.

• POST /api/v1/files — einfacher mehrteiliger Upload
• POST /api/v1/files/finalize — abgeschlossene tus-Uploads in Ressourceneinträge umwandeln
• GET /api/v1/files/{resource_id}/download — herunterladen
• POST /api/v1/files/urls — kurzlebige signierte URLs
• GET /api/v1/files/search — dateiübergreifend suchen

Ausführliche Informationen: API-Anleitung für Dateien.

Teams und Organisationen

Identitäten werden in AuthD verwaltet; die Plattform-API ordnet jede Anfrage im Organisationsumfang über Kontext-Header einer Organisation und einem Team zu. Teams sind Eigentümer von Datensätzen, und Freigaben, Verbindungen sowie Sendungen erfolgen jeweils zwischen Teams.

• GET /api/v1/me — aktueller Benutzer und verfügbare Organisationen
• GET /api/v1/teams — für den Aufrufer sichtbare Teams
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — Teamverwaltung (Organisationsadministratoren)
• POST /api/v1/org/teams/members — Mitgliedschaften verwalten (Organisationsadministratoren)

Ausführliche Informationen: Teams, Freigaben und Verbindungen.

Ordner und Kategorien

Ordner und Kategorien organisieren Datensätze. Beide sind in der API Bundles – kind: "folder" für exklusive Aufnahme und kind: "category" für nicht exklusive Kennzeichnung – und Bundles lassen sich zu Baumstrukturen verschachteln.

• POST /api/v1/bundles — erstellen (mit kind und optional dem übergeordneten childOfId)
• GET /api/v1/bundles / GET /api/v1/bundles/children — auflisten oder die Baumstruktur schrittweise durchlaufen
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — Datensätze platzieren
• PATCH /api/v1/bundles/parent — ein Bundle einem anderen übergeordneten Element zuweisen

Baugruppen und Bauteile

Eine Baugruppe ist ein Datensatz der Art assembly, dessen Bauteile andere Datensätze sind – eine Stücklistenstruktur. Bauteile können vor dem Entfernen geschützt werden, und Bauteillisten werden transitiv zusammengeführt.

• GET /api/v1/assemblies — Baugruppen-Datensätze auflisten
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — Bauteile anhängen und entfernen
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — transitive Bauteilliste
• PATCH /api/v1/assemblies/{assembly_id}/kind — einen Datensatz zwischen unit und assembly konvertieren
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — den Import eines vollständigen Baugruppenpakets als Probelauf ausführen und übernehmen

Datensatzverknüpfungen und Beziehungen

Datensätze können über typisierte Verknüpfungen aufeinander verweisen. Beziehungsdefinitionen benennen die Beziehungsarten; Datensatzverknüpfungen sind deren Instanzen.

• POST /api/v1/relations / GET /api/v1/relations — Beziehungsarten definieren und auflisten
• POST /api/v1/links / GET /api/v1/links — Verknüpfungen zwischen Datensätzen erstellen und auflisten
• GET /api/v1/threads/{thread_id}/links — Verknüpfungen aus der Perspektive eines Datensatzes
• DELETE /api/v1/links/{link_id} — Verknüpfung lösen

Freigaben

Eine Freigabe gewährt einem anderen Team mit viewer- oder editor-Zugriff auf einen Datensatz oder ein Bundle. Berechtigungen werden als Beziehungstupel gespeichert; die Zugriffszusammenfassung zeigt das effektive Ergebnis einschließlich geerbter Zugriffsrechte.

• POST /api/v1/sharing — Datensätze oder Bundles für Teams freigeben
• GET /api/v1/sharing — Berechtigungen auflisten (direction=in|out)
• GET /api/v1/sharing/access-summary — effektiver Zugriff auf ein Objekt
• GET /api/v1/sharing/partner-inventory — alles, was für ein Partnerteam freigegeben wurde

Ausführliche Informationen: Teams, Freigaben und Verbindungen.

Verbindungen

Eine Verbindung (API: team link) ist die dauerhafte Vereinbarung zwischen zwei Teams – häufig in unterschiedlichen Organisationen –, die Freigaben und Sendungen in einer zulässigen Datenflussrichtung ermöglicht. Sie besitzt einen Einladungs-, Annahme- und Bestätigungsablauf sowie einen Lebenszyklus zum Pausieren und Fortsetzen.

• POST /api/v1/connections — erstellen (einladen)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — Einladungs-, Annahme- und Bestätigungsablauf
• PATCH /api/v1/connections/pause / resume — aussetzen und wiederherstellen
• POST /api/v1/connections/amend/propose — eine Richtungsänderung vorschlagen

Sendungen

Eine Sendung (API: transfer) überträgt das Eigentum an Datensätzen von einem Team auf ein anderes: Ein Manifestentwurf wird erstellt und gesendet, woraufhin der Empfänger ihn annimmt, ablehnt oder Änderungen anfordert.

• POST /api/v1/transfers — einen Entwurf erstellen
• POST /api/v1/transfers/{transfer_id}/items — Manifestobjekte hinzufügen
• POST /api/v1/transfers/{transfer_id}/send — an das empfangende Team senden
• POST /api/v1/transfers/{transfer_id}/respond — annehmen / ablehnen / Änderungen anfordern
• GET /api/v1/transfers — Ansichten für Eingang, Ausgang und gesendete Elemente

Semantik und Lebenszyklus: Sendungen; Endpunktübersicht unter Teams, Freigaben und Verbindungen.

Aufteilungen

Eine Aufteilung leitet innerhalb desselben Teams aus einem vorhandenen Datensatz einen neuen Datensatz ab – ausgewählte Felder, Dateien und Kennungen werden kopiert oder verknüpft –, üblicherweise um eine freigabefähige Teilmenge vorzubereiten.

• POST /api/v1/slices — einen Datensatz aufteilen
• POST /api/v1/slices/batch — mehrere Datensätze gleichzeitig ableiten
• GET /api/v1/slices/{slice_id} — eine Aufteilung mit ihren Fabric-Verknüpfungen

Fabric

Fabric ist die organisationsübergreifende Herkunftsebene: Wenn Datensätze über Teamgrenzen hinweg verschoben oder offengelegt werden, erfasst Fabric den Graph der verknüpften Datensätze und steuert revisionsweise exakt, welche Daten jede nachgelagerte Partei sehen kann (Offenlegung).

• GET /api/v1/fabric/threads/{thread_id}/graph — der von einem Datensatz aus sichtbare Herkunftsgraph
• GET /api/v1/fabric/links/{link_id}/context — aktuell über eine Verknüpfung offengelegte Daten
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — ändern, was offengelegt wird
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — eine Offenlegung nachgelagert weitergeben
• GET /api/v1/fabric/notifications — Offenlegungsbenachrichtigungen für nachgelagerte Eigentümer

Konzepte: Fabric.

Zertifikate

Zertifikate stellen Datensatzdaten als ausgestellte, verifizierbare Dokumente dar. Zertifikatsformulare sind die Layouts; bei der Generierung wird ein Formular anhand des Feldnamens mit einem Datensatz verknüpft.

Ein Formular kann mehrere Vlink-QR-Zonen enthalten. Die Zertifikatsgenerierung akzeptiert eine Vlink-Konfiguration pro Zonenkennung und gibt jede ausgestellte Zuordnung zwischen Zone und Vlink zurück.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — Formulare verwalten
• POST /api/v1/certificates/preflight — prüfen, ob ein Formular für einen Datensatz aufgelöst werden kann
• POST /api/v1/certificates/generate — ein Zertifikat ausstellen
• GET /api/v1/certificates — die Zertifikate eines Datensatzes auflisten
• POST /api/v1/certificates/void — ein Zertifikat ungültig machen

Konzepte: Zertifikate.

Öffentliche Seiten

Eine Öffentliche Seite ist die nicht authentifizierte Webansicht eines Datensatzes – der digitale Produktpass, den ein Verbraucher durch das Scannen einer Kennung aufruft. Welche Inhalte angezeigt werden, wird vollständig durch ein wiederverwendbares, dem Team gehörendes Seitendesign bestimmt. Deshalb sind für die Veröffentlichung keine datensatzspezifischen Inhaltsangaben erforderlich: Beim Veröffentlichen wird das Design für den Datensatz aufgelöst. Die URL einer Seite wird reserviert und verknüpft, bevor etwas veröffentlicht wird, sodass Etiketten vorab gedruckt werden können.

Durch das Veröffentlichen eines Designs wird eine unveränderliche Designversion festgeschrieben; jede Seite ist an eine Designversion sowie eine Datenmomentaufnahme (die für diesen Datensatz aufgelösten Werte) gebunden. Eine Veröffentlichungsserie veröffentlicht jede Seite in einem Umfang – Ordner, Kategorie, Vorlage oder explizite Auswahl – über eine Designversion erneut. Sie wird als Hintergrundlauf ausgeführt und besitzt eine eigene Fortschritts- und Fehlererfassung.

Das Reservieren einer Seiten-URL und ihre Verknüpfung mit einem Datensatz erfordern die Mitgliedschaftsstufe – durch das Reservieren einer Adresse wird nichts veröffentlicht, sodass Etiketten gedruckt werden können, bevor jemand eine Veröffentlichung beschließt. Alles, was Daten öffentlich zugänglich macht – eine Seite veröffentlichen, aktivieren oder archivieren, ein Design erstellen, eine Designversion veröffentlichen, ausrollen und Veröffentlichungsserien ausführen –, erfordert die Team-Berechtigung publisher (Teamadministratoren verfügen implizit darüber); dies gilt auch für Vorabprüfungen und Vorschauprüfungen. Maßgeblich ist die Angabe x-required-role des jeweiligen Vorgangs in der API-Referenz.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — eine permanente Seiten-URL reservieren und anschließend mit einem Datensatz verknüpfen
• GET / PUT /api/v1/public-pages/thread/{threadId} — die Seite eines Datensatzes lesen oder abrufen beziehungsweise erstellen
• GET /api/v1/public-pages/thread/{threadId}/activity — anonyme Aufrufe und Verifizierungsscans auf der veröffentlichten Seite
• POST /api/v1/public-pages/{publicPageId}/publish — eine Momentaufnahme über die neueste Version des Designs veröffentlichen
• PATCH /api/v1/public-pages/{publicPageId} — eine Seite aktivieren oder archivieren, ohne ihre URL zu ändern
• GET /api/v1/public-pages/{publicPageId}/publications — Veröffentlichungsverlauf
• POST /api/v1/public-pages/preflight / preflight/batch — prüfen, ob ein Design für einen oder mehrere Datensätze aufgelöst werden kann
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — einen Designentwurf erstellen
• POST /api/v1/public-page-designs/{designId}/versions — eine Designversion veröffentlichen (GET listet sie auf)
• POST /api/v1/public-pages/designs/{designId}/roll-out — die neueste Version eines Designs auf allen zugehörigen Seiten live schalten
• POST /api/v1/public-pages/waves — eine Veröffentlichungsserie starten (GET ruft ihren Laufeintrag, ihre Objekte und ihre Liste ab)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — fehlgeschlagene Vorgänge erneut versuchen oder die verbleibende Arbeit stoppen

Das Ausrollen erfolgt ausschließlich vorwärts: Eine Designversion wird niemals wiederhergestellt, und beim Abbrechen einer Serie bleiben bereits veröffentlichte Seiten auf der Version, die sie erhalten haben.

Konzepte: Öffentliche Seiten.

Ereignisse

Jede relevante Änderung – Feldbearbeitungen, Verknüpfungen, Freigaben und Sendungen – wird als Ereignis erfasst und bildet den in DICE als Transaktionsprotokoll angezeigten Audit-Trail.

• GET /api/v1/events — Ereignisse auflisten, filterbar nach Datensatz, Team, Aktion und Zeit, mit optionaler Aktivitätsgruppierung (groupBy)
  • lineage=upstream (mit threadId) liefert zusätzlich die Ereignisse jedes früheren Datensatzes in der Fabric-Abstammung des Datensatzes – die vollständige Geschichte eines erhaltenen Datensatzes –, begrenzt durch das, was jede Quelle offengelegt hat. Vorgelagerte Zeilen enthalten ein lineage-Objekt (Quelldatensatz, Quellteam, Verbindung, Hop) und können redacted sein; eine spätere Offenlegungsänderung einer Quelle erscheint als schreibgeschützte Zeile fabric.disclosure.revised. Ohne diesen Parameter enthält die Antwort nur die eigenen Ereignisse des Datensatzes.
  • resourceId, tagId oder fieldId (jeweils einzeln, mit threadId) beschränken den Verlauf auf eine Datei, eine Kennung oder ein Feld; ein Zertifikat wird über seine Datei adressiert. Mit lineage=upstream wird die eigene Abstammung der Ressource verfolgt.
  • Ein Datensatz, der in einer Sendung empfangen oder durch ein Aufteilen erstellt wurde, beginnt seinen Verlauf mit transfer.received / slice.derived, zugeordnet der Person, die angenommen bzw. aufgeteilt hat; er hat kein eigenes created.thread oder bind.
• GET /api/v1/summary — zentrale Anzahlmetriken
• GET /api/v1/notifications — Benachrichtigungen des Aufrufers

Nächste Schritte

Schnellstart

Führen Sie im Schnellstart Ihren ersten authentifizierten Aufruf aus.

TypeScript-Client

Verwenden Sie den typisierten @dustid/apid-client anstelle von ungekapseltem HTTP.

Konventionen

Informationen zu Headern, Paginierung und Fehlern finden Sie unter API-Konventionen.

Vollständige Referenz

Alle Pfade, Parameter und Schemas finden Sie in der API-Referenz.

PDF-Belege

Laden Sie mit GET /api/v1/receipts/{kind}/{id} bei Bedarf ein PDF herunter. Dabei ist kind entweder file, thread oder shipment, und id die zugehörige UUID. Verwenden Sie Ihre übliche Authentifizierung und die Kontext-Header für die aktive Organisation und das aktive Team. Die Antwort hat den Typ application/pdf, einen Anhangsdateinamen und die Cache-Einstellungen private und no-store. Accept-Language wählt die Sprache des Belegs.

Dateibelege enthalten Metadaten, die gespeicherte SHA-256-Prüfsumme, sofern verfügbar, Informationen zum zugehörigen Datensatz und zugängliche Transaktionsprotokolleinträge. Datensatzbelege enthalten Felder, Kennungen, Dateien und Prüfsummen, Beziehungen, Baugruppen- und Abstammungsinformationen sowie zugängliche Protokolle. Sendungsbelege beginnen mit Sendungsinformationen, dem aktuellen Status und dem Manifest, gefolgt von sichtbaren Datensatzdetails und Protokollen. Ausstehende Sendungen verwenden angebotene Momentaufnahmen; andere Status verwenden Datensätze, auf die der Aufrufer derzeit zugreifen kann.

Geben Sie für eine über eine Offenlegung sichtbare Datei linkId an; für eine in einer ausstehenden Sendung angebotene Datei geben Sie transferId an. Diese optionalen UUID-Abfrageparameter können nicht kombiniert werden und gelten nur für Dateibelege. Für sie gelten dieselben Zugriffs- und Offenlegungsbeschränkungen wie für die entsprechende Vorschau.

Belege enthalten einen Erstellungszeitstempel und einen QR-Link zurück zu DICE. Sie sind nicht signierte Momentaufnahmen der für den Aufrufer sichtbaren Datensätze, keine digitalen Signaturen. Die Erstellung ist schreibgeschützt: Es werden weder ein Beleganhang noch ein Transaktionsprotokollereignis gespeichert. Exporte mit mehr als 10.000 sichtbaren Ereignissen in einem Protokoll schlagen fehl, statt unbemerkt gekürzt zu werden. Links in einem Beleg erfordern weiterhin Zugriff auf DICE.