REST API v1

REST API 文档

自动化您的电池护照工作流程。通过 REST API 创建、更新、发布和导出产品。护照查询端点与 EN 18222:2026 的方法和 REST 规范对齐；包括相关标准在内的完整符合性评估仍在进行中。

身份验证

需要 Scale 方案。请在您的组织设置中生成密钥。

Authorization: Bearer dpp_live_...

Base URL

每个组织每分钟 120 个请求。

https://app.dpphero.com/api/v1

快速示例

curl -X POST https://app.dpphero.com/api/v1/products \
  -H "Authorization: Bearer dpp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LFP Module 48V",
    "serial_number": "BAT-2025-001",
    "battery_category": "industrial",
    "manufacturing_date": "2025-06-15",
    "battery_mass": 45.5
  }'

可用端点

所有端点需要 Bearer token（API 密钥）。在 Scale 方案中可用。

产品

GET/products
POST/products
GET/products/{id}
PATCH/products/{id}
DELETE/products/{id}
POST/products/{id}/image
DELETE/products/{id}/image
POST/products/{id}/files

电池状态

通过 API 更新动态 BMS 数据，如充电状态、循环次数和容量衰减。

GET/products/{id}/condition
PATCH/products/{id}/condition

批量导入

POST/products/bulk

导出

GET/products/{id}/export/json
GET/products/{id}/export/gefeg-json
GET/products/{id}/export/pdf
POST/products/{id}/preprint-qr
GET/products/{id}/export/qr

组织

GET/organization
GET/facilities
GET/audit-log

列表、筛选与分页

GET /products 按页返回。page 从 1 开始，per_page 取值 1 到 100（默认 25）。您可以按 status 和 battery_category 筛选，使用 search 搜索，并按 created_at、updated_at 或 name 升序或降序排序。响应中包含 total 和 total_pages。

GET /products?page=1&per_page=25&sort=created_at&order=desc

机器可读的规范

完整接口以 OpenAPI 文档形式提供，无需登录即可获取。您可以用它生成客户端代码，或将集合导入您使用的工具。

openapi.json

GS1 数字链接

护照同样可以通过 GS1 标识来定位：GTIN 与序列号共同指向唯一一块电池，这正是 GS1 数字链接的设计。GTIN 在其中如何书写，见相关端点的说明；具体是哪些端点，请见登录后的完整文档。

错误与状态码

每个错误都以结构一致的 JSON 对象返回。出现 429 时，Retry-After 头部会给出以秒为单位的等待时间。

400validation_error输入不完整或有误；details 指出具体字段
401unauthorizedAPI 密钥缺失或无效
403forbidden该密钥无权访问此资源
403plan_required该功能属于其他套餐
404not_found该资源在您的组织中不存在
409conflict值已被占用，例如标识码重复
429rate_limit_exceeded请求过多；请遵循 Retry-After
500internal_error我方发生错误；请将 correlation_id 提供给支持团队
{
  "error": {
    "code": "validation_error",
    "message": "...",
    "details": { "name": ["Required"] },
    "correlation_id": "..."
  }
}

correlation_id 同时出现在 X-Correlation-Id 头部中。联系支持时请提供该值，我们就能在日志中找到同一条记录。

完整文档

包含字段定义、示例负载、错误码、自动填充规则和完整产品 Schema 的完整 API 参考可在您的控制面板中获取。

查看方案登录以访问文档

在发出第一个请求之前应当了解什么

身份验证

每个请求都在 Authorization 头之中携带一个 Bearer 令牌。REST 接口属于 Scale 套餐；在较小的套餐之中，您通过界面或 CSV 导入来工作。

分页读取

列表端点不会一次返回全部内容。您可通过 page（自 1 起，默认 1）和 per_page（1 至 100，默认 25）控制。响应中带有 page、per_page、total 和 total_pages。因此您无需猜测何时结束。排序通过 sort（created_at、updated_at 或 name）和 order（asc 或 desc）。筛选通过 status、battery_category 和 search。

目前还没有 Webhook

目前没有事件通知。变更需要通过轮询获取。建议按 updated_at 排序，并限定为自上次运行以来的时间段。我们把这一点写出来，而不是回避。这样您就不会把对接建立在并不存在的承诺上。

导出遵循 Battery Passport 数据模型 2.0 版。哪个字段放什么，由应用的字段登记表决定，而不是由调用决定。上方的端点说明与账户中的文档标签出自同一来源。因此它们不会产生分歧。