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（安全文件傳輸協議）· idempotency（防重：多次發送只產生一個結果）· UAT（用戶驗收測試）· 上線（正式運行）· 回滾（回退）· webhook/callback（系統間自動通知）· token（數據替代碼）· data dictionary（數據字典）· system of record（標準數據源）· retry（重試）· timeout（超時）。

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

每個數據領域應有一個標準數據源（system of record）。不應讓 HRIS、薪資和 EWA 同時以三種不同方式修改一個屬性。

數據領域	建議的標準數據源	在 EWA 中的角色
員工檔案和狀態	HRIS/HRM	確定身份、單位、工作狀態和參加條件
工時、班次和工作時間	考勤系統	確定已完成並核准的工時
薪資週期、工資水平、收入/扣除代碼	薪資系統	計算符合條件的金額並用於薪資週期結算
提前支付交易	EWA 平台	管理請求、限額、費用（如有）和狀態歷史
轉賬結果	銀行/支付合作夥伴	確認成功、失敗、結果不明或退款
分錄和對賬	ERP/會計	對賬金額、債務和結算檔案

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 描述整合合同，以便雙方統一端點、數據結構和反饋。OpenAPI 是描述 HTTP API 的標準；這是一個有用的技術選擇，但不是實施 EWA 的必要條件。

7. 識別和防重數據

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

建議：

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

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

8. Idempotency 和對賬：兩種不同的保護層

Idempotency 確保同一請求多次發送只產生一個業務結果。例如，應用程序在發送轉賬命令後超時。當再次發送相同的 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 的簽名/驗證；
負載限制；
idempotency 規則；
狀態和日誌的保存時間。

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 在正式發布前需要補充的資料

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

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

在尚未取得書面確認之前，不應公開合作夥伴名稱、處理時間、SLA 或任何技術功能。-->

常見問題

EWA 是否必須實時整合？

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

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

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

為什麼要使用相同的員工編號？

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

Idempotency 是否等同於檢查重複交易？

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

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

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

誰負責 EWA 的對賬？

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

結論

整合 EWA 並不是簡單地提取考勤文件然後計算百分比。一個可靠的系統需要員工數據、已核准工時、薪資規則和交易通過統一的識別連接；同時具備數據版本、idempotency、支付狀態、對賬和錯誤處理流程。

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

參考來源

---

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

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

← 最新消息