资源

序列化单元

序列化单元 的每一个端点，附带它强制要求的作用域、它接受的请求体、一份可读的响应，以及它可能返回的拒绝。

列出序列化单元。

get/organizations/{organization}/passports/{id}/units
作用域
units:read
Idempotency-Key
不接受
返回
200

路径参数

organizationstring必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

idstring必填

资源的标识符。请把它当作不可解析的字符串处理。

查询参数

limitstring可选

返回多少条记录。服务端返回的条数可能更少。

cursorstring可选

上一页返回的 next_cursor。游标会编码签发时所用的筛选条件，改用其他筛选条件发送会被 cursor_invalid 拒绝。

statusstring可选

仅返回处于该状态的单元。

unit_serialstring可选

返回携带该序列号的那一个单元。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
响应 · 200
{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25

创建序列化单元。

post/organizations/{organization}/passports/{id}/units
作用域
units:write
Idempotency-Key
接受
返回
201

路径参数

organizationstring必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

idstring必填

资源的标识符。请把它当作不可解析的字符串处理。

请求体

unitsarray of objects必填

1 到 1000 个单元。上级护照必须属于 battery 类别——序列化单元是电池领域的概念，其他类别的上级护照会被 invalid_request 拒绝。同一请求内重复出现的序列号会逐行拒绝，而不是自动去重，这样批量导入程序就绝不会以为自己创建了一条其实并不存在的记录。

unit_serialstring必填

该实体物品所携带的序列号，最多 70 个字符。在同一护照内唯一。

statusstring可选

生命周期状态，取自附件 XIII 的词汇表：original、repurposed、re-used、remanufactured、waste。以自由文本形式存储，最多 70 个字符——列表之外的取值会被接受，但之后没有任何环节能识别它。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "units": [
    {
      "unit_serial": "BAT-2026-000117",
      "status": "original"
    },
    {
      "unit_serial": "BAT-2026-000118"
    }
  ]
}'
响应 · 201
{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z"
    },
    {
      "object": "unit",
      "id": "5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000118",
      "status": null,
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units

序列化单元 — PassportCraft API 参考 | PassportCraft