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 – 已賺取工資的訪問）系統的參考架構。字段名稱、狀態、審批流程和實際會計處理需要在集成調查階段由 Nhân Kiệt 與企業確認。

> 術語解釋： EWA（已完成工作日的工資訪問） · HRIS/HRM（人力資源信息系統） · ERP（企業資源規劃系統） · 薪資（工資計算） · API（應用程式介面） · 批量處理 · SFTP（安全文件傳輸協議） · 冪等性（防重複：多次發送只產生一個結果） · UAT（用戶驗收測試） · 上線（正式運行） · 回滾 · webhook/callback（系統間的自動通知） · token（數據替代碼） · 數據字典 · 記錄系統 · 重試 · 超時。

為什麼 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

不應僅僅因為“可能需要”而同步整個人力資源檔案。合適的原則是收集和傳輸為已確定目的所需的準確數據。
2.最低限度的員工資料清單

數據字段	目的	建議要求
`employee_id`	跨系統的唯一識別鍵	必須，唯一，不可重用
`employerid` / `legalentity_id`	區分企業和法人	多企業系統必須
`payroll_group`	映射薪資日曆和規則	如果有多個薪資組必須
`employment_status`	檢查是否在職、暫停或已離職	必須，有生效日期
`effectivefrom`, `effectiveto`	確定生效時間	狀態變更必須
`worksiteid` / `departmentid`	根據單位應用政策	僅在政策使用時傳輸
`ewa_eligibility`	確定是否屬於計劃	必須或通過已確定規則推導
`bankaccounttoken`	限制賬戶數據傳播的轉賬	優先使用 token 或遮蔽數據
`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
}

這只是安全的數據示例，並非 EWA 的正式 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 描述集成合同，以便雙方統一 endpoint、數據結構和響應。OpenAPI 是描述 HTTP API 的標準；這是一個有用的技術選擇，但不是實施 EWA 的必要條件。

7. 身份識別和防重數據

錯誤的身份識別是最危險的風險之一。電子郵件、電話號碼或賬戶號碼可能會更改，因此不適合作為主要員工鍵。

建議：

在一個企業範圍內使用不變的 employee_id；
如果平台服務多個單位，結合使用 employerid 或 legalentity_id；
不要將已離職員工的編號重用於新員工；
當 HRIS 和薪資使用兩套不同的編號時，維護映射表；
為薪資組、單位和工作狀態的變更記錄生效日期；
根據業務鍵檢查重複，而不僅僅根據相同內容。

對於批量文件，每個文件應有批次編號、創建時間、記錄總數和校驗和。對於 API，每個創建交易的請求應有 idempotency_key。

8. 冪等性和對賬：兩種不同的保護層

冪等性 確保同一請求多次發送但只產生一個業務結果。例如，應用在發送轉賬命令後超時。當再次發送相同的 idempotency_key 時，系統應返回舊交易或其狀態，而不是創建另一筆支付。

對賬檢查系統是否對同一交易有相同記錄（與從考勤到對賬的 EWA 流程相關）。一個合適的模型是三方對賬：

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”（納入 90 天 EWA 試點計劃）。需要測試足夠的業務情況和運行錯誤。

員工和參加條件

[ ] 員工正在工作並符合條件。
[ ] 新員工尚未到生效日期。
[ ] 員工暫停或已離職。
[ ] 員工轉換法人、薪資組或員工編號。
[ ] 按正確的驗證流程更改收款賬戶。

考勤和限額

[ ] 如果政策要求已批准工時，待審批工時不計算。
[ ] 已批准工時正確改變限額。
[ ] 在審批後修改或撤回的工時正確重新計算。
[ ] 舊數據到達後不覆蓋新數據的版本錯誤。
[ ] 工時結算日期、時區和過夜班次正確處理。

交易和支付

[ ] 使用相同的 idempotency_key 重複發送不創建兩筆交易。
[ ] 不足限額返回正確原因。
[ ] 支付系統超時和結果不明不會導致再次轉賬。
[ ] 交易失敗、退款和狀態變更正確更新。
[ ] 交易前後的限額與交易記錄一致。

批量文件和 API

[ ] 重複文件、錯誤順序文件和重複記錄被檢測。
[ ] 部分記錄錯誤不會丟失已處理的記錄。
[ ] API 驗證過期、缺少權限和超過負載限制返回正確錯誤。
[ ] 偽造或錯誤簽名的回調被拒絕。
[ ] 重試遵循限制並保持防重鍵不變。

薪資、ERP 和對賬

[ ] 開放、鎖定和已結算的薪資週期正確處理。
[ ] EWA 交易按已批准流程納入薪資週期對賬記錄。
[ ] EWA、支付和薪資/ERP 三方金額和狀態一致。
[ ] 差異創建警報並有處理流程直至關閉。
[ ] 報告可從分錄追溯到交易和數據來源。

安全和運行

[ ] 無權人員無法查看或修改數據。
[ ] 日誌不包含秘密或完整的敏感數據。
[ ] 訪問密鑰可輪換而不長時間中斷。
[ ] 有值班人員、警報渠道和事件處理流程。
[ ] 如果上線遇到嚴重錯誤，有回滾計劃。

13. 雙方在實施前需要確定的技術文檔

一個最低限度的集成文檔應包括：

架構圖和責任邊界；
每個字段的數據字典；
員工編號、薪資週期、單位和項目代碼的映射表；
API 規範或文件規範；
狀態和錯誤碼目錄；
已批准的限額計算規則；
防重、重試和延遲數據處理規則；
對賬流程和差異報告模板；
權限矩陣和安全要求；
UAT、切換、回滾和上線後支持計劃。

雙方還應進行數據合同測試。當一個系統更改字段名稱、數據類型、狀態目錄或業務意義時，管道應在更改導致生產環境外的限額錯誤之前發出警告。

## 14. Nhân Kiệt 在正式發布前需要補充的資料

為確保文章內容能準確反映 Lương Ngày 的實際能力，Product/IT 團隊需要確認：

目前支援的考勤、薪資計算（payroll）或 ERP 系統；
現有的整合方式：API、SFTP、範本檔案或其他方式；
實際的同步週期及服務承諾；
可公開的 endpoint、資料欄位、狀態及錯誤代碼清單；
目前使用的驗證機制、idempotency、webhook 及對帳機制；
交易結果不明、交易失敗及退款的處理流程；
額度計算規則及符合資格的薪資項目；
已移除個人資料的技術報告範本；
Nhân Kiệt、企業及付款合作夥伴各自的責任；
整合文件及 UAT 支援的聯絡窗口。

在尚未取得文件確認前，不應公開合作夥伴名稱、處理時間、SLA 或技術功能。
常見問題

EWA 是否必須實時集成？

不是。企業可以使用近實時 API、按計劃的批量文件或在試點中使用有控制的手動流程。頻率需要與限額計算方式、數據變化速度和源系統的運行能力相適應。

僅有考勤數據就能計算 EWA 限額嗎？

通常不夠。還需要員工狀態、薪資週期、工資計算規則、相關調整項目和 EWA 交易歷史。記錄的工時也需要有明確的審批狀態。

為什麼要使用統一的員工編號？

統一的身份識別有助於避免將一個人的工時、工資或交易錯誤地分配給另一個人。如果系統使用不同的編號，企業需要有控制的映射表和生效日期。

冪等性與交易重複檢查相同嗎？

有關聯但不完全相同。冪等性確保同一請求的多次發送不會創建新的業務結果。重複檢查還可以使用其他業務鍵來檢測兩個不同編號但實際上是同一交易的請求。

當轉賬命令超時時，應立即重發嗎？

不應在未確定舊命令結果時重發新支付命令。系統應保持未明狀態，根據參考編號查詢，並僅按既定流程進行後續處理以避免重複支付。

誰負責 EWA 的對賬？

責任應在運行矩陣中規定。通常會有 EWA 運行單位、薪資、會計/財務、IT 和支付合作夥伴的參與。每種差異需要一個具體的負責人。

結論

EWA 集成不僅僅是提取考勤文件然後計算百分比。一個可靠的系統需要員工數據、已批准工時、薪資規則和交易通過統一的身份識別鏈接；同時需要數據版本、冪等性、支付狀態、對賬和錯誤處理流程。

如果企業正在評估將 EWA 與現有考勤、薪資或 ERP 系統連接的可能性，請準備系統圖、一個已隱藏個人數據的數據字典和需要支持的業務情況，然後了解企業的 EWA 以討論技術集成文檔和合適的試點範圍。

參考來源

---

作者： Ngô Nhã Kỳ— 編輯，Nhan Kiet Manpower Supply Co., Ltd.

企業的 EWA 解決方案諮詢： 熱線 0937.022.655 · 電子郵件 info@nhankiet.vn · 企業的 EWA

← 最新消息