poai_ 服务器到服务器 API 密钥
- 创建者账户的权限（管理员：整个账户）
- 切勿在浏览器代码中交付
- 无需Origin标头
- 因MCP被锁定
- 可限制为 IP 地址
身份验证与密钥
一个Bearer令牌。 每个端点。
PaperOffice-API的每个产品端点均要求提供Authorization: Bearer头部。无需OAuth流程，无需刷新令牌。
两种令牌类型，明确的权限，已记录的速率限制。
一个头部字段 无 OAuth 流程 随时可撤销
- 自有欧盟基础设施 您的数据保留在欧洲。
- ISO/IEC 27001 已认证 安全已获认证。
- 24+年经验 经证实。稳定。面向未来。
curl -X POST "https://api.paperoffice.ai/latest/job/add/workflow" \ -H "Authorization: Bearer po_ut_YOUR_API_KEY" \ -F "file_1=@invoice.pdf" \ -F "idp_collection=invoice" \ -F "model=basic-pro-max"import requestsresponse = requests.post( "https://api.paperoffice.ai/latest/job/add/workflow", headers={"Authorization": "Bearer po_ut_YOUR_API_KEY"}, files={"file_1": open("invoice.pdf", "rb")}, data={"idp_collection": "invoice", "model": "basic-pro-max"},)print(response.json())const form = new FormData();form.append("file_1", new Blob([await readFile("invoice.pdf")]), "invoice.pdf");form.append("idp_collection", "invoice");form.append("model", "basic-pro-max");const response = await fetch("https://api.paperoffice.ai/latest/job/add/workflow", { method: "POST", headers: { Authorization: "Bearer po_ut_YOUR_API_KEY" }, body: form,});console.log(await response.json());首次调用
设置标头，选择管道，提交
在 /latest/job/add/ 之后的路径为操作名称：通常采用 handler___command 格式（例如 paperoffice_aiocr___generate），而对于结构化智能文档处理（IDP），则使用专用的 workflow 管道。
- 一个标头
Authorization: Bearer po_ut_… — 产品端点不需要更多。poai_ 和 po_ut_ 不发送 Origin 标头。
- 路径中的管道
handler___command 使用三个下划线；workflow 是带有自己 slug 的例外情况。点号表示法将返回 API，HTTP 400 JOB_CONFIG_INVALID。
- 结果或 job_id
client_wait 默认为 true：API 保持连接并内联返回结果。如果时间窗口不足，则返回 HTTP 202，附带 job_id 和用于 GET /latest/job/get/{job_id} 的 poll_url。
对于 idp_collection=invoice，推荐使用的模型为 basic-pro-max。实际使用的模型将返回在响应字段 model 中，且可能与请求的模型不同。
权限
User Token 的权限范围
User Token 仅拥有其在指定领域内的用户权限。在创建时无法分配特定领域的权限；如需限制权限范围，请使用具有用户组权限的组令牌 (po_gt_)。
- 文档
documents上传、下载、处理
- Workspaces
workspaces管理文件夹和结构
- AI 作业
ai_jobsOCR、IDP、提取
- 计费
billing读取用量和账户余额
- 用户
users管理团队成员
- Webhooks
webhooks接收事件
- 知识库
knowledge_base知识库和常见问题解答
- 代理
agents配置IDP代理
- 工作流
workflows创建自动化
- 合规
compliance审计、GDPR、归档
速率限制
API 重视什么
计费按每个令牌计算；无 Bearer 时按每个 IP 地址计算。以下数值为各套餐中适用的文档化最低值。
- 5
- 每秒请求数
- 30
- 每分钟请求数
- 100
- 每小时请求数
- 500
- 每天请求数
- 剩余配额显示在响应头中
每个响应中的 RateLimit-* 和 X-RateLimit-* 标头指示当前时间窗口内剩余的可用配额。
- 超限处理：HTTP 429
API 将返回 RATE_LIMIT_EXCEEDED。请根据 Retry-After 标头中的时间间隔重试请求。
- 更高套餐提升配额上限
付费费率高于这些最低值。各费率的覆盖范围请参阅价格页面。
安全性
密钥的安全保障机制
六项在运行中生效的机制——每项均具有可验证的状态码或应用内的位置。
- 轮换与撤销
密钥在应用中通过“账户 → API”创建、列出、轮换和撤销。被撤销的令牌将返回 HTTP 401 TOKEN_NOT_FOUND。
- 过期与有效性
过期的Token返回HTTP 401 BEARERTOKEN_EXPIRED，错误的返回HTTP 401 INVALID_TOKEN。Publishable Keys自创建之日起有效期为180天。
- 每个令牌的限额
Free套餐中每个令牌适用速率限制。在付费套餐中，按账户计算；只要存在Credits，就不会应用速率限制。
- 浏览器中的来源绑定
可发布密钥在每次请求时都要求 Allowlist 中的 Origin；否则 API 返回 403 ORIGIN_HEADER_REQUIRED 或 DOMAIN_NOT_ALLOWED。
- 追踪使用情况
每次计费的响应都包含一个 _billing 块；通过评估每次调用可获取 GET /latest/billing/usage-detail。
- 硬性限制
浏览器密钥禁止使用账户登录、密钥管理、OAuth、合作伙伴管理员、支付变更和密码破解。允许产品APIs（包括账单读取和Webhooks）。Workspace的删除、清空回收站和法律保留释放仅限在App中进行（403 UI_ONLY_ENDPOINT）。
下一站
后续步骤
开发者漏斗中推荐的下一步以及两个合适的分支。
