Definition
パスポート API のクライアントライブラリで何が得られますか。
API が検証に用いるスキーマから生成された型により、項目の誤りは実行時エラーではなくコンパイル時に検出されます。レート制限ヘッダーに従う再試行とバックオフ。生のボディに対する Webhook 署名検証。そして、クライアントがモデル化していないリクエストのための退避経路。
None of it is essential. Every payload is JSON following a published standard, so an integration written with an HTTP client and no SDK at all is a completely reasonable choice — and one some security policies require.
クライアント
利用できるもの
| Language | Typical use | Notes |
|---|---|---|
| TypeScript / Node.js | Storefronts, webhook receivers, serverless issuing | Types generated from the schema; works in edge runtimes |
| Python | Data pipelines, PLM and ERP integration jobs | Fits where the sustainability data work already happens |
| Go | High-throughput event ingestion services | For services writing events continuously rather than in batches |
| Anything else | Direct HTTP | JSON, GS1 and W3C standards — no client required |
形
使うときの実際
import { CirculeID } from '@circuleid/sdk';
const circuleid = new CirculeID({ apiKey: process.env.CIRCULEID_API_KEY });
const passport = await circuleid.passports.create({
gtin: '09506000134352',
productGroup: 'textiles',
level: 'model',
record: { name: 'Merino Crew Knit' },
});
// The gap report is part of the response, not a separate call:
// which fields the delegated act still requires for this group.
console.log(passport.gaps);
// Escape hatch — same auth, same retries, no abstraction in the way.
await circuleid.request('POST', '/v1/events', { body: epcisEvent });彼らが担う範囲
自前で書かないほうがよい部分
生成された型定義
APIが検証に用いるのと同じスキーマから生成するため、両者が食い違うことはありません。
再試行とバックオフ
レート制限のヘッダーを読み、ジッターを適用するため、並列ワーカーが行儀よく振る舞います。
署名の検証
生のボディに対し、一定時間で比較します。ここを取り違える例が二つとも多い箇所です。
ページネーション
長いイベント履歴のためのカーソル処理を、非同期イテレータとして提供します。
エスケープハッチ
型付き呼び出しと同じ認証および再試行の挙動を持つ、任意のリクエスト。
予測可能なバージョニング
メジャーはAPIのバージョンに従い、マイナーは追加のみで、再定義は行いません。
回答
よくある質問
SDK は HTTP のラッパー以上に何をしてくれますか。
持っておく価値のあるものが3つあります。API が検証に用いるのと同じスキーマから生成された型（項目の誤りが 400 ではなくコンパイルエラーになります）。レート制限ヘッダーに従う再試行とバックオフ。そして Webhook 署名の検証です。これは生のボディではなく再シリアライズしたボディをハッシュ化してしまい、気づきにくい形で誤実装しやすい部分です。
生のリクエストも引き続き送れますか。
はい。クライアントはそれを許すよう作られています。いずれのクライアントにも、同じ認証と再試行の挙動で任意のリクエストを送れる退避経路が用意されています。自らの抽象を通ることを強制する SDK は、想定外の要件が生じた最初の瞬間に戦う相手になります。
SDKのバージョンとAPIのバージョンはどう対応しますか。
メジャーバージョンは API バージョンに対応するため、v1 クライアントは /v1 と通信します。マイナーリリースは API の成長に応じてエンドポイントと項目を追加します。同一メジャーバージョン内でクライアントの挙動が黙って変わることはありません。新しい項目が追加されるだけで、既存項目の意味は変わりません。
発行パイプラインにはどの言語を使うべきですか。
貴社の運用チームがすでに扱っている言語です。発行経路は貴社の PLM と当社を結ぶスケジュール実行のジョブであり、性能面の要求は高くありません。保守するのは、貴社の他の連携を保守している担当者です。社内の誰も知らない言語を選ぶことが、ここで最も避けやすい失敗です。
クライアントはオープンソースですか。
クライアントは公開されたスキーマから生成され、生成されたソースは可読で、社内に取り込めます。社内方針を満たすためにフォークが必要でも、通信プロトコルは当社のクライアントに依存しません。すべてのペイロードは、貴社が直接実装できるGS1またはW3Cの標準に従います。