Definition
如何通过 API 签发数字产品护照？
针对某个 GS1 标识创建护照资源、附上产品记录，随物品流转追加 EPCIS 2.0 事件，并为必须可证明的声明签发 W3C Verifiable Credentials。读取时解析该标识，并返回调用方凭证所对应的视图。
The wire format is not ours. Identity follows GS1 Digital Link, events follow EPCIS 2.0, and claims follow W3C Verifiable Credentials 2.0.
快速上手
一次请求即可签发护照
curl https://api.circuleid.com/v1/passports \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"gtin": "09506000134352",
"productGroup": "textiles",
"record": {
"name": "Merino Crew Knit",
"materials": [
{ "name": "merino wool", "share": 0.82, "certification": "RWS" },
{ "name": "recycled polyamide", "share": 0.18 }
],
"carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
}
}'Illustrative request shape. See the API reference for the authoritative schema and error contract.
集成路径
从 API 密钥，到一份可解析的护照
- 01
进行认证
创建限定作用域的 API 密钥。密钥按环境、按能力分别限定，因此签发服务永远不会持有对商业数据的读取权限。
- 02
映射产品记录
把贵方现有的产品主数据提交到其 GS1 标识之下。API 会报告：依据该产品组的授权法案，还需要哪些字段。
- 03
追加事件与凭证
随着物品流转写入 EPCIS 2.0 事件，并为那些必须经得起独立审视的主张签发可验证凭证。
- 04
解析并订阅
Digital Link 标识符会解析为与调用方相称的视图。当护照、事件或凭证发生变化时，Webhook 会通知您的系统。
Developers · 01
构建
Developers · 02
运营
答疑
常见问题
CirculeID 的 API 实际签发什么？
一个带有 GS1 Digital Link 标识的护照资源，一组附着其上的 EPCIS 2.0 事件，以及承载需要可证明之声明的 W3C Verifiable Credentials。读取护照即是解析该标识，并返回调用方有权获得的视图，而这取决于其出示的凭证。
我们必须把产品数据迁移到 CirculeID 吗？
不是。CirculeID 位于贵方 ERP、PLM 与碳核算系统之上，而不是取代它们。数据通过 REST API 与 Webhook 流入，护照成为对这些既有系统的一个视图。多数集成的起点是映射既有的产品主数据，而不是把它导入进来。
护照数据在系统之间如何认证？
机器对机器访问使用限定作用域的 API 密钥。护照内的声明由签发方以 W3C Verifiable Credentials 形式签名，并使用可独立于 CirculeID 解析的 Decentralized Identifier —— 因此下游系统完全无需调用我们，即可核验供应商的声明。
如果我们不再使用 CirculeID，我们的护照会怎样？
护照以已公开发布的标准表达，因此这份记录在我们平台之外依然有意义。标识遵循 GS1 Digital Link，事件遵循 EPCIS 2.0，凭证遵循 W3C Verifiable Credentials 2.0，字段模型遵循 CIRPASS。导出所得，与另一个符合规范的解析器所能提供的文档完全相同。