护照 — PassportCraft API 参考

列出护照。

get/organizations/{organization}/passports

作用域: passports:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

查询参数

limit字符串可选

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

cursor字符串可选

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

status字符串可选

仅返回处于该状态的护照。

category字符串可选

仅返回该类别下的护照。

updated_since字符串可选

一个 RFC 3339 时间戳。返回在该时刻或之后更新过的护照，集成方据此轮询变更，而不必重新读取整份目录。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports?status=published&limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "list",
  "data": [
    {
      "object": "passport",
      "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "category": "textile",
      "status": "published",
      "gtin": "02000000000053",
      "external_id": "SKU-4471-BLK",
      "version": 4,
      "livemode": true,
      "created_at": "2026-08-01T09:12:44.918Z",
      "updated_at": "2026-08-01T14:03:22.501Z",
      "data": {
        "product_name": "Merino Crew Neck",
        "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
        "manufacturer_name": "Atelier Kestrel SAS",
        "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
        "manufacturer_country": "FR",
        "material_composition": [
          {
            "fiber": "Merino wool",
            "percentage": 100
          }
        ],
        "substances_of_concern": [
          "None above threshold"
        ],
        "gtin": "02000000000053"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports?status=published&limit=25

创建护照。

post/organizations/{organization}/passports

作用域: passports:write
Idempotency-Key: 接受
返回: 201

路径参数

organization字符串必填

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

请求体

category字符串必填

来自 GET /categories 的类别 id。它决定了字段架构，创建之后无法更改。

external_id字符串可选

您自己为该产品指定的标识符，长度 1 到 255 个字符。在组织和模式内唯一，因此您无需保存我们的 id 也能完成对账；同一个 id 可以在测试模式和正式模式中各存在一次。

data对象可选

护照文档。键名取自该类别的字段架构，另外还包括每个可附文件字段的 document_id_key 配套键；其余键会被拒绝，而不是被悄悄存下。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "textile",
  "external_id": "SKU-4471-BLK",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR"
  }
}'

响应 · 201

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 1,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T09:12:44.918Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ]
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports

获取单个护照。

get/organizations/{organization}/passports/{id}

作用域: passports:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41

对护照应用 JSON Merge Patch。

patch/organizations/{organization}/passports/{id}

作用域: passports:write
Idempotency-Key: 接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

请求头

Expected-Version整数可选

读取护照时返回的 version，以整数形式给出。若护照在此期间已被改动，写入会被 precondition_failed 拒绝，这是让读取-修改-写入在并发编辑面前保持安全的唯一办法。请使用该请求头，而不是 If-Match。重试被拒绝的写入时请使用新的 Idempotency-Key：该拒绝已记录在原有的键上，否则会被再次返回。

If-Match字符串可选

除非其值恰好为 *，否则会以 invalid_request 被拒绝——携带 ETag 时同样如此。我们的 CDN 会将 If-Match 与响应进行比对并改写结果：这样一来条件写入本会生效，却仍以 412 的形式报告给您，而拒绝正是为了阻止这种情况。请改用 Expected-Version 发送版本号。仅要求护照仍然存在的 If-Match: * 会被接受。

请求体

data对象可选

对护照文档应用的 RFC 7386 JSON Merge Patch。省略某个键即保持原值不动；传入 null 则删除它。数组一律整体替换，绝不合并。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}'

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 2,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T10:44:12.700Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}

PATCH /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41

发布护照。

post/organizations/{organization}/passports/{id}/publish

作用域: passports:write
Idempotency-Key: 接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

请求体

variant_review_fingerprint字符串可选

当护照包含由助手填写的尺码与颜色时必填：即 GET …/variants/review 返回的指纹，须在人工审核这些行之后发送。缺少该指纹时，发布将以 variant_review_required 被拒绝；若审核后尺码与颜色发生变化，则以 variant_review_changed 被拒绝。请使用新的幂等键发送。64 个字符的十六进制字符串。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/publish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  },
  "warnings": [
    {
      "code": "environmental_claim_detected",
      "message": "This passport contains environmental claims (carbon neutral), found in its wording or in fields the brand marked as environmental information. From 27 September 2026, Directive (EU) 2024/825 requires the trader placing the product on the market to hold substantiation for such claims. Publishing succeeded; confirm the substantiation exists.",
      "doc_url": "https://passportcraft.com/docs/api/errors#environmental_claim_detected"
    }
  ]
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/publish

取消发布护照。

破坏性

post/organizations/{organization}/passports/{id}/unpublish

作用域: passports:write
Idempotency-Key: 接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/unpublish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 5,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:15:09.113Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/unpublish

将护照移入回收站。

破坏性

post/organizations/{organization}/passports/{id}/trash

作用域: passports:write
Idempotency-Key: 接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/trash" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "trashed",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 6,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:19:44.002Z",
  "published_at": null,
  "trashed_at": "2026-08-02T08:19:44.002Z",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/trash

从回收站恢复护照。

post/organizations/{organization}/passports/{id}/restore

作用域: passports:write
Idempotency-Key: 接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/restore" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

响应 · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 7,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:21:03.884Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/restore

按类别架构校验护照，但不保存。

post/organizations/{organization}/passports/{id}/validate

作用域: passports:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

请求体

data对象可选

校验前先合并进来的字段，您可以据此试验一次修改而不保存它。无论结果如何，都不会写入任何内容。

