EWA与考勤、薪资和ERP集成需要哪些数据？

Doanh nghiệp · 15/09/2026 · 作者: Ngô Nhã Kỳ (Biên tập viên ban biên tập)

EWA与考勤、薪资和ERP集成需要哪些数据？

为了将EWA与考勤、薪资和ERP集成，企业至少需要五组数据：员工档案、已批准的工时、薪资周期和规则、调整或扣除项目，以及提前领取工资的交易。所有数据必须使用统一的员工编号，包含状态、更新时间、数据版本和追踪日志。良好的架构不仅要快速传输数据，还要防止重复支付，处理延迟数据，并对每笔交易进行对账。

> 注意： 本文介绍了一个EWA（Earned Wage Access – 日薪预支）系统的参考架构。字段名称、状态、审批流程和实际会计处理需要在集成调查阶段由Nhan Kiet和企业确认。

> 术语解释： EWA（日薪预支） · HRIS/HRM（人力资源信息系统） · ERP（企业资源计划系统） · 薪资（工资计算） · API（应用程序接口） · 批处理（批量处理） · SFTP（安全文件传输协议） · 幂等性（防重复：多次发送只产生一个结果） · UAT（用户验收测试） · 上线（正式运营） · 回滚（撤销） · webhook/callback（系统间自动通知） · 令牌（替代原始数据的代码） · 数据字典 · 记录系统 · 重试 · 超时。

为什么EWA必须同时连接考勤、薪资和ERP？

EWA在允许员工领取工资之前需要回答三个问题：

该员工是否在工作并参与计划？
截至目前，他们已产生多少符合条件的工资？
在之前的交易和需要保留的项目之后，还可以领取多少？

人力资源系统通常确认身份和工作状态。考勤系统记录已完成的工时或小时数。薪资系统掌握工资规则、工资周期和调整项目。ERP或会计系统用于记录、对账和结算。支付系统提供最终的转账状态。

如果仅连接一个来源，EWA可能会看到员工但不知道已批准的工时；或看到工时但不知道工资周期已锁定；或已转账但薪资系统尚未收到交易以进行对账。因此，最重要的不是“连接API”，而是建立从已完成的工时到已结算交易的一致数据链。

1. 总体数据架构

一个参考架构可以组织如下：

flowchart TD
    A["HRIS: 员工"] --> D["集成层"]
    B["考勤: 已批准的工时"] --> D
    C["薪资: 工资周期和规则"] --> D
    D --> E["EWA额度计算引擎"]
    E --> F["EWA应用"]
    F --> G["支付系统"]
    G --> H["薪资、ERP和会计对账"]
    H --> E

每个数据域应有一个标准数据来源（记录系统）。不应让HRIS、薪资和EWA分别以三种不同方式修改同一属性。

数据域	建议的标准数据来源	在EWA中的角色
员工档案和状态	HRIS/HRM	确认身份、单位、工作状态和参与条件
工时、班次和工作时间	考勤系统	确认已完成并已批准的工时
工资周期、工资水平、收入/扣除代码	薪资系统	计算符合条件的金额并用于工资周期结算
提前领取工资交易	EWA平台	管理请求、额度、费用（如适用）和状态历史
转账结果	银行/支付合作伙伴	确认成功、失败、结果不明或退款
会计分录和对账	ERP/会计	对账金额、债务和结算记录

2. 最低员工数据目录

不应仅因为“可能需要”而同步整个员工档案。合适的原则是收集和传输为已确定目的所需的正确数据。

数据字段	目的	建议要求
`employee_id`	跨系统的标识键	必须，唯一，不可重用
`employerid` / `legalentity_id`	区分企业和法人	多企业系统中必需
`payroll_group`	映射工资日历和规则	多工资组时必需
`employment_status`	检查是否在职、休假或已离职	必须，具有生效日期
`effectivefrom`, `effectiveto`	确定生效时间	状态变化时必需
`worksiteid` / `departmentid`	按单位应用政策	仅在使用政策时传输
`ewa_eligibility`	确定参与计划	必须或通过已商定规则推导
`bankaccounttoken`	转账时限制账户数据传播	优先使用令牌或遮蔽数据，限于支付域
`consentversion`, `acceptedat`	记录条款/同意版本	根据已批准的法律流程应用
`sourceupdatedat`, `record_version`	检测旧数据或错误更新顺序	必须以控制同步

完整的银行账户信息应仅存在于真正需要用于支付的域中，并得到适当的权限和保护。测试环境应使用模拟或遮蔽数据，不复制生产数据。

