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 用于校验的同一套 schema 生成，因此两者不可能出现偏离。
重试与退避
读取速率限制响应头并施加抖动，让并行工作进程守规矩。
签名验证
对原始请求体、以恒定时间比较 —— 这正是两个最常被弄错的细节。
分页
面向长事件历史的游标处理，以异步迭代器形式提供。
应急出口
任意请求，其认证与重试行为与类型化调用完全一致。
可预期的版本管理
主版本号跟随 API 版本；次版本号只做新增，绝不重新定义。
答疑
常见问题
除了封装 HTTP，SDK 还做了什么？
有三样东西值得拥有：由 API 用于校验的同一套模式生成的类型，使字段写错成为编译期错误而非 400；遵循限流响应头的重试与退避；以及 Webhook 签名校验——如果对重新序列化后的请求体而非原始请求体做哈希，就很容易实现得似是而非。
我还能发送原始请求吗？
可以，而且客户端就是为此设计的。每个客户端都提供一个退出通道，用同样的认证与重试行为发送任意请求。一个逼您必须走它那套抽象的 SDK，会在您第一次遇到它没预料到的需求时成为阻力。
SDK 版本与 API 版本是什么关系？
主版本号与 API 版本一致，因此 v1 客户端对接 /v1。次版本随 API 的演进新增端点与字段。在同一主版本内，客户端的行为不会在您无察觉的情况下改变——只会出现新字段，既有字段的含义不会变化。
签发流水线该用什么语言？
用您运维团队已经在用的那种语言。签发路径是一个与您的 PLM 和我们对接的定时作业，对性能并不敏感，而且将由维护您其他集成的同一批人来维护。选一门团队里没人熟悉的语言，是这里最常见也最容易避免的错误。
客户端库是开源的吗？
客户端库由已发布的 schema 生成，生成的源码可读、也可直接纳入贵方代码库。若您为满足内部政策而需要 fork，通信协议中没有任何一处依赖我们的客户端 —— 每一个负载都遵循您本可自行实现的 GS1 或 W3C 标准。