Definition
API経由でデジタル製品パスポートをどう発行しますか。
GS1識別子に対して製品レコードを伴うパスポートリソースを作成し、製品の移動に応じてEPCIS 2.0イベントを追加し、証明が必要な主張についてW3C Verifiable Credentialsを発行します。読み取りは識別子を解決し、呼び出し元のクレデンシャルが認めるビューを返します。
The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.
クイックスタート
最初のパスポート
curl https://api.circuleid.com/v1/passports \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"gtin": "09506000134352",
"productGroup": "textiles",
"level": "model",
"record": {
"name": "Merino Crew Knit",
"materials": [
{ "name": "merino wool", "share": 0.82, "certification": "RWS" },
{ "name": "recycled polyamide", "share": 0.18 }
]
}
}'Illustrative request shape. The API reference carries the authoritative schema and error contract.
連携の進め方
APIキーから、解決可能なパスポートへ
- 01
スコープ付きのキーを取得
キーは環境ごと、機能ごとに限定されるため、発行サービスが制限付きデータへの読み取り権限を持つことはありません。
- 02
製品レコードを対応づける
製品マスターをそのGS1識別子に対して送信してください。応答が、当該製品グループにまだ必要な項目を示します。
- 03
イベントとクレデンシャルを追加する
品物の移動に合わせて EPCIS 2.0 イベントを書き込みます。独立した検証に耐える必要のある主張にはクレデンシャルを発行します。
- 04
解決して購読する
識別子は呼び出し元に応じたビューへ解決し、何かが変化すれば Webhook が貴社のシステムへ通知します。
回答
よくある質問
パスポートを発行する前に何が必要ですか。
APIキー、製品のGS1識別子、そして製品レコードそのものです。GS1識別子をまだお持ちでない場合は、それが最初に解消すべき依存関係です。識別子は当社ではなく貴社が加盟するGS1組織から取得します。識別子は当社プラットフォームの外でも世界的に一意でなければならないためです。
サンドボックスはありますか。
はい。鍵は環境ごとにスコープが分かれており、サンドボックスの鍵で本番のパスポートに触れることはできず、本番の鍵を誤ってテスト環境で使うこともできません。サンドボックスのパスポートは、別のリゾルバーのホスト名に対して本番とまったく同じように解決されます。
ワイヤーフォーマットは何ですか。
APIはHTTPS上のJSONです。イベントはGS1 EPCIS 2.0のJSON-LDシリアライズに、クレデンシャルはW3C Verifiable Credentials 2.0のデータモデルに従います。標準が表現を定めている場合は、独自に作らずそれを用います。したがって、その標準向けの既存ツールが当社の出力にそのまま使えます。
エラーはどう扱うべきですか。
APIは一般的なHTTPステータスコードと、失敗した項目および違反した制約を示す構造化されたエラーボディを返します。検証エラーは一件ずつではなくすべてまとめて返すため、不正な製品レコードは5往復ではなく1回の応答で全問題が判明します。
連携作業中のサポートはどう受けられますか。
ご契約アカウントのサポート窓口から、評価段階であればお問い合わせ経路からご連絡ください。ドキュメントの不足を明らかにする連携上の質問は、ドキュメントの不具合として扱います。API が拡張していくなかでリファレンスを正確に保つ方法は、これ以外にありません。