Consigner la provenance depuis votre ERP

Les systèmes métier voient des événements dont DICE n’est jamais témoin : une réception de marchandises dans SAP, la validation d’une inspection dans votre MES, une vente conclue sur votre plateforme de commerce. Les transactions déclarées permettent à votre intégration de consigner ces événements dans l’historique d’une fiche au moment où ils se produisent — chacun sous la forme d’une entrée attribuée et permanente qui accompagne la provenance de l’élément et peut apparaître sur sa page publique.

Cette procédure connecte un ERP (la même structure convient à un WMS, un MES ou tout autre système de référence) à POST /api/v1/events/declare, avec une authentification en tant que compte de service et l’attribution de chaque entrée à l’opérateur humain qui a effectué l’action dans votre système.

Note

Une entrée déclarée est une assertion attribuée de votre organisation — jamais un fait vérifié par la plateforme. DICE consigne qui l’a déclarée et quand, l’affiche comme étant déclarée et ne la présente jamais comme un événement observé par la plateforme. Elle est également permanente : elle est partagée avec les propriétaires en aval, avec le reste de l’historique de la fiche, et ne peut pas être supprimée, mais seulement retirée — et un retrait constitue une seconde entrée visible, pas un effacement.

Vue d’ensemble du processus

1. Votre intégration échange les identifiants de son compte de service contre un jeton porteur à courte durée de vie (Authentification).
2. Un événement se produit dans votre système — une sortie de marchandises, une inspection, la clôture d’une réparation.
3. Votre intégration appelle POST /api/v1/events/declare avec l’id de la fiche, un titre ainsi que la date, l’heure et le lieu de l’assertion, en envoyant l’identité de l’opérateur dans l’en-tête Dust-Ctx-Declared-Actor.
4. L’entrée apparaît dans le journal des transactions de la fiche dans DICE, marquée Déclarée et attribuée au compte de service agissant pour le compte de votre opérateur.

Prérequis

• Un compte de service doté d’une clé API ou d’un client OAuth — consultez Authentification. Le compte de service doit disposer d’un accès en modification aux fiches dans lesquelles il écrira (accordez-lui l’accès à l’équipe propriétaire).
• L’id de votre organisation pour l’en-tête Dust-Ctx-Org-Id, ainsi que l’id de l’équipe si le compte de service doit agir au nom d’une équipe précise — consultez Conventions des requêtes.
• Les ids de fiche des éléments concernés. Une intégration les résout généralement en effectuant une recherche sur le champ commun avec votre système — un numéro de série, de lot ou de commande — via GET /api/v1/threads (consultez le guide de l’API des fiches).

Déclarer une transaction

Un appel consigne une entrée sur une fiche :

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();

Champs de la requête — tous sont facultatifs à l’exception de threadId, mais une déclaration entièrement vide est rejetée :

Champ	Type	Remarques
threadId	UUID	La fiche à laquelle appartient l’entrée. Nécessite un accès en modification.
title	string ≤ 80	Titre court — ce que les flux et les pages affichent comme titre de l’entrée.
note	string ≤ 4000	Description libre de ce qui s’est produit.
kind	string ≤ 64	Classification ouverte : sale, inspection, repair, service, … selon votre vocabulaire. La valeur par défaut est other.
edtf	string ≤ 64	Le moment où l’événement s’est produit, avec le degré de précision dont vous disposez réellement — voir ci-dessous. Omettez ce champ pour le consigner à la date et à l’heure actuelles.
location	object	Le lieu déclaré : { "name": string, "latitude"?: number, "longitude"?: number }. name est la valeur affichée.
resIds	UUID[] ≤ 25	Éléments probants : ids de fichiers déjà joints à la fiche qui documentent l’entrée — un rapport d’inspection, un certificat. Les ids de fichiers qui ne sont pas joints à cette fiche sont rejetés.

La réponse renvoie l’assertion matérialisée — les valeurs kind, title et note, ainsi qu’un objet when structuré contenant la chaîne display, la précision et les limites de l’assertion.

