数字产品护照 API：开发者文档

概述

客户 API 是基于 JSON 的 REST 接口。它操作的是您组织的数据，也就是您在网页界面中看到的同一批产品和护照。典型用途包括对接 ERP 或 PLM 系统、每晚同步主数据，或用脚本获取用于印刷的二维码。

基础 URL 为 https://dpp.com2u.selfhost.eu/api/v1/integration。除二维码和 PDF 下载外，所有响应均为 JSON。

下载规范

所有端点、字段、示例和错误响应的机器可读参考是一份 OpenAPI 3.1 规范，安全方案为 ApiKeyAuth：

• 下载 openapi.json
• 下载 openapi.yaml

API 本身也在 GET /api/v1/integration/openapi.json 提供同一文件，无需 Key。您可以将其导入 Swagger UI、Postman 或任意代码生成器。文件中的说明文字为德语。

快速入门

1. 注册或登录。API 属于付费套餐，请参见价格。
2. 在平台中打开“组织”区域并生成 API Key。请立即复制，因为它只显示一次。
3. 测试连接：

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

响应会列出您的组织、Key 的权限范围（Scope）、您的套餐以及 API 调用的使用量。

认证

每次调用时在请求头 X-API-Key 中发送 Key。使用 Authorization: Bearer dpp_key_… 效果相同。组织始终由 Key 确定，作为参数传入的组织 ID 不会被采用。API 不接受网页界面的会话令牌。

Key 属于生成它的人员。所有操作都以该人员的所有者或管理员权限执行。如果该人员失去此角色，API 将返回 403，直到生成新的 Key。重新生成会立即撤销原有 Key。平台只保存 Key 的 SHA-256 哈希值。

端点

所有路径都位于 /api/v1/integration 之下。每个端点都需要一个权限范围，新 Key 拥有全部四个。

创建产品

name 为必填项。如果不提供 schema_key，将使用您组织的默认数据模板（Schema）；可用的键可通过 GET /schemas 获取。数据字段可以直接一并传入。field_status 用于设置值的状态，只有 approved 的值才会进入护照。

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Battery module X1","category":"Industrial batteries",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

状态码为 201 的响应包含产品的 id。它同时也是写入二维码的唯一产品标识符。与网页界面一样，您套餐的产品额度同样适用。

发布护照，下载二维码和 PDF

护照会将已批准的数据字段固定为一个新版本。如果缺少必填字段，API 返回 422，并在 missing_fields 中列出这些字段。

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

如需矢量格式的二维码，请使用 format=svg。PDF 仅在发布后提供，发布前 API 返回 404。二维码指向公开的护照页面，详情请参见从 Excel 创建数字产品护照。

错误代码

对于 401 和 403，detail 包含一个带有 code 和 message 的对象，例如 insufficient_scope 或 api_not_in_plan。对于 402，detail 会列出资源、上限和目前的使用量。

限制

通过 API 您可以设置产品层级的数据字段。批次或单件商品的字段请在网页界面中维护。API 没有频率限制，但每个套餐有调用额度；每次经过认证的调用都会计数。获取规范不计数。当前套餐和额度请参见价格页面。如需不通过 API 批量导入，可使用数据模板。