3. 考勤数据和审批状态

EWA不应仅接收一个“月总工时”数字。系统需要足够的信息以了解哪些数据已确认，哪些数据仍可能更改。

通常需要的字段包括：

employee_id：统一的员工编号；
work_date：工作日期；
shift_id：班次代码，如果企业按班次管理；
regularhours, overtimehours：正常工时和加班工时；
attendance_status：出勤、休假、缺勤或相应状态；
approval_status：待审批、已批准、拒绝、调整或锁定；
approvedby, approvedat：审批人和时间（如政策要求）；
sourceupdatedat, record_version：记录的时间和版本；
source_system：数据来源系统。

为什么“已批准”状态很重要？

一次打卡不一定是有效工时。员工可能忘记打卡、登记错误班次或在经理批准后进行调整。企业需要明确哪些状态计入EWA额度（参见已批准的工时是什么？）。

示例记录：

{
  "employee_id": "EMP-000123",
  "work_date": "2026-08-18",
  "shift_id": "SHIFT-A",
  "regular_hours": 8,
  "overtime_hours": 0,
  "approval_status": "APPROVED",
  "source_updated_at": "2026-08-19T02:15:30Z",
  "record_version": 3
}

这只是一个安全数据示例，并非日薪预支的正式API规范。

4. 工资数据和调整项目

薪资数据帮助将“已批准的工时”转化为“符合条件的工资部分”。数据集通常包括：

工资周期代码payperiodid及开始和结束时间；
工资组和支付周期；
工资计算基础或已商定公式所需单价；
收入项目代码earning_code；
相关调整、保留或扣除项目；
工时结算日期和工资表锁定时间；
工资周期状态：开放、处理中、已锁定或已结算；
货币单位和舍入规则；
应用的公式/政策版本。

并非工资单上的所有项目都计入EWA额度。基本工资、津贴、加班费、奖金或佣金的确定性和批准时间各不相同。企业必须制定一张规则表，明确哪些项目被计算，从哪个状态计算以及如何限制。

规则表应包含哪些列？

项目代码	项目名称	计入EWA？	符合条件的状态	公式	应用上限	审批负责人
BASIC	工资	是/否	已批准的工时	按政策	按政策	薪资
OT	加班费	是/否	已批准的加班	按政策	按政策	HR/薪资
BONUS	奖金	是/否	已批准的决策	按政策	按政策	HR/财务

表中的实际值必须由企业和实施单位确认。不要从项目名称推测。

5. 提前领取工资交易数据

每个提前领取工资请求应是一个可独立追踪的交易。

字段	含义
`transaction_id`	EWA系统中的唯一交易编号
`idempotency_key`	防止在同一请求多次发送时创建新交易的键
`employee_id`	执行交易的员工
`payperiodid`	相关工资周期
`requested_amount`	员工请求的金额
`fee_amount`	费用，如政策适用且已公布
`netdisbursedamount`	实际转账金额
`limitbefore`, `limitafter`	交易前后的额度
`status`	当前处理状态
`payment_reference`	与支付单位的参考编号
`createdat`, `processedat`, `completed_at`	用于追踪的时间节点
`sourcedataversion`	用于计算额度的数据版本

一个参考的交易生命周期包括：CREATED → VALIDATING → PROCESSING → SUCCEEDED或FAILED。如果支付结果尚未确定，交易应处于UNKNOWN或等效状态以便查询；不应默认失败然后自动再次转账。系统还需要在业务发生时记录退款和已对账状态。

6. 选择API、批处理文件还是手动同步？

没有一种方法适合所有企业。可以根据每个系统的成熟度结合多种方式。

方法	适用情况	优点	需要控制的点
近实时API	考勤和薪资已有稳定API	数据更新快，易于状态反馈	认证、负载限制、API版本、超时和重试
通过SFTP的批处理文件	旧系统，数据按计划锁定	易于实施，适合大批量	文件名、加密、校验和、文件顺序、重复记录和部分错误文件
有控制的手动同步	小规模试点或过渡阶段	快速启动，易于业务检查	权限、标准表单、日志、双层检查和人为错误风险

如果使用HTTP API，企业可以通过OpenAPI Specification描述集成合同，以便双方统一端点、数据结构和响应。OpenAPI是描述HTTP API的标准；这是一个有用的技术选择，不是实施EWA的必要条件。

7. 标识和防止数据重复

错误的标识是最危险的风险之一。电子邮件、电话号码或银行账户可能会更改，因此不适合作为主要员工键。

建议：

