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 状态码，并附带结构化的错误响应体，指明未通过的字段与被违反的约束。校验错误一次性全部返回，而非逐条给出，因此格式有误的产品记录会在一次响应中暴露全部问题，而不必往返五次。
集成过程中我们如何获得支持？
通过您账户下的支持渠道；若仍在评估阶段，可通过联系方式与我们沟通。凡是暴露文档缺口的集成问题，都按文档缺陷处理——这是随着 API 不断扩展、参考文档仍能保持准确的唯一办法。