Modèle central

L’API de la plateforme DUST modélise les processus liés aux objets physiques sous la forme d’un petit ensemble de ressources composables. Une fiche est l’enregistrement numérique d’un élément physique ; tout le reste — identifiants, fichiers, dossiers, assemblages, partage, expéditions — est rattaché aux fiches, les organise ou les déplace. Cette page en fournit la carte : une courte section par concept, avec les principaux endpoints et un lien vers le guide détaillé.

Correspondance des noms

Certains espaces de noms de l’API sont antérieurs au vocabulaire actuel du produit. L’application web DICE et cette documentation utilisent les noms de gauche ; les chemins de l’API conservent les noms de droite.

Nom dans DICE / la documentation	Espace de noms de l’API	Remarques
Fiches	/api/v1/threads	—
Identifiants	/api/v1/tags	Ancienne dénomination tags dans les chemins
Fichiers	/api/v1/files	Appelés ressources dans certains schémas
Dossiers & catégories	/api/v1/bundles	Bundle est le nom utilisé dans l’implémentation
Assemblages	/api/v1/assemblies	Les assemblages sont des fiches de type assembly
Équipes	/api/v1/teams	Sélectionnées pour chaque requête au moyen de l’en-tête Dust-Ctx-Team-Id (l’ancien Dust-Ctx-Grp-Id reste accepté)
Connexions	/api/v1/connections	Les schémas d’échange conservent l’ancienne dénomination team link
Partage	/api/v1/sharing	—
Expéditions	/api/v1/transfers	Ancienne dénomination transfers dans les chemins
Divisions	/api/v1/slices	—
Fabric	/api/v1/fabric	Graphe de provenance interorganisations
Certificats	/api/v1/certificates, /api/v1/certificate-forms	—
Pages publiques	/api/v1/public-pages, /api/v1/public-page-designs	La publication nécessite l’autorisation publisher de l’équipe
Événements	/api/v1/events	—

Chaque requête comporte un jeton porteur AuthD ; les endpoints à périmètre organisationnel — soit presque tous — ajoutent l’en-tête Dust-Ctx-Org-Id (et éventuellement Dust-Ctx-Team-Id pour sélectionner une équipe). Consultez Authentification et Conventions. La documentation complète au niveau des paramètres se trouve dans la référence de l’API.

Fiches

Une fiche est l’enregistrement associé à un actif physique, une pièce, un document ou un élément de processus : un nom et une description, des données de champs typées, des fichiers joints, des identifiants liés et un historique des événements. Les fiches possèdent un kind — unités ordinaires ou assembly (voir ci-dessous).

• POST /api/v1/threads — créer une ou plusieurs fiches
• GET /api/v1/threads — rechercher et répertorier (pagination par curseur)
• GET /api/v1/threads/{thread_id} — obtenir une fiche avec les données de ses champs
• POST /api/v1/threads/{thread_id}/data — insérer, mettre à jour ou supprimer des valeurs de champs
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — gérer le cycle de vie de l’archivage

Pour approfondir : guide de l’API des fiches.

Champs et modèles

Les valeurs des champs sont typées (text, number, date, select, références à des ressources, voire champs dont la valeur est une fiche) et imbriquées par type. Les modèles définissent les champs attendus pour un type de fiche reproductible.

• POST /api/v1/templates / GET /api/v1/templates — créer et répertorier les modèles
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — consulter et mettre à jour

Identifiants

Un identifiant lie un marquage physique — identifiant DUST, code QR, code-barres, symbole Data Matrix ou puce NFC — à une fiche, afin qu’un scan sur le terrain renvoie vers l’enregistrement numérique. L’espace de noms de l’API est /api/v1/tags (ancienne dénomination).

• POST /api/v1/tags/extract — analyser une capture DUST pour en extraire une empreinte canonique sans effectuer de liaison
• POST /api/v1/tags/bind — rattacher un identifiant à une fiche
• POST /api/v1/tags/identify — trouver la fiche correspondant à un scan
• POST /api/v1/tags/verify — confirmer qu’un scan correspond aux identifiants d’une fiche donnée
• POST /api/v1/tags/unbind — détacher un identifiant

Pour approfondir : guide de l’API des identifiants.

Fichiers

Les fichiers (appelés ressources dans certains schémas) sont conservés dans un stockage d’objets et rattachés aux fiches directement ou au moyen de champs de type ressource. Les fichiers volumineux utilisent le protocole tus avec reprise ; les petits fichiers utilisent une seule requête POST multipart.