在一个企业范围内使用不变的employee_id；
如果平台服务多个单位，结合使用employerid或legalentity_id；
不要为新员工重复使用已离职员工的编号；
当HRIS和薪资使用两个不同的编号集时，维护映射表；
记录工资组、单位和工作状态变化的生效日期；
根据业务键而不仅仅是相同内容检查重复。

对于批处理文件，每个文件应有批次编号、创建时间、记录总数和校验和。对于API，每个交易创建请求应有idempotency_key。

8. 幂等性和对账：不同的双重保护

幂等性确保同一请求多次发送但只产生一个业务结果。例如，应用在发送转账命令后超时。再次发送相同的idempotency_key时，系统应返回旧交易或其状态，而不是创建额外的支付。

对账检查各系统是否一致记录交易（与从考勤到对账的日薪预支流程相关）。一个合适的模型是三方对账：

EWA平台中的交易；
来自银行或支付单位的结果；
已批准的薪资/ERP数据或结算记录。

对账报告应至少指出：

完全匹配的交易；
在EWA中但尚无支付结果；
有支付结果但缺少在薪资/ERP中的记录；
金额、费用、收款人或工资周期不一致；
退款交易但尚未更新；
重复记录或错误顺序更新。

每个差异需要有负责人、处理状态和关闭错误的证据。

9. 错误处理、重试和警报

并非所有错误都应自动重试。

错误组	示例	建议处理方式
数据错误	缺少员工编号，错误的工资周期	拒绝记录，返回明确错误代码，要求修正来源
业务错误	员工不符合条件，工资周期已锁定	不自动重试；显示适当原因并记录日志
临时错误	网络中断，服务过载	有限次数和间隔重试；保持去重键不变
结果不明	发送支付命令后超时	转为待查询状态；在每次重发前查询状态
永久错误	无效的收款账户，认证失败	停止处理，向负责团队发出警报并要求干预

每个请求应有correlation_id以跨系统追踪。警报需包含交易编号、错误类型、时间、来源系统和后续处理步骤，但不应在日志中包含密码、API密钥或完整的敏感数据。

10. API请求示例

{
  "idempotency_key": "ewa-demo-20260818-0001",
  "employee_id": "EMP-000123",
  "pay_period_id": "2026-08",
  "requested_amount": 1000000,
  "currency": "VND",
  "source_data_version": "attendance-v18_payroll-v6",
  "requested_at": "2026-08-18T09:20:00+07:00"
}

响应应指明请求被接受、拒绝或需要进一步处理；同时返回transactionid、状态、原因代码和correlationid。不应返回完整的账户数据或不必要的信息。

API规范应明确：

认证和权限方法；
API版本和变更政策；
日期时间格式、时区和货币单位；
金额精度和舍入规则；
错误代码目录；
超时和重试政策；
回调或webhook的签名/验证；
负载限制；
幂等性规则；
状态和日志的保存时间。

11. 从设计开始的数据安全和保护

员工数据、工资、收款账户和交易历史具有高度敏感性。集成设计应包括：

基于角色的权限和最小权限原则；
数据传输和存储时加密；
集中管理机密，不在源代码或日志中存放访问密钥；
分离开发、测试和生产环境；
模拟或遮蔽的测试数据；
访问和配置更改日志；
存储期限、删除流程和数据主体请求处理；
供应商评估和数据共享范围；
应急计划、通知和事故调查。

在越南，设计和运营需要法律部门根据《个人数据保护法》第91/2025/QH15号和第356/2025/NĐ-CP号法令进行审查，均自2026年1月1日起生效。电子文件、信息和凭证也需在《2023年电子交易法》和相关行业法规框架内进行审查。

12. 上线前的UAT检查清单

UAT不应仅检查“收到文件”或“API返回200”（纳入EWA 90天试点计划）。需要测试足够的业务场景和操作错误。

员工和参与条件

[ ] 在职且符合条件的员工。
[ ] 新员工尚未生效。
[ ] 暂时休假或已离职的员工。
[ ] 转换法人、工资组或员工编号的员工。
[ ] 按正确的验证流程更改收款账户。

考勤和额度

[ ] 如果政策要求已批准的工时，待审批工时不计入。
[ ] 已批准的工时正确改变额度。
[ ] 已批准后被修改或撤销的工时正确重新计算。
[ ] 旧数据在新数据之后到达时不覆盖错误版本。
[ ] 工时结算日期、时区和跨夜班次正确处理。

交易和支付

[ ] 使用相同idempotency_key的重复发送不创建两个交易。
[ ] 不足额度返回准确原因。
[ ] 支付系统超时且结果不明不导致二次转账。
[ ] 交易失败、退款和状态变更正确更新。
[ ] 交易前后额度与交易记录一致。

