Definition
一次典型的护照集成实际做了什么？
五项反复进行的操作。针对 GS1 标识签发护照。随产品流转追加 EPCIS 2.0 事件。收集供应商签名的声明。核验他人出示的声明。以及在有人扫描产品上的数据载体时，返回公开视图。
The volume is dominated by the first two. The difficulty is dominated by the third, which is a supplier relationship problem rather than a technical one.
01
签发一份护照
curl https://api.circuleid.com/v1/passports \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 }
],
"carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
}
}'02
追加一条供应链事件
curl https://api.circuleid.com/v1/events \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{
"type": "ObjectEvent",
"action": "OBSERVE",
"eventTime": "2026-03-14T09:22:00+01:00",
"epcList": ["urn:epc:id:sgtin:0950600.013435.SN8817403"],
"bizStep": "urn:epcglobal:cbv:bizstep:commissioning",
"disposition": "urn:epcglobal:cbv:disp:active",
"bizLocation": { "id": "urn:epc:id:sgln:0950600.00001.0" }
}'03
为供应商声明签名
curl https://api.circuleid.com/v1/credentials \
-H "Authorization: Bearer $SUPPLIER_API_KEY" \
-d '{
"type": "RecycledContentCredential",
"issuer": "did:web:mill.example.com",
"subject": "01/09506000134352",
"validUntil": "2027-03-14T00:00:00Z",
"claim": {
"material": "polyamide",
"recycledShare": 0.18,
"basis": "mass",
"chainOfCustody": "mass-balance"
}
}'04
验证他人向您出示的主张
curl https://api.circuleid.com/v1/credentials/verify \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{ "credential": { /* the credential as presented */ } }'
# {
# "verified": true,
# "issuer": "did:web:mill.example.com",
# "issuedAt": "2026-03-14T09:31:02Z",
# "status": "active" # "revoked" fails verification
# }05
响应一次扫描
# What the phone requests when a consumer scans the carrier:
curl https://id.circuleid.com/01/09506000134352 \
-H "Accept: application/json"
# A browser gets the rendered public passport instead.
# A verified recycler presenting a credential gets the treatment tier
# from the same URL — the resolver decides, not the caller.模式
它们通常各自位于何处
签发流水线
一个定时任务，读取 PLM 并为下一批生产签发护照。
事件摄取
一项服务，在 WMS 与 MES 消息产生时即将其转换为 EPCIS 事件。
供应商门户
二级供应商在此提交并签署那些您自己无法主张的内容。
店面
读取公开层级，以便在商品页面上展示有据可依的可持续性数据。
载体本身
完全不需要贵方编写任何代码 —— 解析器直接响应这次扫描。
回收进料
在退货或回收设施的作业线上读取处理层级。
答疑
常见问题
我该从哪个示例开始？
先签发一份护照，再追加一条事件。这两步覆盖了一次集成的大部分流量，并迫使您敲定标识模型 —— 型号、批次还是单件 —— 这是其余一切所依赖、也是日后最难更改的决定。
第一天就必须处理凭证吗？
不需要。数据未经签名的护照仍然是一份可用的护照，只是无法证明每个数字是谁作出的。多数项目先行签发，随着供应商陆续接入再补上带签名的供应商声明 —— 这也正是供应商协同在现实中所允许的顺序。
消费者从一次扫描中实际获得什么？
护照的公开层级，从载体中的 GS1 Digital Link 标识符解析而来，面向浏览器渲染为页面，或按系统请求以 JSON 返回。无需认证、无需账户，也不会为扫码者建立任何画像。
我们能在不触碰生产环境的情况下测试吗？
可以。沙箱密钥对应另一个主机名，沙箱护照的行为与生产护照完全相同。由于生产护照是长期公开的产物，这一隔离是强制执行的，而非约定俗成——沙箱密钥根本无法抵达生产环境。