ERP から来歴を記録する

業務システムは、DICE が直接把握できないイベントを扱っています。たとえば、SAP での入庫、MES での検査承認、コマースプラットフォームでの販売成立などです。申告取引を使用すると、これらの出来事が発生した時点で、連携システムからスレッドの履歴に書き込めます。各イベントは帰属先が明示された永続的なエントリとなり、アイテムの来歴とともに引き継がれ、そのアイテムの公開ページにも表示できます。

このレシピでは、ERP（同じ構成を WMS、MES、その他あらゆる記録システムにも適用できます）を POST /api/v1/events/declare に接続します。サービスアカウントとして認証し、各エントリを、システム内で操作を行った人間のオペレーターに帰属させます。

フローの概要

連携システムがサービスアカウントの認証情報を、有効期間の短い bearer トークンと交換します（認証）。
システム内で、出庫、検査、修理完了などのイベントが発生します。
連携システムが、スレッド id、見出し、および主張の日時と場所を指定して POST /api/v1/events/declare を呼び出し、オペレーターの識別情報を Dust-Ctx-Declared-Actor ヘッダーで送信します。
エントリが DICE のスレッドの取引ログに表示され、申告済みと明示されます。また、サービスアカウントがオペレーターに代わって実行したものとして帰属先が示されます。

前提条件

API キーまたは OAuth クライアントを持つサービスアカウント。詳しくは認証を参照してください。サービスアカウントには、書き込み先となるスレッドへの編集アクセス権が必要です（そのスレッドを所有するチームへのアクセス権を付与してください）。
Dust-Ctx-Org-Id ヘッダーに指定する組織 id、およびサービスアカウントが特定のチームとして動作する場合はそのチーム id。詳しくはリクエスト規約を参照してください。
関係するアイテムのスレッド id。通常、連携システムでは、シリアル番号、バッチ番号、注文番号など、対象システムと共有するフィールドを使い、GET /api/v1/threads で検索して解決します（スレッド API ガイドを参照）。

取引を申告する

1 回の呼び出しで、1 つのスレッドに 1 つのエントリを記録します。

curl
TypeScript

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

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

リクエストフィールドは次のとおりです。threadId 以外はすべて任意ですが、内容が完全に空の申告は拒否されます。

フィールド	型	備考
`threadId`	UUID	エントリが属するスレッド。編集アクセス権が必要です。
`title`	string ≤ 80	短い見出し。フィードやページでエントリのタイトルとして表示されます。
`note`	string ≤ 4000	発生した出来事の自由記述による詳細。
`kind`	string ≤ 64	自由形式の分類。`sale`、`inspection`、`repair`、`service` など、独自の語彙を使用できます。デフォルトは `other` です。
`edtf`	string ≤ 64	実際に把握している精度で指定する発生日時。詳しくは後述します。省略すると、現在時点の出来事として記録されます。
`location`	object	申告する場所：`{ "name": string, "latitude"?: number, "longitude"?: number }`。画面に表示されるのは `name` です。
`resIds`	UUID[] ≤ 25	証拠となるファイルの id。検査報告書や証明書など、エントリを裏付ける、すでにスレッドへ添付されているファイルを指定します。そのスレッドに添付されていないファイルの id は拒否されます。

レスポンスでは、実体化された主張が返されます。これには kind、title、note のほか、主張の display 文字列、精度、境界を保持する構造化された when オブジェクトが含まれます。

把握している精度で日時を記述する

edtf には EDTF（ISO 8601-2）のサブセットを指定できます。これにより、システムが保持している精度どおりに、年、月、日、期間、または概算として主張を記録できます。

主張	`edtf`	表示
正確な日	`2026-07-14`	2026年7月14日
月	`2026-07`	2026年7月
年	`1968`	1968年
終端が定まった期間	`1968/1970`	1968～1970年
およその時期	`1835~`	1835年頃
指定日より前	`../1970-03`	1970年3月より前
指定日より後	`2019/..`	2019年より後

主張は、指定した精度のまますべての場所に表示されます。1968/1970 という期間が、捏造された正確な日付に変換されることはありません。午前 0 時のタイムスタンプを推測で付けるのではなく、実際に把握している精度で送信してください。

人間のオペレーターに帰属させる

サービスアカウントは、あなたのシステムを認証します。Dust-Ctx-Declared-Actor ヘッダーでは、リクエストごとに、そのシステム内で操作を行った人物を指定します。

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

id は必須で、system、displayName、role は任意です。JSON 値は 1 KB 未満に収める必要があります（ASCII 以外の文字を含む場合は URI エンコードしてください）。申告された実行者は、そのリクエストが書き込むすべてのエントリにそのまま記録され、履歴では申告された帰属情報として表示されます。この情報は連携システムが提供するもので、DICE が検証したものではなく、権限にも一切影響しません。組織管理者はこの情報を必須に設定できます。その場合、この情報がない書き込みは 403 ATTRIBUTION_REQUIRED で拒否されます。完全なセマンティクスについては、申告された実行者への帰属を参照してください。

申告された来歴を扱う場合、このヘッダーは独自コードでも必須として扱う価値があります。「検査済み — 合格」という主張は、「SAP Connector」だけが付いている場合よりも、「Jane Doe, Quality Inspector」が付いている場合のほうがはるかに説得力があります。