Indiquer le moment avec la précision connue

edtf accepte un sous-ensemble d’EDTF (ISO 8601-2), afin que l’assertion reflète exactement la précision dont dispose votre système — une année, un mois, un jour, une plage ou une approximation :

Assertion	edtf	Affichage
Un jour précis	2026-07-14	14 juil. 2026
Un mois	2026-07	Juillet 2026
Une année	1968	1968
Une plage fermée	1968/1970	1968–1970
Environ	1835~	Vers 1835
Avant une date	../1970-03	Avant mars 1970
Après une date	2019/..	Après 2019

L’assertion est affichée partout avec la précision que vous avez indiquée — une plage 1968/1970 n’est jamais réduite à une date précise inventée. Envoyez la précision dont vous disposez réellement, pas une estimation artificiellement horodatée à minuit.

Astuce

Les documents ERP comportent généralement une date de comptabilisation, pas un horodatage. Publiez la date (2026-08-06), pas un instant inventé — la fiche est ainsi plus fidèle et plus lisible dans la fiche et sur sa page publique.

Attribuer l’opérateur humain

Un compte de service authentifie votre système. L’en-tête Dust-Ctx-Declared-Actor désigne la personne qui y a effectué l’action, pour chaque requête :

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

id est obligatoire ; system, displayName et role sont facultatifs ; la valeur JSON doit rester inférieure à 1 Ko (encodez-la au format URI si elle contient des caractères non ASCII). L’acteur déclaré est consigné textuellement sur chaque entrée écrite par la requête et affiché dans l’historique comme une attribution déclarée — fournie par votre intégration, non vérifiée par DICE et sans aucune incidence sur les autorisations. Un administrateur de l’organisation peut rendre cette attribution obligatoire, auquel cas les écritures qui en sont dépourvues sont rejetées avec 403 ATTRIBUTION_REQUIRED. Pour la sémantique complète, consultez Attribution de l’acteur déclaré.

Pour la provenance déclarée, il est utile de traiter cet en-tête comme obligatoire dans votre propre code : « Inspection — conforme » constitue une assertion bien plus solide lorsqu’elle est accompagnée de « Jane Doe, inspectrice qualité » que lorsqu’elle mentionne seulement « Connecteur SAP ».

Effectuer une déclaration pour un lot entier

Lorsqu’un événement métier concerne de nombreux éléments — la réception de 200 unités sérialisées, une inspection au niveau du lot — déclarez-le une seule fois pour chacun d’eux :

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 accepte de 1 à 500 ids de fiche ; l’écriture est entièrement atomique et nécessite un accès en modification à chaque fiche du lot.
• La même assertion est ajoutée à chaque fiche — aucune variation par fiche n’est possible dans un lot. Les données qui diffèrent selon l’élément (numéro de série, lot, résultats de mesure) doivent figurer dans les champs de la fiche, et non dans l’assertion.
• La réponse comprend un operationId partagé. Conservez-le : il sert d’identifiant de correction pour le lot (voir ci-dessous).

Astuce

Le point de terminaison par lot fonctionne également avec un seul id de fiche et, contrairement au point de terminaison pour une entrée unique, il renvoie un operationId. Si votre intégration peut un jour devoir corriger une entrée par programmation, effectuer la déclaration via le point de terminaison par lot et stocker l’operationId avec votre document source vous fournit un identifiant durable.

Importer rétrospectivement plusieurs entrées à la fois

/declare/batch écrit une assertion dans plusieurs fiches. Lorsque vous devez publier plusieurs assertions différentes — un import rétrospectif d’historique, une migration depuis un système reposant sur des feuilles de calcul, les événements d’une journée dans l’atelier — utilisez plutôt /declare/rows. Chaque ligne est écrite dans chaque fiche indiquée dans threadIds, et l’ensemble partage un même 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" }
    ]
  }'