• POST /api/v1/files — téléversement multipart simple
• POST /api/v1/files/finalize — convertir les téléversements tus terminés en fiches de ressources
• GET /api/v1/files/{resource_id}/download — télécharger
• POST /api/v1/files/urls — URL signées à courte durée de validité
• GET /api/v1/files/search — effectuer une recherche dans les fichiers

Pour approfondir : guide de l’API des fichiers.

Équipes et organisations

Les identités sont gérées dans AuthD ; l’API de la plateforme limite chaque requête à périmètre organisationnel à une organisation et à une équipe au moyen d’en-têtes de contexte. Les équipes possèdent les fiches, tandis que le partage, les connexions et les expéditions s’effectuent tous entre équipes.

• GET /api/v1/me — utilisateur actuel et organisations disponibles
• GET /api/v1/teams — équipes visibles par l’appelant
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — gestion des équipes (administrateurs de l’organisation)
• POST /api/v1/org/teams/members — gestion des appartenances (administrateurs de l’organisation)

Pour approfondir : Équipes, partage et connexions.

Dossiers et catégories

Les dossiers et les catégories organisent les fiches. Tous deux sont des bundles dans l’API — kind: "folder" pour un contenu exclusif, kind: "category" pour un étiquetage non exclusif — et les bundles s’imbriquent pour former des arborescences.

• POST /api/v1/bundles — créer (avec kind et, facultativement, le parent childOfId)
• GET /api/v1/bundles / GET /api/v1/bundles/children — répertorier ou parcourir l’arborescence de manière différée
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — placer des fiches
• PATCH /api/v1/bundles/parent — changer le parent d’un bundle

Assemblages et pièces

Un assemblage est une fiche de type assembly dont les pièces sont d’autres fiches, ce qui forme une structure de nomenclature. Les pièces peuvent être protégées contre le détachement, et les listes de pièces peuvent être agrégées de manière transitive.

• GET /api/v1/assemblies — répertorier les fiches d’assemblage
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — rattacher et détacher des pièces
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — liste transitive des pièces
• PATCH /api/v1/assemblies/{assembly_id}/kind — convertir une fiche de unit en assembly, ou inversement
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — simuler puis valider l’importation d’un package d’assemblage complet

Liens et relations entre fiches

Les fiches peuvent se référencer mutuellement au moyen de liens typés. Les définitions de relation nomment les types de relations ; les liens entre fiches en sont les instances.

• POST /api/v1/relations / GET /api/v1/relations — définir et répertorier les types de relations
• POST /api/v1/links / GET /api/v1/links — créer et répertorier les liens entre fiches
• GET /api/v1/threads/{thread_id}/links — liens du point de vue d’une fiche
• DELETE /api/v1/links/{link_id} — supprimer un lien

Partage

Le partage accorde à une autre équipe un accès viewer ou editor à une fiche ou à un bundle. Les autorisations sont stockées sous forme de tuples de relations ; le récapitulatif des accès présente le résultat effectif, y compris les accès hérités.

• POST /api/v1/sharing — partager des fiches ou des bundles avec des équipes
• GET /api/v1/sharing — répertorier les autorisations (direction=in|out)
• GET /api/v1/sharing/access-summary — accès effectif à un objet
• GET /api/v1/sharing/partner-inventory — tout ce qui est partagé avec une équipe partenaire donnée

Pour approfondir : Équipes, partage et connexions.

Connexions

Une connexion (API : team link) est l’accord permanent entre deux équipes — souvent issues d’organisations différentes — qui autorise le partage et les expéditions, selon une direction de flux de données permise. Elle comporte un protocole d’invitation, d’acceptation et de confirmation, ainsi qu’un cycle de vie permettant de la suspendre et de la reprendre.

• POST /api/v1/connections — créer (inviter)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — protocole d’établissement
• PATCH /api/v1/connections/pause / resume — suspendre et rétablir
• POST /api/v1/connections/amend/propose — proposer un changement de direction

Expéditions

Une expédition (API : transfer) transfère la propriété de fiches d’une équipe à une autre : créez un projet de manifeste, envoyez-le, puis le destinataire l’accepte, le rejette ou demande des modifications.

• POST /api/v1/transfers — créer un brouillon
• POST /api/v1/transfers/{transfer_id}/items — ajouter des éléments au manifeste
• POST /api/v1/transfers/{transfer_id}/send — envoyer à l’équipe destinataire
• POST /api/v1/transfers/{transfer_id}/respond — accepter / rejeter / demander des modifications
• GET /api/v1/transfers — vues des éléments reçus, à envoyer et envoyés