ロット全体にわたって申告する

1 つの業務イベントが多数のアイテムに関係する場合（たとえば、シリアル管理された 200 個の入庫やロット単位の検査）は、それらすべてに対して一度に申告します。

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 には 1～500 個のスレッド id を指定できます。書き込みはすべて成功するか、すべて失敗するかのいずれかであり、バッチ内のすべてのスレッドに対する編集アクセス権が必要です。
すべてのスレッドに同じ主張が記録されます。バッチ内でスレッドごとに内容を変えることはできません。アイテムごとに異なるデータ（シリアル、バッチ、測定結果）は、主張ではなくスレッドのフィールドに格納してください。
レスポンスには、共有の operationId が含まれます。これはバッチを訂正するためのハンドルとなるため、保存してください（後述）。

多数のエントリを一度にバックフィルする

/declare/batch は、1 つの主張を多数のスレッドに書き込みます。過去データのバックフィル、スプレッドシートシステムからの移行、1 日分の製造現場イベントなど、相互に異なる多数の主張を送信する場合は、代わりに /declare/rows を使用します。各行は threadIds 内のすべてのスレッドに書き込まれ、全体で 1 つの 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" }
    ]
  }'

リクエストごとに最大 100 行、500 スレッドまで指定でき、エントリ総数は 2,000 件（threadIds.length × rows.length）が上限です。それ以上のバックフィルは分割してください。
リクエスト全体が、すべて成功するか、すべて失敗するかのいずれかです。認識できない日付が 1 つでもあると、すべての行が拒否されます。これにより、1 件ずつ撤回するしかない不完全なバックフィルが残ることを防ぎます。
行には anchor も証拠の resIds も指定できません。どちらも単一の主張に対して行う操作です。これらには /declare を使用してください。
/declare/batch は、このエンドポイントの 1 行の場合に相当します。主張が本当に 1 つである場合は、引き続きこちらを使用してください。

これは、DICE 自体の CSV インポートが送信するものと同じエンドポイントです。顧客がシステムからではなく手作業でバックフィルする場合は、連携システムを構築する代わりに、過去のイベントを記録するを案内してください。

誤りを訂正する

申告されたエントリは不変です。編集も削除もできません。訂正は、最初の内容が誤っていたことを示す、帰属先付きの 2 つ目のエントリとなる撤回によって行います。元のエントリは撤回済みと明示された状態で履歴に残り、両方のエントリが記録とともに後続へ引き継がれます。つまり、消去ではなく訂正記録です。

1 つのバッチによって書き込まれたすべてのエントリを撤回する場合（たとえば、ERP で入庫が取り消された場合）は、保存してある 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)."
  }'

これにより、その操作によって書き込まれ、まだ有効なすべてのエントリが撤回されます。すでに個別に撤回されているエントリはスキップされます。また、関係するすべてのスレッドに対する編集アクセス権が必要です。単一のエントリは、そのイベント id を使用して撤回します。任意の reason を付け、POST /api/v1/events/{event_id}/retract を呼び出してください。イベント id はスレッドの履歴（GET /api/v1/events?threadId=…）から取得できます。

撤回後、新たな申告によって訂正済みのエントリを記録します。誤ったエントリとその訂正からなるこの組み合わせが、偽りのない記録の形です。

公開ページはスナップショットを公開するため、新しいエントリや撤回がページに反映されるのは、ページが再公開された時点です。ページのデザインで現在の製品パスポートを使用するポリシーが設定されている場合、申告または撤回が成功すると、現在提供中のバージョンを基準として自動的に再公開されます。それ以外の場合、ページでは以前のスナップショットが引き続き表示され、記録より遅れているものとして一覧表示され、次回の公開時に更新されます。どちらの場合も、撤回された主張は消えるのではなく、取り消し線と撤回済みの表示が付いた状態でレンダリングされます。公開済みの来歴が密かに書き換えられることはありません。

エラーとなる場合

レスポンス	意味
`400 INVALID_DATA`	`edtf` の値が対応するサブセットの範囲外である、実在する暦日ではない、申告内容が空である、または証拠の id がそのスレッドに添付されていません。
`400 INVALID_REQUEST`	本文の形式が不正です。たとえば、フィールドが長さの上限を超えています。
`403 ATTRIBUTION_REQUIRED`	サービスアカウントのポリシーで申告された実行者が必須ですが、リクエストに含まれていません。
`404 NOT_FOUND`	呼び出し元から参照できない、または存在しないスレッド id です。バッチエンドポイントでは、そのような id が 1 つでもあるとバッチ全体が失敗します。

エラー本文は標準の規約に従います。リクエスト規約を参照してください。また、各コードのステータスと再試行に関するガイダンスについては、エラーとスキャン結果を参照してください。

次のステップ

認証と API キー — サービスアカウント、トークン交換、申告された実行者のセマンティクス。
エラーとスキャン結果 — 401 の更新動作を含む、完全なエラー規約。
スレッド API ガイド — システム内のシリアル番号や注文番号からスレッド id を解決する方法。
過去のイベントを記録する — オペレーターが DICE で使用する場合の同じ機能。
公開ページ — 申告されたエントリがアイテムの公開製品パスポートにどのように表示されるか。

ドキュメントの問題を報告