Tích hợp EWA với chấm công, payroll và ERP cần dữ liệu gì?

Để tích hợp EWA với chấm công, payroll và ERP, doanh nghiệp cần tối thiểu năm nhóm dữ liệu: hồ sơ nhân viên, công đã được duyệt, kỳ và quy tắc tính lương, các khoản điều chỉnh hoặc khấu trừ, và giao dịch nhận lương sớm. Tất cả phải dùng một mã nhân viên thống nhất, có trạng thái, thời điểm cập nhật, phiên bản dữ liệu và nhật ký truy vết. Kiến trúc tốt không chỉ truyền dữ liệu nhanh mà còn phải ngăn chi trả trùng, xử lý được dữ liệu sửa muộn và đối soát đến từng giao dịch.

> Lưu ý: Bài viết trình bày kiến trúc tham khảo cho một hệ thống EWA (Earned Wage Access – tiếp cận phần tiền lương đã kiếm được). Tên trường, trạng thái, luồng phê duyệt và cách hạch toán thực tế cần được Nhân Kiệt cùng doanh nghiệp xác nhận trong giai đoạn khảo sát tích hợp.

> Giải thích thuật ngữ: EWA (nhận lương theo ngày công đã làm) · HRIS/HRM (hệ thống thông tin nhân sự) · ERP (hệ thống hoạch định nguồn lực doanh nghiệp) · payroll (tính lương) · API (giao diện kết nối phần mềm) · batch (xử lý theo lô) · SFTP (truyền file bảo mật) · idempotency (chống lặp: gửi lại nhiều lần chỉ tạo một kết quả) · UAT (kiểm thử nghiệm thu) · go-live (đưa vào vận hành chính thức) · rollback (quay lui) · webhook/callback (thông báo tự động giữa các hệ thống) · token (mã thay thế dữ liệu gốc) · data dictionary (từ điển dữ liệu) · system of record (nguồn dữ liệu chuẩn) · retry (thử lại) · timeout (hết thời gian chờ).

Vì sao EWA phải kết nối đồng thời với chấm công, payroll và ERP?

EWA cần trả lời ba câu hỏi trước khi cho phép một người lao động nhận tiền:

1. Người này có đang làm việc và thuộc chương trình hay không?

2. Đến thời điểm hiện tại, họ đã tạo ra bao nhiêu tiền lương đủ điều kiện?

3. Sau các giao dịch trước đó và những khoản cần giữ lại, số tiền còn có thể nhận là bao nhiêu?

Hệ thống nhân sự thường xác nhận danh tính và tình trạng làm việc. Hệ thống chấm công ghi nhận số công hoặc số giờ đã làm. Payroll nắm quy tắc lương, kỳ lương và các khoản điều chỉnh. ERP hoặc hệ thống kế toán phục vụ ghi nhận, đối soát và quyết toán. Hệ thống thanh toán cung cấp trạng thái chuyển tiền cuối cùng.

Nếu chỉ kết nối một nguồn, EWA có thể thấy người lao động nhưng không biết số công đã được duyệt; hoặc thấy công nhưng không biết kỳ lương đã khóa; hoặc đã chuyển tiền nhưng payroll chưa nhận được giao dịch để đối soát. Vì vậy, điểm quan trọng nhất không phải là “kết nối được API”, mà là thiết lập được một chuỗi dữ liệu nhất quán từ công đã làm đến giao dịch đã quyết toán.

1. Kiến trúc dữ liệu tổng thể

Một kiến trúc tham khảo có thể được tổ chức như sau:

