规格变体 — PassportCraft API 参考

列出尺码和颜色变体。

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

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

路径参数

organization字符串必填

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

id字符串必填

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

查询参数

limit字符串可选

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

cursor字符串可选

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

gtin字符串可选

仅返回此 GTIN 对应的变体。有效的 8、12、13 或 14 位 GTIN 会统一为 14 位。

错误

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

请求

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

响应 · 200

{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

创建尺码和颜色变体。

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

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

路径参数

organization字符串必填

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

id字符串必填

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

请求体

variants对象列表必填

为纺织品或通用产品护照发送 1–1000 个变体。多次请求累计每本护照最多 2000 个。整批数据全部写入或全部拒绝，返回顺序与请求一致。GTIN 和尺码/颜色组合必须唯一。允许使用本护照的主 GTIN；同一组织、同一模式下其他护照的主 GTIN 或变体 GTIN 均会被拒绝，包括回收站中的护照。成功请求使用同一 Idempotency-Key 重试时，会先返回已记录的结果，不再检查冲突和容量。预检查中可纠正的拒绝不会占用该键。连接器凭据只能向草稿添加变体，不能删除变体。

gtin字符串必填

包含校验位的有效 8、12、13 或 14 位 GTIN。保存和返回时均为 14 位。

size字符串可选

尺码，去除首尾空白字符后为 1–70 个 Unicode 字符。请提供尺码、颜色或两者。

colour字符串可选

颜色，去除首尾空白字符后为 1–70 个 Unicode 字符。尺码与颜色组合必须唯一，比较时不区分大小写。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    {
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy"
    }
  ]
}'

响应 · 201

{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

删除单个变体。连接器凭据不能删除变体。

破坏性

delete/organizations/{organization}/passports/{id}/variants/{variantId}

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

路径参数

organization字符串必填

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

id字符串必填

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

variantId字符串必填

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

错误

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

请求

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

响应 · 200

{
  "object": "variant",
  "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "deleted": true
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84

按 GTIN 移除变体。

破坏性

post/organizations/{organization}/passports/{id}/variants/remove

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

路径参数

organization字符串必填

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

id字符串必填

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

请求体

gtins字符串数组必填

发送 1–1000 个有效 GTIN，统一为 14 位。已存在的记录会被移除，未找到的记录列入 absent。成功请求使用同一键重试会返回原结果；不带键重试时，已移除的记录列入 absent。每次从已发布或已停用护照中实际移除变体的调用，计入一次破坏性操作限额。连接器凭据不能移除变体。移除操作会以数量受限的批次执行；若后续批次失败，error.details.removed 会列出已完成的移除。请不带 Idempotency-Key 重试以处理剩余记录；使用同一键会返回已记录的失败结果。

错误

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

请求

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/remove" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "gtins": [
    "03453120000011"
  ]
}'

响应 · 200

{
  "removed": [
    "03453120000011"
  ],
  "absent": []
}

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

读取发布前由人工审核的尺码与颜色及其指纹。

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

作用域: 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/variants/review" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

响应 · 200

{
  "object": "variant_review",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "fingerprint": "3b2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f",
  "agent_written_count": 1,
  "variants": [
    {
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "agent_written": {
        "keyId": "pcmcp_a1",
        "keyName": "Claude",
        "at": "2026-09-18T09:12:44.000Z",
        "sourceClass": "agent_asserted"
      }
    },
    {
      "id": "8d3f1c22-6b7e-4d1a-9e2f-5a6b7c8d9e0f",
      "gtin": "05012345678900",
      "size": "L",
      "colour": "Navy",
      "agent_written": null
    }
  ]
}

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