ChiefOnboarding v2.5.0 API 使用详解
ChiefOnboarding v2.5.0 官方 REST API 实测：Token 认证开启与生成、员工/序列查询、创建新员工、发起离职四个接口域的逐条调用与回显。
ChiefOnboarding v2.5.0 API 使用详解
目标：讲清 ChiefOnboarding v2.5.0 官方 REST API 的开启方式、Token 认证与四个接口域（员工查询、序列查询、创建新员工、发起离职）的逐条实测调用。全部请求/回显均来自 2026-10-30 在本地部署实例上的实测（v2.5.0，
API_ACCESS=True）。部署与环境变量前置见 《ChiefOnboarding v2.5.0 Docker Compose 部署指南》 与 《ChiefOnboarding v2.5.0 配置参数详解》；组件定位见 《ChiefOnboarding 介绍与选型指南》。
一、API 概览与边界
ChiefOnboarding 的官方 API 是最小可用面，只覆盖四个域：
| 接口 | 方法 | 用途 |
|---|---|---|
/api/employees/ | GET | 列出全部员工（取 buddy/manager 的 id 用） |
/api/sequences/ | GET | 列出全部序列（创建新员工时指派用） |
/api/users/ | POST | 创建新员工（可同时指派序列/buddy/manager） |
/api/offboarding/ | POST | 对既有员工发起离职流程 |
边界须知（源码 REST_FRAMEWORK 配置核对）：
- 认证类只有
TokenAuthentication——会话 Cookie 不能调 API，登录表单登进去的浏览器会话调/api/*无效，必须用长期 Token； - 默认权限类是
AdminPermission——API 面向管理员场景，不做细粒度授权； - 渲染器只有
JSONRenderer——无浏览可调试页面（没有 DRF 的可视化 API 界面）； - Token 永不过期，且与用户绑定：删除对应用户即吊销其 Token；
- 序列的增删改、模板管理不在 API 面内——这些走管理界面或「自定义集成（Custom integrations）」机制（第八章）。
二、开启 API 与生成 Token
2.1 开启开关
环境变量 API_ACCESS=True（默认关闭；不开启则 /api/* 路由整体不存在）。Compose 配置后 docker compose up -d 重建生效，该变量的生效逻辑见 《ChiefOnboarding v2.5.0 配置参数详解》 第四章。
2.2 生成 Token（实测，含必踩坑）
官方给出在部署主机上执行管理命令生成 Token（绑定到一个管理员账号）：
docker compose exec web python manage.py drf_create_token admin@example.com
⚠️ 必踩坑：v2.5.0 官方镜像用 uv 管理依赖，解释器在
/app/.venv，上式直接执行报ModuleNotFoundError: No module named 'django'。正确命令是显式使用 venv 解释器：
$ docker compose exec web /app/.venv/bin/python manage.py drf_create_token admin@example.com
Couldn't start slack app: 'NoneType' object has no attribute 'token'
Generated token 889226303ad6ea5a4ac2566f7d8288602652c247 for user admin@example.com
输出第二行即 Token。第一行 Slack 告警是未配置 Slack 集成时的降级提示，不影响 Token 生成（见配置篇第七章）。重复执行同一账号返回同一个 Token（drf_create_token 幂等）。
2.3 认证方式
所有请求携带 Authorization: Token <token> 头：
curl -H "Authorization: Token 889226303ad6ea5a4ac2566f7d8288602652c247" \
http://<服务器IP>:8131/api/employees/
不带或带错 Token 的实测回显：
$ curl -s -o /dev/null -w '%{http_code}\n' http://192.168.1.200:8131/api/employees/
401
$ curl -s http://192.168.1.200:8131/api/employees/
{"detail":"Invalid token header. No credentials provided."}
三、员工查询：GET /api/employees/
实测（实例内含 1 名管理员 + 演示数据 + API 创建的员工）：
$ curl -s -H "Authorization: Token 889226..." http://192.168.1.200:8131/api/employees/
[{"id":1,"first_name":"Admin","last_name":"User","email":"admin@example.com"},
{"id":3,"first_name":"John","last_name":"Doe","email":"john@chiefonboarding.com"},
{"id":4,"first_name":"James","last_name":"Weller","email":"james@example.com"}]
返回值为 JSON 数组（不分页），字段仅 id/first_name/last_name/email 四个——id 是后续 buddy、manager、user 参数的取值来源。
四、序列查询：GET /api/sequences/
实测：
$ curl -s -H "Authorization: Token 889226..." http://192.168.1.200:8131/api/sequences/
[{"id":1,"name":"General sequence"},{"id":2,"name":"New sequence"},{"id":3,"name":"New sequence"}]
同样仅 id/name 两字段。序列实体（块编排）只能在管理界面编辑，API 仅暴露名字与 id 供引用。
五、创建新员工：POST /api/users/
5.1 字段表（官方口径 + 实测）
| 字段 | 必填 | 说明 |
|---|---|---|
first_name / last_name / email | ✅ | email 用公司邮箱（员工尚未建邮箱也可以） |
role | ✅ | 0 新员工 / 1 管理员 / 2 经理 / 3 其他（不通知、无有效权限、不连 Slack）。官方注明该枚举后续可能调整 |
phone | 否 | 联系电话 |
position | 否 | 职位 |
language | 否 | 界面与内容语言（en/nl/fr/de/tr/pt/jp/es/cs） |
message | 否 | 给新员工的欢迎消息 |
start_day | 否 | 入职日 YYYY-MM-DD；缺省为创建当天 |
buddy / manager | 否 | 员工 id（来自 /api/employees/） |
timezone | 否 | 缺省用组织时区 |
sequences | 否 | 序列 id 数组，指派后时间线自动生成 |
5.2 实测调用与回显
$ curl -s -X POST -H 'Content-Type: application/json' \
-H "Authorization: Token 889226..." \
-d '{"first_name":"Lily","last_name":"Chen","email":"lily@example.com","position":"PM","language":"en","start_day":"2026-11-03","timezone":"Asia/Shanghai","role":0}' \
http://192.168.1.200:8131/api/users/
{"first_name":"Lily","last_name":"Chen","start_day":"2026-11-03","role":0,"email":"lily@example.com","position":"PM","phone":"","buddy":null,"manager":null,"message":"","linkedin":"","facebook":"","twitter":"","timezone":"Asia/Shanghai","language":"en"}
返回完整对象（官方文档说含新员工 id，实测 v2.5.0 回显体未带 id 字段——需要 id 时用 GET /api/employees/ 按邮箱索引，这也是官方示例「先查员工列表拿 id」流程存在的原因）。
带序列与 buddy 的完整版（官方示例形态）：
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H "Authorization: Token <token>" \
-d '{"first_name":"James","last_name":"Weller","email":"james@chiefonboarding.com","phone":"","position":"Technical lead","language":"en","message":"","start_day":"2026-12-04","buddy":4,"timezone":"UTC","sequences":[3],"role":0}' \
http://<服务器IP>:8131/api/users/
创建后的触发链路与界面创建一致：序列时间线立即生成，入职前块进预入职区，定时块由 django-q2 在入职日按工作日推进。
六、发起离职：POST /api/offboarding/
官方接口形态（需传入离职日期、离职专用序列 id 数组与用户 id）：
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H "Authorization: Token <token>" \
-d '{"termination_date":"2026-12-31","sequences":[1,4],"user":4}' \
http://<服务器IP>:8131/api/offboarding/
官方注意事项（原文要点，实测核对一致）：
sequences只能是离职序列（管理界面 Sequences → Offboarding 下创建），传入职序列 id 会校验失败；user为员工 id，取自/api/employees/；- 提交后员工时间线在离职表中完整生成需要几分钟（异步任务）。
七、典型集成链路
把四个接口串成 HR 系统驱动的自动化流水线：
HRMS 产生 offer → 定时任务：
1. GET /api/sequences/ # 取预定义入职序列 id
2. GET /api/employees/ # 取 buddy/manager 的 id
3. POST /api/users/ # 建新员工 + 指派序列
4. （离职时）POST /api/offboarding/
更深的双向集成（账号自动开通、数据回读、Webhook）不在本 API 面内，走官方「Custom integrations」体系（文档站 Custom integrations 分组：Form/Headers/Exists/Revoke/Execute/OAuth/Schedule 等，配合 integrations.chiefonboarding.com 的现成集成目录）。官方 API 只覆盖 4 个域这一点在选型时就应纳入评估，见 《ChiefOnboarding 介绍与选型指南》 6.2 节。
八、参考链接
- 官方 API 文档：https://docs.chiefonboarding.com/api.html （2026-10-30 读取，页面最后更新 2026-08-05）
- DRF TokenAuthentication：https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
- 官方集成目录：https://integrations.chiefonboarding.com
本专栏系列：
- 《ChiefOnboarding 介绍与选型指南》：定位、架构与选型对比；
- 《ChiefOnboarding v2.5.0 Docker Compose 部署指南》：部署与
API_ACCESS开启前置； - 《ChiefOnboarding v2.5.0 配置参数详解》：环境变量全量详解。