```mermaid
flowchart TD
A["HRIS: nhân viên"] --> D["Lớp tích hợp"]
B["Chấm công: công đã duyệt"] --> D
C["Payroll: kỳ lương và quy tắc"] --> D
D --> E["Bộ máy tính hạn mức EWA"]
E --> F["Ứng dụng EWA"]
F --> G["Hệ thống thanh toán"]
G --> H["Đối soát payroll, ERP và kế toán"]
H --> E

Mỗi miền dữ liệu nên có một nguồn dữ liệu chuẩn (system of record). Không nên để HRIS, payroll và EWA cùng sửa một thuộc tính theo ba cách khác nhau.

2. Danh mục dữ liệu nhân viên tối thiểu

Không nên đồng bộ toàn bộ hồ sơ nhân sự chỉ vì “có thể cần”. Nguyên tắc phù hợp là thu thập và truyền đúng dữ liệu cần thiết cho mục đích đã xác định.

Số tài khoản đầy đủ chỉ nên tồn tại trong miền thực sự cần dùng để thanh toán, được phân quyền và bảo vệ phù hợp. Môi trường thử nghiệm nên dùng dữ liệu giả hoặc đã che giấu, không sao chép nguyên dữ liệu sản xuất.

3. Dữ liệu chấm công và trạng thái duyệt

EWA không nên chỉ nhận một con số “tổng công tháng”. Hệ thống cần đủ thông tin để biết dữ liệu nào đã được xác nhận và dữ liệu nào còn có thể thay đổi.

Các trường thường cần gồm:

• employee_id: mã nhân viên thống nhất;

• work_date: ngày làm việc;

• shift_id: mã ca, nếu doanh nghiệp quản lý theo ca;

• regularhours, overtimehours: giờ công thường và giờ làm thêm;

• attendance_status: có mặt, nghỉ phép, vắng mặt hoặc trạng thái tương ứng;

• approval_status: chờ duyệt, đã duyệt, từ chối, điều chỉnh hoặc khóa;

• approvedby, approvedat: người và thời điểm duyệt nếu chính sách yêu cầu;

• sourceupdatedat, record_version: thời điểm và phiên bản bản ghi;

• source_system: hệ thống phát sinh dữ liệu.

Vì sao trạng thái “đã duyệt” quan trọng?

Một lượt quẹt thẻ chưa chắc đã là công hợp lệ. Nhân viên có thể quên chấm ra, đăng ký sai ca hoặc có điều chỉnh sau khi quản lý duyệt. Doanh nghiệp cần thống nhất rõ trạng thái nào được tính vào hạn mức EWA (xem Công đã duyệt là gì?).

Ví dụ về một bản ghi minh họa:

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

Đây chỉ là mẫu dữ liệu an toàn để minh họa, không phải đặc tả API chính thức của Lương Ngày.

4. Dữ liệu lương và khoản điều chỉnh

Dữ liệu payroll giúp chuyển “công đã duyệt” thành “phần tiền lương đủ điều kiện”. Bộ dữ liệu thường bao gồm:

• mã kỳ lương payperiodid và thời gian bắt đầu, kết thúc;

• nhóm lương và chu kỳ trả lương;

• cơ sở tính lương hoặc đơn giá cần thiết cho công thức đã thống nhất;

• mã khoản thu nhập earning_code;

• các khoản điều chỉnh, tạm giữ hoặc khấu trừ có liên quan;

• ngày chốt công và thời điểm khóa bảng lương;

• trạng thái kỳ lương: mở, đang xử lý, đã khóa hoặc đã quyết toán;

• đơn vị tiền tệ và quy tắc làm tròn;

• phiên bản công thức/chính sách được áp dụng.

Không phải mọi thành phần trên phiếu lương đều được tính vào hạn mức EWA. Lương cơ bản, phụ cấp, làm thêm giờ, thưởng hay hoa hồng có mức độ chắc chắn và thời điểm phê duyệt khác nhau. Doanh nghiệp phải lập một bảng quy tắc chỉ rõ khoản nào được tính, tính từ trạng thái nào và bị giới hạn ra sao.

Bảng quy tắc nên có những cột gì?

Các giá trị thực tế trong bảng này phải do doanh nghiệp và đơn vị triển khai xác nhận. Không nên suy đoán từ tên khoản lương.

5. Dữ liệu giao dịch nhận lương sớm

Mỗi yêu cầu nhận lương sớm cần là một giao dịch có thể truy vết độc lập.

Một vòng đời giao dịch tham khảo gồm: CREATED → VALIDATING → PROCESSING → SUCCEEDED hoặc FAILED. Nếu chưa xác định được kết quả thanh toán, giao dịch nên ở trạng thái UNKNOWN hoặc tương đương để tra soát; không được mặc định thất bại rồi tự động chuyển tiền lần nữa. Hệ thống cũng cần trạng thái hoàn trả và đã đối soát khi nghiệp vụ phát sinh.

6. Chọn API, file batch hay đồng bộ thủ công?

Không có một phương thức phù hợp cho mọi doanh nghiệp. Có thể kết hợp nhiều cách theo độ trưởng thành của từng hệ thống.

Nếu dùng HTTP API, doanh nghiệp có thể mô tả hợp đồng tích hợp bằng OpenAPI Specification để hai bên thống nhất endpoint, cấu trúc dữ liệu và phản hồi. OpenAPI là tiêu chuẩn mô tả API HTTP; đây là lựa chọn kỹ thuật hữu ích, không phải điều kiện bắt buộc để triển khai EWA.

7. Định danh và chống dữ liệu trùng

Sai định danh là một trong những rủi ro nguy hiểm nhất. Email, số điện thoại hoặc số tài khoản có thể thay đổi, nên không phù hợp làm khóa nhân viên chính.

Khuyến nghị:

• dùng employee_id bất biến trong phạm vi một doanh nghiệp;

• kết hợp với employerid hoặc legalentity_id nếu nền tảng phục vụ nhiều đơn vị;

• không tái sử dụng mã của người đã nghỉ cho người mới;

• duy trì bảng ánh xạ khi HRIS và payroll đang dùng hai bộ mã khác nhau;

• ghi nhận ngày hiệu lực cho các thay đổi về nhóm lương, đơn vị và trạng thái làm việc;

• kiểm tra trùng theo khóa nghiệp vụ, không chỉ theo nội dung giống nhau.

Với file batch, mỗi file nên có mã lô, thời điểm tạo, tổng số bản ghi và checksum. Với API, mỗi yêu cầu tạo giao dịch nên có idempotency_key.

8. Idempotency và đối soát: hai lớp bảo vệ khác nhau

Idempotency giúp một yêu cầu được gửi lại nhiều lần nhưng chỉ tạo ra một kết quả nghiệp vụ. Ví dụ, ứng dụng bị timeout sau khi gửi lệnh chuyển tiền. Khi gửi lại cùng idempotency_key, hệ thống phải trả về giao dịch cũ hoặc trạng thái của nó, thay vì tạo thêm một lần chi trả.

Đối soát kiểm tra các hệ thống có cùng ghi nhận một giao dịch hay không (gắn với quy trình Lương Ngày từ chấm công đến đối soát). Một mô hình phù hợp là đối soát ba chiều:

1. giao dịch trong nền tảng EWA;

2. kết quả từ ngân hàng hoặc đơn vị thanh toán;

3. dữ liệu payroll/ERP hoặc hồ sơ quyết toán đã được phê duyệt.

Báo cáo đối soát nên chỉ ra ít nhất:

• giao dịch khớp hoàn toàn;

• có trong EWA nhưng chưa có kết quả thanh toán;

• có kết quả thanh toán nhưng thiếu trong payroll/ERP;

• lệch số tiền, phí, người nhận hoặc kỳ lương;

• giao dịch hoàn trả nhưng chưa cập nhật;

• bản ghi trùng hoặc cập nhật sai thứ tự.

Mỗi chênh lệch cần có người phụ trách, trạng thái xử lý và bằng chứng đóng lỗi.

9. Xử lý lỗi, retry và cảnh báo

Không phải lỗi nào cũng nên thử lại tự động.

Mọi request nên có correlation_id để truy vết xuyên hệ thống. Cảnh báo cần chứa mã giao dịch, loại lỗi, thời điểm, hệ thống nguồn và bước xử lý tiếp theo, nhưng không đưa mật khẩu, khóa API hoặc dữ liệu nhạy cảm đầy đủ vào log.

10. Mẫu yêu cầu API minh họa

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

Phản hồi nên cho biết yêu cầu được chấp nhận, bị từ chối hay cần xử lý thêm; đồng thời trả transactionid, trạng thái, mã lý do và correlationid. Không nên trả dữ liệu tài khoản đầy đủ hoặc thông tin không cần thiết.

Đặc tả API nên quy định rõ:

• phương thức xác thực và phân quyền;

• phiên bản API và chính sách thay đổi;

• định dạng ngày giờ, múi giờ và đơn vị tiền tệ;

• độ chính xác của số tiền và quy tắc làm tròn;

• danh mục mã lỗi;

• timeout và chính sách retry;

• chữ ký/xác minh callback hoặc webhook;

• giới hạn tải;

• quy tắc idempotency;

• thời gian lưu trạng thái và nhật ký.

11. Bảo mật và bảo vệ dữ liệu ngay từ thiết kế

Dữ liệu nhân viên, lương, tài khoản nhận tiền và lịch sử giao dịch có mức độ nhạy cảm cao. Thiết kế tích hợp nên bao gồm:

• phân quyền theo vai trò và nguyên tắc quyền tối thiểu;

• mã hóa dữ liệu khi truyền và khi lưu;

• quản lý bí mật tập trung, không để khóa truy cập trong mã nguồn hoặc log;

• tách môi trường phát triển, thử nghiệm và sản xuất;

• dữ liệu thử nghiệm giả lập hoặc đã che giấu;

• nhật ký truy cập và thay đổi cấu hình;

• thời hạn lưu trữ, quy trình xóa và xử lý yêu cầu của chủ thể dữ liệu;

• đánh giá nhà cung cấp và phạm vi chia sẻ dữ liệu;

• kế hoạch ứng phó, thông báo và điều tra sự cố.

Tại Việt Nam, thiết kế và vận hành cần được bộ phận pháp lý rà soát theo Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15 và Nghị định 356/2025/NĐ-CP, đều có hiệu lực từ ngày 1/1/2026. Hồ sơ, thông điệp và chứng từ điện tử cũng cần được xem xét trong khuôn khổ Luật Giao dịch điện tử 2023 và quy định chuyên ngành có liên quan.

12. Checklist UAT trước khi go-live

UAT không nên chỉ kiểm tra “nhận được file” hoặc “API trả 200” (đưa vào kế hoạch pilot EWA 90 ngày). Cần thử đủ các tình huống nghiệp vụ và lỗi vận hành.

Nhân viên và điều kiện tham gia

• [ ] Nhân viên đang làm việc và đủ điều kiện.

• [ ] Nhân viên mới chưa đến ngày hiệu lực.

• [ ] Nhân viên tạm nghỉ hoặc đã nghỉ việc.

• [ ] Nhân viên chuyển pháp nhân, nhóm lương hoặc mã nhân viên.

• [ ] Thay đổi tài khoản nhận tiền theo đúng luồng xác minh.

Chấm công và hạn mức

• [ ] Công đang chờ duyệt không được tính nếu chính sách yêu cầu công đã duyệt.

• [ ] Công được duyệt làm hạn mức thay đổi đúng.

• [ ] Công bị sửa hoặc thu hồi sau khi duyệt được tính lại đúng.

• [ ] Dữ liệu cũ đến sau dữ liệu mới không ghi đè sai phiên bản.

• [ ] Ngày chốt công, múi giờ và ca qua đêm được xử lý đúng.

Giao dịch và thanh toán

• [ ] Gửi lặp cùng idempotency_key không tạo hai giao dịch.

• [ ] Không đủ hạn mức trả về lý do chính xác.

• [ ] Hệ thống thanh toán timeout và kết quả chưa rõ không gây chuyển tiền lần hai.

• [ ] Giao dịch thất bại, hoàn trả và đảo trạng thái được cập nhật đúng.

• [ ] Hạn mức trước và sau giao dịch khớp với sổ giao dịch.

File batch và API

• [ ] File trùng, file sai thứ tự và bản ghi trùng được phát hiện.

• [ ] Một số bản ghi lỗi không làm mất dấu các bản ghi đã xử lý.

• [ ] API hết hạn xác thực, thiếu quyền và vượt giới hạn tải trả lỗi đúng.

• [ ] Callback giả mạo hoặc sai chữ ký bị từ chối.

• [ ] Retry tuân thủ giới hạn và giữ nguyên khóa chống trùng.

Payroll, ERP và đối soát

• [ ] Kỳ lương mở, khóa và đã quyết toán được xử lý đúng.

• [ ] Giao dịch EWA được đưa vào hồ sơ đối soát kỳ lương theo quy trình đã phê duyệt.

• [ ] Ba nguồn EWA – thanh toán – payroll/ERP khớp số tiền và trạng thái.

• [ ] Chênh lệch tạo cảnh báo và có luồng xử lý đến khi đóng.

• [ ] Báo cáo có thể truy ngược từ bút toán đến giao dịch và dữ liệu nguồn.

Bảo mật và vận hành

• [ ] Người không có quyền không xem hoặc sửa được dữ liệu.

• [ ] Log không chứa bí mật hoặc dữ liệu nhạy cảm đầy đủ.

• [ ] Khóa truy cập có thể luân chuyển mà không gián đoạn kéo dài.

• [ ] Có người trực, kênh cảnh báo và quy trình xử lý sự cố.

• [ ] Có kế hoạch quay lui nếu go-live gặp lỗi nghiêm trọng.

13. Hồ sơ kỹ thuật hai bên cần chốt trước triển khai

Một bộ hồ sơ tích hợp tối thiểu nên có:

1. sơ đồ kiến trúc và ranh giới trách nhiệm;

2. data dictionary cho từng trường;

3. bảng ánh xạ mã nhân viên, kỳ lương, đơn vị và mã khoản;

4. đặc tả API hoặc đặc tả file;

5. danh mục trạng thái và mã lỗi;

6. quy tắc tính hạn mức đã được phê duyệt;

7. quy tắc chống trùng, retry và xử lý dữ liệu đến muộn;

8. luồng đối soát và mẫu báo cáo chênh lệch;

9. ma trận phân quyền và yêu cầu bảo mật;

10. kế hoạch UAT, cutover, rollback và hỗ trợ sau go-live.

Các bên cũng nên thực hiện kiểm thử hợp đồng dữ liệu. Khi một hệ thống đổi tên trường, kiểu dữ liệu, danh mục trạng thái hoặc ý nghĩa nghiệp vụ, pipeline phải cảnh báo trước khi thay đổi gây sai hạn mức ngoài môi trường sản xuất.

<!-- MỤC CHỜ NHÂN KIỆT HOÀN THIỆN (ẩn khi đăng) — dữ liệu Product/IT cần xác nhận để phản ánh đúng năng lực tích hợp thực tế; không công bố tên đối tác/SLA/tính năng khi chưa có tài liệu.
## 14. Những dữ liệu Nhân Kiệt cần bổ sung trước khi xuất bản bản chính thức

Để bài viết phản ánh đúng năng lực thực tế của Lương Ngày, đội Product/IT cần xác nhận:

• các hệ thống chấm công, payroll hoặc ERP đang hỗ trợ;

• phương thức tích hợp hiện có: API, SFTP, file mẫu hoặc phương thức khác;

• chu kỳ đồng bộ và cam kết dịch vụ thực tế;

• danh sách endpoint, trường dữ liệu, trạng thái và mã lỗi được phép công khai;

• cơ chế xác thực, idempotency, webhook và đối soát đang sử dụng;

• luồng xử lý giao dịch chưa rõ kết quả, thất bại và hoàn trả;

• quy tắc tính hạn mức và các thành phần lương đủ điều kiện;

• mẫu báo cáo kỹ thuật đã loại bỏ dữ liệu cá nhân;

• trách nhiệm của Nhân Kiệt, doanh nghiệp và đối tác thanh toán;

• đầu mối tiếp nhận tài liệu tích hợp và hỗ trợ UAT.

Không nên công bố tên đối tác, thời gian xử lý, SLA hoặc tính năng kỹ thuật khi chưa có xác nhận bằng tài liệu.

-->

Kết luận

Tích hợp EWA không phải là kéo một file chấm công rồi tính tỷ lệ phần trăm. Một hệ thống đáng tin cậy cần dữ liệu nhân viên, công đã duyệt, quy tắc payroll và giao dịch được liên kết bằng định danh thống nhất; đồng thời có phiên bản dữ liệu, idempotency, trạng thái thanh toán, đối soát và quy trình xử lý lỗi.

Nếu doanh nghiệp đang đánh giá khả năng kết nối Lương Ngày với hệ thống chấm công, payroll hoặc ERP hiện có, hãy chuẩn bị sơ đồ hệ thống, một data dictionary đã ẩn dữ liệu cá nhân và các tình huống nghiệp vụ cần hỗ trợ, rồi tìm hiểu Lương Ngày cho doanh nghiệp để trao đổi về tài liệu tích hợp kỹ thuật và phạm vi pilot phù hợp.

Nguồn tham khảo

• OpenAPI Initiative – OpenAPI Specification

• OpenAPI Specification trên GitHub

• Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15

• Nghị định 356/2025/NĐ-CP hướng dẫn Luật Bảo vệ dữ liệu cá nhân

• Luật Giao dịch điện tử số 20/2023/QH15

---

Tác giả: Ngô Nhã Kỳ— Biên tập viên, Công ty TNHH Cung Ứng Nhân Lực Nhân Kiệt.

Tư vấn giải pháp Lương Ngày cho doanh nghiệp: Hotline 0937.022.655 · Email info@nhankiet.vn · Lương Ngày cho doanh nghiệp