使用 HR 开放 API 连接其他系统

HR 开放 API 允许其他系统使用您创建的密钥读取人员、考勤、休假和最终工资数据，并发送打卡。HR webhook 则在事件发生时通知该系统。

开始之前

• 您必须是所有者。经理即使拥有全部人事权限也不能创建密钥。
• 已启用 HR。

创建密钥

1. 打开 HR → HR settings，在 Self-service and the team 中选择 HR open API。
2. 勾选 The open API is on，选择 Save。页面会显示 Base address。
3. 在 Make a key 下输入 What for（例如“工资服务机构”）。
4. 在 May 下仅勾选系统需要的权限：read people、read attendance、send punches、read leave、read final payroll、manage webhooks。
5. 选择 Make the key。
6. 立即复制密钥并交给其他系统。密钥仅显示一次；Kluvan 只保存其哈希值。

添加 webhook

1. 在 Add a webhook 下输入系统的 URL（必须以 https 开头）。
2. 勾选事件：employee.created、employee.left、punch.recorded、leave.approved 和 payroll.paid。默认全部勾选。
3. 选择 Add it 并复制仅显示一次的签名密钥。
4. 查看 Deliveries，了解发送内容、状态和尝试次数。

须知

• 独立密钥。 HR 密钥使用独立体系，与其他 Kluvan API 密钥分开，只能访问您组织的人事数据。
• 密钥永远不能读取银行资料、证件或生物识别数据。read final payroll 仅返回已支付的工资批次，不返回草稿，也不返回 IBAN 或账号。
• 选择 Revoke 可立即停用密钥。列表显示每个密钥的上次使用时间和调用次数。
• 每个密钥每秒可调用 10 次，短时突发最多 60 次。请求的时间范围最多为 92 天。
• API 发送的打卡作为更正添加，并以密钥名称作为作者。每次打卡只发送一次：重复发送会在工时表上出现两条记录，需要经理删除其中一条。
• webhook 使用签名密钥签名（X-Hr-Signature 请求头中的 HMAC-SHA256）。发送失败后会重试约一天；连续失败 20 次的 webhook 会被关闭，直到您重新启用。
• 尚未针对真实端点试用：webhook 发送仅在我们自己的测试环境中测试过。正式依赖前，请先与自己的系统测试。
• 创建及撤销密钥，以及发送的每次打卡，都会写入活动日志。
• 页面提供面向开发者的技术参考链接：Read how to call it.