Sémantique et cycle de vie : Expéditions ; récapitulatif des endpoints dans Équipes, partage et connexions.

Divisions

Une division crée une nouvelle fiche à partir d’une fiche existante au sein de la même équipe — en copiant ou en liant certains champs, fichiers et identifiants — généralement afin de préparer un sous-ensemble partageable.

• POST /api/v1/slices — diviser une fiche
• POST /api/v1/slices/batch — créer plusieurs fiches dérivées en une seule fois
• GET /api/v1/slices/{slice_id} — une division avec ses liens Fabric

Fabric

Fabric est le calque de provenance interorganisations : lorsque des fiches sont déplacées ou divulguées au-delà des limites d’une équipe, Fabric consigne le graphe des fiches liées et contrôle précisément les données que chaque partie en aval peut consulter (divulgation), révision par révision.

• GET /api/v1/fabric/threads/{thread_id}/graph — graphe de provenance visible depuis une fiche
• GET /api/v1/fabric/links/{link_id}/context — données actuellement divulguées sur un lien
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — modifier les données divulguées
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — transmettre une divulgation en aval
• GET /api/v1/fabric/notifications — notifications de divulgation destinées aux propriétaires en aval

Concepts : Fabric.

Certificats

Les certificats rendent les données des fiches sous forme de documents émis et vérifiables. Les formulaires de certificat en définissent la mise en page ; la génération lie un formulaire à une fiche au moyen des noms de champs.

Un formulaire peut contenir plusieurs zones de code QR Vlink. La génération d’un certificat accepte une configuration Vlink par identifiant de zone et renvoie chaque association émise entre une zone et un Vlink.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — gérer les formulaires
• POST /api/v1/certificates/preflight — vérifier qu’un formulaire peut être résolu par rapport à une fiche
• POST /api/v1/certificates/generate — émettre un certificat
• GET /api/v1/certificates — répertorier les certificats d’une fiche
• POST /api/v1/certificates/void — en invalider un

Concepts : Certificats.

Pages publiques

Une page publique est la vue web non authentifiée d’une fiche — le passeport produit numérique auquel accède un consommateur en scannant un identifiant. Son contenu est entièrement déterminé par un modèle de page publique réutilisable appartenant à l’équipe. La publication ne nécessite donc aucune donnée de contenu propre à chaque fiche : elle résout le modèle par rapport à la fiche. L’URL d’une page est réservée et liée avant toute publication, ce qui permet d’imprimer les étiquettes en premier.

La publication d’un modèle fige une version de modèle immuable ; chaque page est associée à une version de modèle et à un instantané de données (les valeurs résolues pour cette fiche). Un lot de publication republie chaque page d’un périmètre — dossier, catégorie, modèle ou sélection explicite — au moyen d’une même version de modèle, sous la forme d’une exécution en arrière-plan dotée de son propre suivi de progression et de ses propres décomptes d’échecs.

La réservation de l’URL d’une page et sa liaison à une fiche relèvent du niveau membre — réserver une adresse ne publie rien, ce qui permet d’imprimer les étiquettes avant même qu’une décision de publication soit prise. Toutes les opérations qui rendent des données publiques — publier une page, l’activer ou l’archiver, créer un modèle, publier une version de modèle, effectuer un déploiement et lancer des lots de publication — nécessitent l’autorisation publisher de l’équipe (implicite pour l’administrateur de l’équipe), tout comme les vérifications préalables et les aperçus. Le champ x-required-role de chaque opération dans la référence de l’API fait autorité.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — réserver une URL de page permanente, puis la lier à une fiche
• GET / PUT /api/v1/public-pages/thread/{threadId} — consulter la page d’une fiche, ou l’obtenir en la créant si nécessaire
• GET /api/v1/public-pages/thread/{threadId}/activity — vues anonymes et scans de vérification sur la page publiée
• POST /api/v1/public-pages/{publicPageId}/publish — publier un instantané au moyen de la dernière version du modèle
• PATCH /api/v1/public-pages/{publicPageId} — activer ou archiver une page sans modifier son URL
• GET /api/v1/public-pages/{publicPageId}/publications — historique des publications
• POST /api/v1/public-pages/preflight / preflight/batch — vérifier qu’un modèle peut être résolu par rapport à une ou plusieurs fiches
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — créer le brouillon d’un modèle
• POST /api/v1/public-page-designs/{designId}/versions — publier une version de modèle (GET les répertorie)
• POST /api/v1/public-pages/designs/{designId}/roll-out — déployer la dernière version d’un modèle sur ses pages
• POST /api/v1/public-pages/waves — lancer un lot de publication (GET permet d’obtenir sa fiche d’exécution, ses éléments et sa liste)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — réessayer les opérations ayant échoué ou arrêter le travail restant

