使用 API 密钥连接自己的软件

公共 API 让您或开发者的软件读写 Kluvan 记录：产品、客户、库存、报表、账务单据、人事人员、CRM、订阅和已拥有的应用。您控制每把密钥：能做什么、有效多久、适用哪个分支。

开始之前

• 只有所有者可以创建和撤销密钥。
• 密钥不能访问组织未拥有的应用，套餐、应用和分支的所有规则仍然适用。

步骤

1. 打开 Settings → Developer access（设置 → 开发者访问）。
2. 在 New key（新密钥）下输入容易识别的 Name（名称），例如“仓库扫描器”。
3. 设置 Valid for days (1–365)（有效天数 1–365），默认为 90。
4. 在 Branch（分支）保留 All branches（所有分支），或选择一个分支。
5. 在 Can see（可查看）勾选密钥需要的每个范围。每项标明 Read（读）或 Write（写），例如 Products · Read（产品 · 读）。
6. 勾选授权所选访问的声明。
7. 点击 Make the key（创建密钥）。
8. 立即复制密钥，它仅显示这一次。
9. 将密钥提供给软件，由软件通过 Authorization: Bearer 请求头发送。

调用 API

• 地址为 https://api.kluvan.com/v1/public-api。Developer guide（开发者指南，/developers）提供示例及每项操作所需范围。OpenAPI 3.1 可下载含请求字段的完整接口规范。
• 每次写入需要 Idempotency-Key：每项更改使用新的 UUID。如果响应丢失，可在 7 天内用相同密钥重发相同请求，不会重复执行。同一密钥配不同请求会被拒绝。
• 修改现有记录还需发送当前版本（v），防止旧副本覆盖新记录。
• 金额使用货币最小单位（150.00 写作 15000）。
• 应用记录列表每页最多返回 50 条及 next 值；将其作为 after 传入以获取下一页。
• 每把密钥每分钟最多 120 次请求。超过时返回 429 和 Retry-After。每个错误都包含代码，参见错误指南。

注意事项

• 写入范围会修改真实记录，可执行影响库存和会计的应用操作。只授予必要范围。
• 分支密钥仅读取分支记录。商品目录、客户、CRM、人事和订阅操作需要所有分支的密钥。
• Kluvan 仅保存密钥指纹（哈希）。密钥丢失时，撤销并创建新密钥。
• Revoke（撤销）立即停用密钥；到期日也会自动停用。最多可持有 20 把密钥。
• API activity（API 活动）列出每次调用的时间、操作、密钥和状态。不记录请求体和密钥内容。
• API 不提供账单管理、登录、收款或 webhook；没有主动发送的通知，软件需读取所需列表。
• 已登录的浏览器会话不能调用此 API；助手应用密钥独立管理，参见连接助手应用。