variant_review_fingerprint字符串可选

GET …/variants/review 返回的指纹。发送该指纹可询问携带它的发布是否会成功；缺少该指纹时，包含由助手填写的尺码与颜色的护照会将审核报告为错误。64 个字符的十六进制字符串；由于此端点给出的是预测，过期或格式错误的指纹会作为问题报告，而不是被拒绝。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validate" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "material_composition": null
  }
}'

响应 · 200

{
  "object": "validation",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validation",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "category": "textile",
  "schema_version": "1.0.0-draft",
  "dry_run": true,
  "valid": false,
  "publishable": false,
  "error_count": 2,
  "warning_count": 0,
  "checked_at": "2026-08-02T08:26:11.409Z",
  "issues": [
    {
      "object": "validation_issue",
      "field": "material_composition",
      "source": {
        "pointer": "/data/material_composition"
      },
      "rule": "required",
      "severity": "error",
      "message": "Material Composition is required",
      "message_key": "required",
      "message_params": {
        "field": "Material Composition"
      },
      "writable_via_api": true
    },
    {
      "object": "validation_issue",
      "field": "gtin",
      "source": {
        "pointer": "/data/gtin"
      },
      "rule": "required",
      "severity": "error",
      "message": "A GTIN is required before this passport can be published. A saved size or colour with its own barcode also satisfies this.",
      "writable_via_api": true
    }
  ]
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validate

获取公开 URL 和 GS1 Digital Link 地址。gs1_digital_links 包含所有变体及其 variant_id、size 和 colour。主 GTIN 的 URI 仅出现一次，并保留变体信息；带序列号的主 URI 单独保留。

get/organizations/{organization}/passports/{id}/links

作用域: passports:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "passport_links",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "status": "published",
  "livemode": true,
  "gtin": "02000000000053",
  "serial_number": null,
  "public_url": "https://passportcraft.com/passport/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "qr_target": "https://passportcraft.com/01/02000000000053",
  "gs1_digital_links": [
    {
      "uri": "https://passportcraft.com/01/02000000000053",
      "gtin14": "02000000000053",
      "serial": null,
      "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
      "unavailable_reason": null,
      "variant_id": null,
      "size": null,
      "colour": null
    }
  ],
  "gs1_digital_link": {
    "uri": "https://passportcraft.com/01/02000000000053",
    "gtin14": "02000000000053",
    "serial": null,
    "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
    "unavailable_reason": null
  },
  "resolves_publicly": true,
  "not_resolvable_reason": null,
  "preview_url": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links

列出电池读数。

get/organizations/{organization}/passports/{id}/units/{unitId}/readings

作用域: units:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

unitId字符串必填

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

查询参数

limit字符串可选

返回1至100条读数。

cursor字符串可选

上一页的next_cursor。请保持相同的字段筛选条件。

field字符串可选

仅返回此字段的读数。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "list",
  "data": [
    {
      "object": "unit_reading",
      "id": "a1100000-0000-4000-8000-000000000001",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "livemode": true,
      "field": "status",
      "value": "original",
      "observed_on": "2026-08-02",
      "source": "brand_statement",
      "note": null,
      "document_id": null,
      "recorded_by": "a1100000-0000-4000-8000-000000000002",
      "recorded_actor_type": "api_key",
      "recorded_via": "api",
      "recorded_at": "2026-08-02T09:31:18.446123Z",
      "legacy_import": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50

记录电池读数。

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

作用域: units:write
Idempotency-Key: 接受
返回: 201

路径参数

organization字符串必填

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

id字符串必填

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

unitId字符串必填

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

请求体

field字符串必填

类别架构中的电池专属字段。

value文本、数字或带单位的数字必填

符合字段定义的数值；带单位选择器的字段需提供数字和单位。

observed_on字符串必填

数值的测量或声明日期，格式为YYYY-MM-DD。

source字符串必填

measurement或brand_statement。

note字符串可选

关于方法或依据的可选备注，最多500个字符。

document_id字符串可选

支持此读数的可选组织文档库文档。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement"
}'

响应 · 201

{
  "object": "unit_reading",
  "id": "a1100000-0000-4000-8000-000000000001",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "livemode": true,
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement",
  "note": null,
  "document_id": null,
  "recorded_by": "a1100000-0000-4000-8000-000000000002",
  "recorded_actor_type": "api_key",
  "recorded_via": "api",
  "recorded_at": "2026-08-02T09:31:18.446123Z",
  "legacy_import": false
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings

解除文档与护照的关联；若无其他护照使用该文档，则将其从文档库中删除。

delete/organizations/{organization}/passports/{id}/documents/{documentId}

作用域: documents:write
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

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

id字符串必填

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

documentId字符串必填

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

请求头

If-Match字符串可选

除非其值恰好为 *，否则会以 invalid_request 被拒绝。该端点没有条件形式。DELETE 是我们唯一没有针对 CDN 测量过的方法；CDN 在某些路径上会将 If-Match 与响应比对，并把成功改写为 412——而已经完成的解除关联，绝不应以拒绝的形式报告给您。仅要求文档仍然存在的 If-Match: * 会被接受。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "document.deleted",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "livemode": true,
  "detached": true,
  "deleted_from_library": true,
  "remaining_links": 0,
  "document_limit": 50
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b