跳到主要内容

资源

提案

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

对已发布的护照提出更改建议。

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

路径参数

organization字符串必填

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

id字符串必填

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

请求体

fields对象必填

要修改的字段，其形状与护照更新相同。发送数值时请连同单位一起发送。null 表示删除该值。

错误

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

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/proposals" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "recycled_content_percentage": 42
  }
}'
响应 · 201
{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "pending",
  "moved": [],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": null,
  "livemode": true
}

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

获取一项提案。

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

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
响应 · 200
{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "out_of_date",
  "moved": [
    "recycled_content_percentage"
  ],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": null,
  "livemode": true
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63

撤回一项等待中的提案。

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

路径参数

organization字符串必填

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

id字符串必填

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

错误

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

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63/withdraw" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
响应 · 200
{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "withdrawn",
  "moved": [],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": "2026-09-26T11:00:00.000Z",
  "livemode": true
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63/withdraw