资源

文档

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

列出与护照关联的文档。

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

路径参数

organizationstring必填

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

idstring必填

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

查询参数

limitstring可选

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

cursorstring可选

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

typestring可选

仅返回该类型的文档。

access_tierstring可选

仅返回发布给该受众层级的文档。

错误

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

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
响应 · 200
{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "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",
      "type": "conformity_declaration",
      "access_tier": "public",
      "file_name": "doc-2026-kestrel.pdf",
      "display_name": "EU Declaration of Conformity",
      "mime_type": "application/pdf",
      "file_size": 184320,
      "upload_state": "ready",
      "uploaded_at": "2026-07-29T15:44:02.008Z",
      "livemode": true,
      "created_at": "2026-07-29T15:43:51.660Z",
      "linked_at": "2026-07-29T15:43:51.660Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

创建文档并获取带签名的上传 URL。

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

路径参数

organizationstring必填

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

idstring必填

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

请求体

此端点接受两种请求体之一。请只发送其中一种形式——同时包含两种字段的请求体会被拒绝。

关联文档库中已有的文档

document_idstring必填

关联组织文档库中已有的文档，而不是上传新文件。不能与任何上传字段同时使用。关联一份尚未附加的文档会返回 201；重复关联已附加的文档会返回 200。两者都不会带有 upload 对象。

上传新文件

typestring必填

上传时必填；设置了 document_id 时不得出现。取值为 certification、image、document、conformity_declaration 之一。

access_tierstring必填

上传时必填；设置了 document_id 时不得出现。取值为 public、restricted、authority 之一。它决定护照上线后谁可以读取该文件。

file_namestring必填

上传时必填；设置了 document_id 时不得出现。存储该文件时使用的文件名。

mime_typestring必填

上传时必填；设置了 document_id 时不得出现。取值为 application/pdf、image/png、image/jpeg、image/webp 之一。该值会原样传给存储服务，与实际文件不符会被拒绝。

file_sizeinteger可选

文件大小，单位为字节，最大 10485760。

display_namestring可选

读者看到的标签。默认取 file_name。

错误

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

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "display_name": "EU Declaration of Conformity"
}'
响应 · 201
{
  "object": "document",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "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",
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "display_name": "EU Declaration of Conformity",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "upload_state": "pending",
  "uploaded_at": null,
  "livemode": true,
  "created_at": "2026-08-02T09:40:12.331Z",
  "linked_at": "2026-08-02T09:40:12.331Z",
  "upload": {
    "url": "https://<project>.supabase.co/storage/v1/object/upload/sign/passport-assets/<organization>/library/<uuid>-doc-2026-kestrel.pdf?token=<jwt>",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-08-02T11:40:12.331Z",
    "max_bytes": 10485760
  }
}

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

文档 — PassportCraft API 参考 | PassportCraft