• Jusqu’à 100 lignes et 500 fiches sont acceptées, avec une limite de 2 000 entrées au total (threadIds.length × rows.length) par requête. Fractionnez les imports rétrospectifs plus volumineux.
• L’opération est entièrement atomique pour toute la requête : une seule date non reconnue entraîne le rejet de toutes les lignes, au lieu de laisser un import rétrospectif partiel composé d’entrées qui ne pourraient être retirées qu’une par une.
• Les lignes ne comportent ni anchor ni éléments probants resIds — tous deux sont propres à une assertion unique. Utilisez /declare dans ces cas.
• /declare/batch correspond au cas d’une seule ligne de ce point de terminaison ; continuez à l’utiliser lorsque l’assertion est réellement unique.

Il s’agit du même point de terminaison que celui auquel l’import CSV de DICE envoie ses données. Si vos clients importent manuellement un historique plutôt que depuis un système, orientez-les vers Consigner des événements passés au lieu de créer une intégration.

Corriger une erreur

Les entrées déclarées sont immuables — elles ne peuvent être ni modifiées ni supprimées. La correction prend la forme d’un retrait : une seconde entrée attribuée indiquant que la première était erronée. L’original reste dans l’historique, marqué comme retiré, et les deux entrées accompagnent la fiche en aval — un erratum, jamais un effacement.

Pour retirer toutes les entrées écrites par un lot (par exemple, si la réception de marchandises a été annulée dans votre ERP), publiez l’operationId stocké :

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)."
  }'

Cette opération retire chaque entrée encore active écrite par l’opération — les entrées déjà retirées individuellement sont ignorées — et nécessite un accès en modification à chaque fiche concernée. Une entrée unique est retirée à l’aide de son id d’événement : POST /api/v1/events/{event_id}/retract, avec un champ reason facultatif. Les ids d’événement proviennent de l’historique de la fiche (GET /api/v1/events?threadId=…).

Après le retrait, consignez une entrée corrigée au moyen d’une nouvelle déclaration — cette paire, composée de l’entrée erronée et de sa correction, constitue la représentation fidèle de la fiche.

Attention

Une page publique publie un instantané ; une nouvelle entrée ou un retrait n’atteint donc la page que lorsque celle-ci est republiée. Lorsque le modèle de la page utilise la politique de passeport dynamique, une déclaration ou un retrait réussi entraîne sa republication automatique avec la version qu’elle diffuse déjà. Sinon, la page continue d’afficher l’instantané précédent, est signalée comme n’étant plus à jour par rapport à sa fiche et sera actualisée lors de la prochaine publication. Dans les deux cas, l’assertion retirée apparaît barrée et marquée comme retirée au lieu de disparaître — une provenance publiée n’est jamais réécrite silencieusement.

Modes d’échec

Réponse	Signification
400 INVALID_DATA	La valeur edtf ne fait pas partie du sous-ensemble pris en charge ou ne correspond pas à une date réelle du calendrier, la déclaration est vide ou l’id d’un élément probant n’est pas joint à cette fiche.
400 INVALID_REQUEST	Corps mal formé — par exemple, un champ dépasse sa longueur maximale.
403 ATTRIBUTION_REQUIRED	La politique du compte de service exige un acteur déclaré et la requête n’en comporte aucun.
404 NOT_FOUND	Un id de fiche que l’appelant ne peut pas consulter ou qui n’existe pas. Sur le point de terminaison par lot, un seul id de ce type entraîne l’échec de l’ensemble du lot.

Les corps d’erreur suivent le contrat standard — consultez Conventions des requêtes, ainsi que Erreurs et résultats de scan pour connaître chaque code, son statut et les recommandations de nouvelle tentative.

Étapes suivantes

• Authentification et clés API — comptes de service, échange de jetons et sémantique de l’acteur déclaré.
• Erreurs et résultats de scan — le contrat complet en cas d’échec, y compris le comportement d’actualisation pour 401.
• Guide de l’API des fiches — résolution des numéros de série et de commande de votre système en ids de fiche.
• Consigner des événements passés — la même fonctionnalité telle que vos opérateurs la voient dans DICE.
• Pages publiques — la façon dont les entrées déclarées apparaissent dans le passeport public de l’élément.