批处理文件和API

[ ] 重复文件、错误顺序文件和重复记录被检测。
[ ] 部分记录错误不丢失已处理记录的踪迹。
[ ] API认证过期、缺少权限和超负载返回正确错误。
[ ] 伪造或错误签名的回调被拒绝。
[ ] 重试遵循限制并保持去重键不变。

薪资、ERP和对账

[ ] 工资周期的开放、锁定和结算正确处理。
[ ] EWA交易按已批准流程纳入工资周期对账记录。
[ ] 三方EWA – 支付 – 薪资/ERP匹配金额和状态。
[ ] 差异生成警报并有处理流程直至关闭。
[ ] 报告可从会计分录追溯到交易和源数据。

安全和运营

[ ] 无权限者无法查看或修改数据。
[ ] 日志不包含机密或完整的敏感数据。
[ ] 访问密钥可轮换而不长时间中断。
[ ] 有值班人员、警报渠道和事故处理流程。
[ ] 如果上线遇到严重错误，有回滚计划。

13. 双方在实施前需要确认的技术文件

一个最低限度的集成文件应包括：

架构图和责任边界；
每个字段的数据字典；
员工编号、工资周期、单位和项目代码的映射表；
API或文件规范；
状态和错误代码目录；
已批准的额度计算规则；
去重、重试和延迟数据处理规则；
对账流程和差异报告模板；
权限矩阵和安全要求；
UAT、切换、回滚和上线后支持计划。

双方还应进行数据合同测试。当一个系统更改字段名称、数据类型、状态目录或业务含义时，管道必须在更改导致生产环境外的额度错误之前发出警告。
## 14. Nhân Kiệt 在发布正式版本前需要补充的数据

为了使文章准确反映日薪预支的实际能力，Product/IT 团队需要确认：

支持的考勤、薪资或ERP系统；
当前的集成方法：API、SFTP、文件模板或其他方法；
实际同步周期和服务承诺；
允许公开的端点、数据字段、状态和错误代码列表；
当前使用的认证、幂等性、webhook和对账机制；
未确定结果、失败和退款交易的处理流程；
额度计算规则和符合条件的工资组成部分；
已去除个人数据的技术报告模板；
Nhân Kiệt、企业和支付合作伙伴的责任；
集成文件接收和UAT支持的联系人。

在没有文件确认的情况下，不应公布合作伙伴名称、处理时间、SLA或技术功能。

-->

常见问题

EWA是否必须实时集成？

不。企业可以使用近实时API、按计划的批处理文件或在试点中使用有控制的手动流程。频率需要与额度计算方式、数据变化速度和源系统的操作能力相适应。

仅有考勤数据就能计算EWA额度吗？

通常不够。还需要员工状态、工资周期、工资计算规则、相关调整项目和EWA交易历史。记录的工时也需要明确的审批状态。

为什么要使用相同的员工编号？

统一的标识有助于避免将一个人的工时、工资或交易错误地分配给另一个人。如果各系统使用不同的编号，企业需要有控制的映射表和生效日期。

幂等性与交易重复检查相同吗？

相关但不完全相同。幂等性确保同一请求的重复发送不会产生新的业务结果。重复检查还可以使用其他业务键来检测两个不同编号但实际上是同一交易的请求。

当转账命令超时时，是否应立即重发？

不应在未确定旧命令结果时重发新的支付命令。系统需要保持不明状态，按参考编号查询，并仅按既定流程处理以避免重复支付。

谁负责EWA对账？

责任应在操作矩阵中规定。通常会有EWA运营单位、薪资、会计/财务、IT和支付合作伙伴的参与。每种差异需要一个具体的负责人。

结论

EWA集成不是简单地拉取考勤文件然后计算百分比。一个可靠的系统需要员工数据、已批准的工时、薪资规则和交易通过统一标识链接；同时具备数据版本、幂等性、支付状态、对账和错误处理流程。

如果企业正在评估将日薪预支与现有考勤、薪资或ERP系统连接的可能性，请准备系统图、已隐藏个人数据的数据字典和需要支持的业务场景，然后了解企业日薪预支以讨论适合的技术集成文件和试点范围。

参考来源

---

作者： Ngô Nhã Kỳ— 编辑, Nhan Kiet Manpower Supply Co., Ltd.

企业日薪预支解决方案咨询： 热线 0937.022.655 · 邮箱 info@nhankiet.vn · 企业日薪预支

← 新闻