Definition
护照 API 提供哪些端点？
四组。护照类端点负责签发、读取、更新产品记录并进行版本管理。事件类端点负责追加与查询 EPCIS 2.0 事件。凭证类端点负责签发、验证与吊销签名声明。解析类端点提供扫描数据载体后所走的公开 GS1 Digital Link 路径。
If you have not read the API model yet, start there. The relationships between these four decide which one you should be calling, and that is the choice most integrations get wrong first.
端点
护照
产品记录及其访问策略。多数集成最终调用最频繁的，是缺口端点。
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/passports | Issue a passport against a GS1 identifier |
| GET | /v1/passports/{id} | Read the full record your key is entitled to |
| PATCH | /v1/passports/{id} | Update the record; material changes are versioned |
| GET | /v1/passports/{id}/gaps | Fields the product group’s delegated act still requires |
| GET | /v1/passports/{id}/versions | The record’s version history |
| GET | /v1/passports | List and filter passports in your tenant |
端点
事件
仅追加的 EPCIS 2.0 历史。历史数据回补请使用批量接口；单条接口针对时延而非吞吐量做了优化。
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/events | Append one EPCIS 2.0 event |
| POST | /v1/events/bulk | Asynchronous bulk ingestion; returns a job |
| GET | /v1/events | Query by object identity, business step or time |
| GET | /v1/jobs/{id} | Status of a bulk ingestion job |
端点
凭证
已签名的声明。任何持有该凭证的人都可以验证，且不需要这些端点 —— 它们只是便利，而非依赖。
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/credentials | Issue a signed claim against a passport |
| GET | /v1/credentials/{id} | Retrieve a credential and its status |
| POST | /v1/credentials/{id}/revoke | Revoke; verification fails from this point |
| POST | /v1/credentials/verify | Verify a credential you were presented |
端点
解析
公开路径。无需认证、可缓存，并返回调用方凭证所对应的层级。
| 方法 | Path | Purpose |
|---|---|---|
| GET | /01/{gtin} | GS1 Digital Link resolution — the path a scan takes |
| GET | /01/{gtin}/21/{serial} | Resolution for an item-level passport |
约定
错误、分页与幂等性
这些适用于上述所有端点。在客户端统一处理一次，好过在每个调用点分别处理。
约定
# Validation errors return every problem at once.
HTTP/1.1 422 Unprocessable Entity
{
"error": "validation_failed",
"problems": [
{ "field": "materials[0].share", "constraint": "must sum to 1.0" },
{ "field": "carbonFootprint.method", "constraint": "required for this group" }
]
}
# Pagination is cursor-based: an offset would skip or repeat
# records as new events arrive while you are reading.
GET /v1/events?object=01/09506000134352&cursor=ev_8f21...
# Send an idempotency key on any write you might retry.
POST /v1/passports
Idempotency-Key: 6f1c9a7e-... # a repeat returns the original result答疑
常见问题
错误响应长什么样？
返回常规的 HTTP 状态码，并附带结构化响应体，指明错误、未通过校验的字段以及被违反的约束。校验错误一次性全部返回，而非逐条给出，因此格式有误的产品记录会在一次响应中暴露全部问题，而不必往返五次。
分页如何处理？
采用游标而非偏移量。事件历史在您读取期间仍在增长，使用偏移量会随着新事件的到来而悄悄跳过或重复记录。游标是不透明且稳定的；请传入上一页返回的游标，直到不再返回游标时停止。
写操作是幂等的吗？
可以，而且应当如此。对任何可能重试的写入请附带幂等键；使用相同键的重复请求会返回原始结果，而不会创建第二份护照或重复事件。若没有幂等键，写入时的网络超时会让您无从判断该操作是否已生效。
读取护照与解析护照有什么区别？
读取需要认证，并只返回您的 API 密钥所对应的内容。解析则是扫描所做的事：公开、匿名、可缓存，并返回调用方凭证所允许的层级 —— 对多数调用方而言就是公开层级。二者是不同的路径，性能与隐私特性也不同。