HR系统如何通过API对接实现与ERP、OA数据互通？

最近公司老板突然扔过来一个需求，要把公司那套用了好几年的HR系统，和新上的ERP、OA系统打通。这事儿听起来挺高大上，其实拆开了揉碎了看，就是让这几个原本“各扫门前雪”的系统，能互相“说说话”，传传数据。这事儿要是全靠人工导表、录入，那不仅能把人累死，还特别容易出错。所以，API就成了我们技术茶余饭后绕不开的话题。今天就结合我实际摸爬滚打的一些经验，聊聊这事儿到底怎么干。

一、先搞明白，咱们到底图个啥？

在埋头写代码之前，咱得先想清楚，折腾这么一通，到底是为了省哪些事儿。不然很容易陷入“为了技术而技术”的怪圈。

打通数据，核心就那几个目的：

• 省人，也省心：最典型的就是新员工入职。HR在HR系统里创建完档案，总得通知行政配电脑、IT开账号、财务算薪酬吧？如果没打通，HR就得一个个发邮件或者填单子，不仅慢，还容易漏。打通了，HR点一下“入职”，这些信息就自动跑到OA和ERP里了。
• 保证数据新鲜又准确：员工信息变动是常态。比如小王升职了，薪资调整了，或者部门调动了。如果系统不互通，HR改了HR系统，还得记得去ERP里改薪酬，去OA里改汇报线。只要漏一个，工资就可能发错，审批流程就可能走错人。API能确保数据改一处，处处同步。
• 随时随地都能办：领导在外面出差，想审批个请假单，或者员工想查查自己的工资条和年假余额。通过API，这些功能可以轻松集成到手机APP或者微信企业版里，不用非得开电脑登录特定系统。
• 让报表更靠谱：老板要看人效分析，要看薪酬成本，这些数据分散在HR、ERP里就是一堆数字。打通之后，数据整合起来，才能做出真正有价值的分析报表，给决策提供依据。

二、动手之前，得做点“家务事”

这就像装修房子，水电改造是硬仗，但 design（规划）和清场是前提。技术对接也是一样，不能上来就写。

1. 摸清家底：盘点你的API资源

你得先搞清楚，你手里的这些系统，到底有没有API接口。不是所有的“老系统”都支持API，有些可能得花钱找原厂升级，甚至是二次开发。

• HR系统：有没有提供标准API接口？是RESTful的还是SOAP的？支持哪些功能（创建员工、更新信息、查询假期...）？
• ERP系统：同上。特别是财务模块，接口权限通常很严格。
• OA系统：一般流程引擎比较开放，关键看它能否通过API触发流程、提交表单、获取审批意见。

如果系统是采购的云服务，像钉钉、企业微信或者其他SaaS软件，他们的API文档一般都比较完善，去开发者平台仔细看就是了。如果是自己开发的或者非常老旧的系统，那可能就需要我们自己动手写个接口“适配器”了。

2. 安全第一，千万别忘了“签名”和“认证”

系统间通信，怎么证明“你就是你”、“我发的数据没被改过”？这就是安全认证要解决的问题。常见的API认证方式有：

• API Key/Secret：最简单，就是给你一个账号密码一样的钥匙，每次请求带上。
• OAuth 2.0：更标准也更安全，用户授权应用访问自己的数据，常见于和钉钉、微信对接。
• JWT（JSON Web Token）：轻量级的令牌，一般是登录后获取一个有时效性的token，后续请求都带上它。
• 数字签名：对请求内容进行加密签名，防止数据被篡改，常用于金融级别的交互。

根据企业的安全级别来选，国企金融一般要求更高，普通的私企用API Key+ HTTPS基本够用。

3. 数据“方言”大一统

这是个大坑。HR系统里的性别可能是“男/女”，ERP里可能是“M/F”，OA里可能是“1/2”。员工状态在HR里可能是“在职”，在OA里是“Active”。这种数据不一致，必须在对接前提前定好标准。要么都用HR系统的标准，要么定义一套新的标准，让两边都向新标准看齐。

三、开始干活：API对接的核心流程

接下来，我们以最常见的“新员工入职”场景为例子，一步步看API是怎么跑起来的。

第一步：权限申请与获取Token

任何数据交互前，得先拿到准入许可。

// 伪代码示例：获取访问令牌
POST https://api.oa-system.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=你的应用ID
&client_secret=你的应用密钥

请求发送后，如果没有问题，OA系统会返回一个类似这样的JSON给你:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

这个access_token就是你接下来一小时内的通行证。

第二步：HR系统创建员工，推送给OA和ERP

HR在系统A里录入了张三的入职信息，点击保存。系统A后台会触发一个API调用逻辑。

以张三入职，需要同步到OA创建账号为例：

// 伪代码示例：向OA推送新员工数据
POST https://api.oa-system.com/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "employee_id": "10003",
  "name": "张三",
  "department_id": "D-005",
  "position": "Java开发工程师",
  "email": "zhangsan@company.com",
  "join_date": "2023-10-27"
}

第三步：OA系统处理数据并反馈

OA系统接收到这个请求，经过校验（比如工号是否重复），在自己的数据库里创建了张三的账号，并默认开通了OA、考勤等权限。

然后，OA需要给HR系统一个回应：

// OA的响应
HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "success",
  "oa_user_id": "OA-20231027-8846",
  "msg": "用户创建成功，并已发送初始密码邮件"
}

HR系统收到这个201 Created和成功的JSON，就知道OA这头的事情办妥了，可以在HR系统的界面上给HR一个提示：“OA账号已创建成功，密码邮件已发送”。同样道理，HR系统再发起一次请求给ERP系统，在ERP的HR模块创建档案（或者叫“职员主数据”）。

数据同步的几种“姿势”