Le déploiement ne s’effectue que vers l’avant : une version de modèle n’est jamais restaurée, et l’annulation d’un lot laisse les pages déjà publiées sur la version qu’elles ont reçue.

Concepts : Pages publiques.

Événements

Chaque modification significative — changements de champs, liaisons, partages, expéditions — est consignée sous forme d’événement, constituant la piste d’audit affichée comme journal des transactions dans DICE.

• GET /api/v1/events — répertorier les événements, avec filtrage par fiche, équipe, action et heure, ainsi qu’un regroupement facultatif par activité (groupBy)
  • lineage=upstream (avec threadId) renvoie également les événements de chaque fiche antérieure de la filiation Fabric de la fiche — l’histoire complète d’une fiche reçue — dans les limites de ce que chaque source a divulgué. Les lignes en amont comportent un objet lineage (fiche source, équipe source, relation, saut) et peuvent être redacted ; un changement ultérieur de divulgation par une source apparaît sous la forme d’une ligne en lecture seule fabric.disclosure.revised. Sans ce paramètre, la réponse ne contient que les événements propres à la fiche.
  • resourceId, tagId ou fieldId (un seul à la fois, avec threadId) limitent l’historique à un fichier, un identifiant ou un champ ; un certificat est désigné par son fichier. Avec lineage=upstream, c’est la filiation propre à la ressource qui est suivie.
  • Une fiche reçue dans une expédition ou créée par une division ouvre son historique par transfer.received / slice.derived, attribué à la personne qui a accepté ou divisé ; elle ne comporte aucun created.thread ni bind qui lui soit propre.
• GET /api/v1/summary — principales mesures de décompte
• GET /api/v1/notifications — notifications de l’appelant

Étapes suivantes

Démarrage rapide

Effectuez votre premier appel authentifié dans le guide de démarrage rapide.

Client TypeScript

Utilisez le client typé @dustid/apid-client plutôt que des requêtes HTTP brutes.

Conventions

Consultez les en-têtes, la pagination et les erreurs dans les conventions de l’API.

Référence complète

Retrouvez chaque chemin, paramètre et schéma dans la référence de l’API.

Reçus PDF

Téléchargez un PDF à la demande avec GET /api/v1/receipts/{kind}/{id}, où kind vaut file, thread ou shipment, et où id est l’UUID correspondant. Utilisez votre authentification habituelle ainsi que les en-têtes de contexte de l’organisation et de l’équipe actives. La réponse est de type application/pdf, avec un nom de fichier joint et une mise en cache private et no-store. Accept-Language sélectionne la langue du reçu.

Les reçus de fichiers incluent les métadonnées, la somme de contrôle SHA-256 enregistrée lorsqu’elle est disponible, les informations sur la fiche associée et les entrées autorisées du journal des transactions. Les reçus de fiches incluent les champs, les identifiants, les fichiers et sommes de contrôle, les relations, les informations d’assemblage et de filiation ainsi que les journaux autorisés. Les reçus d’expéditions commencent par les informations sur l’expédition, son statut actuel et son manifeste, puis incluent les détails et journaux des fiches visibles. Les expéditions en attente utilisent les instantanés proposés ; les autres statuts utilisent les enregistrements auxquels l’appelant a actuellement accès.

Pour un fichier visible par l’intermédiaire d’une divulgation, fournissez linkId ; pour un fichier proposé dans une expédition en attente, fournissez transferId. Ces paramètres de requête UUID facultatifs ne peuvent pas être combinés et s’appliquent uniquement aux reçus de fichiers. Ils conservent les mêmes restrictions d’accès et de divulgation que l’aperçu correspondant.

Les reçus incluent un horodatage de génération et un lien QR vers DICE. Ce sont des instantanés non signés des enregistrements visibles par l’appelant, pas des signatures numériques. La génération est en lecture seule : aucune pièce jointe de reçu ni aucun événement du journal des transactions n’est enregistré. Les exportations dépassant 10 000 événements visibles dans un journal échouent au lieu d’être tronquées silencieusement. Les liens d’un reçu nécessitent toujours un accès à DICE.