跳到主要内容
Battery Compliance
免费开始
菜单

开发者

连接您的 ERP 或生产系统：通过遵循 EN 18222 的 DPP API 创建并发布电池护照、读取和更新护照，并通过 Webhook 接收事件。每个方案（包括 Free）均含 API 访问。

两套 API

  • 护照管理 API

    /openapi.json

    面向拥有护照的公司：列出型号和条目（按游标，带 updatedSince 用于同步）、创建条目、区间和型号副本、更新条目数据、发布（单个条目或后台批量）并获取 QR 码。使用 API 密钥认证。

    参考：护照管理 API

  • DPP API（EN 18222）

    /openapi-dpp.json

    遵循 EN 18222 的生命周期与细粒度 API：按您的访问级别读取护照、按产品 ID 搜索护照 ID，并使用 OAuth 2.0 访问令牌记录事件（维修、健康状态、状态）。公开数据无需令牌即可读取。

    参考：DPP API（EN 18222）

读取护照

每个护照地址在您请求 JSON 时都会以 JSON 响应——公开数据无需密钥。响应头携带版本、其 SHA-256 和 Ed25519 签名，因此您可以对照我们的公钥核验所读取的内容。

curl -i -H "Accept: application/json" \https://batterycompliance.eu/id/BG123456789/EBIKE-48V/SN0001 HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8X-Passport-Version: 3X-Passport-Access-Level: publicX-Passport-SHA256: bd4c49c7b04ac463…81146b938X-Passport-Signature: Tw0bRkvf+s3IS1MQ…MPZ7Dg==X-Passport-Key-Id: batterycompliance-2026-09-25Link: </schema/battery-passport/2.0.0>; rel="describedby" { "dppHeader": { "dppStatus": { "dppStatusValue": "active" }, … },  "identifiersAndProductData": { "batterySerialNumber": "SN0001", … }, … }
较长的值已缩略。使用访问令牌时，同一地址返回您访问级别的字段，X-Passport-Access-Level 会标明该级别。

API 如何运作

认证

API 密钥由公司所有者在“公司 → API 密钥”中创建，仅显示一次。以 Authorization: Bearer bcp_live_… 发送。作用域：items:read、items:write（同时可读）、items:publish、qr:read。

OAuth 2.0 客户端（客户端凭据）由公司所有者为其合作伙伴创建，或由平台为主管机构和获批的第三方创建。通过 POST /oauth/token（grant_type=client_credentials）获取令牌；有效期 15 分钟。作用域：dpp:read、dpp:search、dpp:write。

限额与错误

每个 API 密钥每分钟 60 次请求（请求头 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset），每个 OAuth 客户端每分钟 120 次，无令牌时按地址计算。超出限额：HTTP 429 并附带 Retry-After。

护照管理 API 以包含 code、message 和 details 的 error 对象返回错误；DPP API 返回 statusCode、payload 和 result，并采用 EN 18222 的状态码。

DPP API 的更新接受 Idempotency-Key 请求头：24 小时内使用相同密钥发出相同请求，会返回第一次的响应，且不会创建第二个版本。

公开护照

每份护照都有一个永久地址（GS1 Digital Link /01/{GTIN}/21/{serial} 或 /id/{operator}/{model}/{serial}）。使用 Accept: application/json 或 ?format=json 时，返回适用于您访问级别的最新版本的 JSON；?version=N 返回指定版本；/versions 返回版本列表。

每个版本都经签名：X-Passport-SHA256 携带完整版本的 RFC 8785 规范化 JSON 的 SHA-256，X-Passport-Signature 携带对该十六进制字符串的 Ed25519 签名，X-Passport-Key-Id 携带签名所用的密钥。公钥和模式列在“机器可读说明”下。

Webhook

无需轮询，在“公司 → Webhook”中添加一个端点。事件——passport.published、publish_job.finished、item.lifecycle_recorded、access_request.created、passport.transferred、label_template.issued、dossier.ready、import_batch.assigned、import_batch.confirmed、import_batch.rejected——以 JSON 形式 POST，请求头为 X-Webhook-Id、X-Webhook-Timestamp 和 X-Webhook-Signature = v1= + 使用您的密钥对 timestamp.body 计算的十六进制 HMAC-SHA256。请在 10 秒内返回 2xx；投递失败会重试 24 小时。

机器可读说明

获取 API 密钥

注册您的公司，然后在“公司 → API 密钥”中创建密钥。密钥仅显示一次，并且只以哈希形式存储。

免费开始联系我们