• 单向同步：就像刚才说的新员工入职，通常以HR为主，推送到其他系统。
• 双向同步：比如员工的手机号、邮箱可能在OA里修改得更频繁，允许OA修改后再同步回HR，这里要处理好冲突，比如“修改时间戳优先”或者“HR系统优先”。
• 轮询拉取：如果无法实现推送（系统太老，内网无法对外暴露接口），可以做一个中间库，让新系统定时去这个中间库拉取变更数据。
• 事件驱动（Webhook）：HR系统修改后，主动推送一个事件消息（类似消息队列）给中间件，中间件再分发给下游系统。

四、实战中的“一地鸡毛”与处理方案

理论很丰满，现实很骨感。真干起来，你会碰到各种奇葩问题。

1. 网络不通，跨不过去的防火墙

很多公司的OA、ERP部署在内网，有严格的防火墙策略。HR系统可能在公有云上。直接通过公网IP调用内网API，安全风险很高，通常会被拦住。

解决方案：

• 内网穿透：找一台既能访问内网又能访问外网的服务器（跳板机），部署一个内网穿透工具，或者干脆用商业的内网穿透服务。
• 专线/VPN连接：如果预算充足，云上资源和本地数据中心通过专线或VPN打通，API调用就走这条专道，保证稳定和安全。
• 搞个中间件服务器（ESB/集成平台）：这是我最推荐的方式。在公司内网架设一个API网关或者集成平台，所有系统都只跟这个平台对话。HR系统通过VPN或者公网鉴权访问这个平台，平台再转发到内网的ERP/OA。这样架构清晰，也方便管理。

2. 数据格式不统一，JSON vs XML

现在一般新系统都是JSON格式，但有些老掉牙的ERP系统还在用XML，甚至更古老的用SOAP（也是一种XML）。两边语言不通。

解决方案：

• 在中间件层做数据转换（Transformation）。比如接收到ERP发的XML，先解析成JSON或者内部对象，再转换成标准JSON发给HR系统。

3. 接口不稳定，请求超时或报错

ERP系统晚上在跑批结账，可能会关掉服务或者响应很慢，这时候HR系统发请求过去就会失败。

解决方案：

• 重试机制：如果第一次请求失败，不要立即报错，可以等1分钟、5分钟后再试一次，最多重试3次。
• 异步处理：不要让HR系统的用户傻等着。HR点击保存后，只要把数据写入本地数据库的“待同步队列”表，就可以提示用户保存成功了。后台再用一个叫“同步服务”的程序，夜以继日地从这个队列里拿数据，一次次地去调用外部API，直到成功为止，失败了就记录日志报警。

一个简单的“同步任务表”设计思路

id	data_type	payload	target_sys	status	retry_count	last_error	create_time
101	emp_onboard	{'id':10003, ...}	ERP	pending	0		2023-10-27 09:00:00

五、那些年我们踩过的坑（血泪教训）

有一些坑，真是书上学不到，只有干了才知道疼。

• ID对应关系错乱：HR系统生成了员工ID是10001，ERP系统根据身份证号生成了另一套ID，OA系统又按邮箱生成了ID。传递数据时，得根据手机号或者身份证号这种“不变量”来查对方的ID。通常需要建一个“映射表”，记录下大象和蚂蚁之间的对应关系。
• 不要直接传密码！：千万别图省事，把OA的账号密码直接通过API发过去。万一泄露了怎么办？通常只创建账号，密码由目标系统通过邮件或短信随机生成发给用户本人，或者走SSO（单点登录）认证。
• 接口版本迭代：今天ERP厂商升级了接口，把字段salary改成了base_salary，咱们的HR系统没改，一推数据就报错。所以，API的版本控制（比如URL里加/v1/, /v2/）非常重要，对接前一定要约定好兼容性策略。
• 事务一致性：这是个高级问题。比如HR系统在A库，ERP在B库，如果A库写入成功了，B库写入失败了，数据就不一致了。对于简单业务，人工核对或者写个对账脚本定期跑就行。对于金融强一致性要求的，可能需要用到分布式事务，比如Saga或者两阶段提交，但这对集成来说负担太重了，通常不建议在集成层面做复杂事务，尽量把流程拆小，允许暂时不一致，再通过补偿机制修复。

六、一点碎碎念：工具与团队

如果你的公司系统足够多，改一个业务逻辑要动五六个系统的接口，那你就该考虑上 iPaaS 平台了（Integration Platform as a Service）。市面上有很多这类工具，比如 MuleSoft, Boomi，或者国内的钉钉连接器、数环通之类。它们提供了可视化的拖拽界面，把API调用封装成了简单的模块，不用每次都自己写代码，也省去了维护服务器的工作。

当然，不管用什么工具，API文档（API Specification） 是人与人之间沟通的桥梁，比代码还重要。接口地址、请求方法、字段定义、错误码列表、调用示例，最好用Swagger或者YApi这种工具自动生成并维护，这样前端、后端、测试都能看懂，不至于扯皮。

有些CIO喜欢搞个大一统平台，把所有接口都收归国有，这当然好。但对于我们干活的来说，有时候为了赶项目，两个系统之间“私相授受”，直接连了API，这种情况在大公司也不少见。只要做好监控，留好文档，也是解决问题的一种方式。

最后，其实API对接这事儿，技术上不难，难的是业务逻辑的梳理和各个部门利益的平衡。HR怕数据泄露，财务怕账目不准，IT怕系统搞崩。多开会，多沟通，把数据流向图画清楚，把异常场景（比如断网、数据重复、离职回滚）想明白，这事儿就成了一大半。

搞技术嘛，有时候就是把复杂的事情简单化，让大家工作轻松点，这就行了。

人力资源系统服务