Lỗi thường gặp khi tích hợp API ngân hàng vào hệ thống kế toán

API trả HTTP 200, giao dịch đã xuất hiện trong phần mềm, nhưng công nợ vẫn lệch. Tình huống này cho thấy kết nối chạy được chưa đồng nghĩa dữ liệu được hiểu đúng. Lỗi có thể nằm ở phạm vi tài khoản, quy tắc phân bổ hoặc kỳ ghi nhận, rất xa đoạn code gửi request đầu tiên.

Lỗi thường gặp khi tích hợp API ngân hàng vào hệ thống kế toán nên được chẩn đoán theo từng lớp. Khi dùng nguồn Pay2S được giới thiệu trên hoadontudong.com.vn, cần lần theo triệu chứng từ kết nối tới dữ liệu, rule và bút toán. Những mã lỗi hoặc log minh họa dưới đây thuộc ứng dụng giả định; khi xử lý sự cố, đối chiếu chúng với contract nguồn và thông báo thực tế của phần mềm kế toán.

Request thành công nhưng lấy sai phạm vi dữ liệu

Một token hợp lệ có thể thuộc đơn vị, ứng dụng hoặc tài khoản khác với phạm vi đang đối soát. Kết quả không rỗng vẫn chưa chứng minh dữ liệu đúng pháp nhân. Lỗi này nguy hiểm vì không tạo exception rõ ràng; báo cáo chỉ lệch hoặc xuất hiện giao dịch không quen.

Kiểm tra danh tính bộ khóa, tài khoản liên kết, quyền truy cập và bộ lọc của request. Đối chiếu một giao dịch mẫu đã biết chắc từ nguồn tới phần mềm. Giữ các định danh phạm vi trong log đã che thông tin nhạy cảm để phát hiện khi cấu hình bị dùng nhầm.

Với Pay2S, xem cơ chế xác thực API theo đúng nhóm sản phẩm. Không dùng một loại token cho mọi endpoint hoặc coi việc authorize thành công là đã có quyền trên toàn bộ ngân hàng của doanh nghiệp.

Mapping tài khoản ngân hàng sai đối tượng kế toán

Phần mềm có thể nhận đúng số tiền nhưng gán vào tài khoản ngân hàng nội bộ hoặc đơn vị kế toán sai. Nguyên nhân thường là mapping theo tên hiển thị, cấu hình mặc định hoặc mã đã đổi mà chưa cập nhật. Hai tài khoản có tên giống nhau không nên được xem là cùng một đối tượng.

Giữ bảng ánh xạ bằng định danh ổn định, gồm chủ thể, tài khoản nguồn và đối tượng tương ứng trong hệ thống kế toán. Khi không có mapping, chặn nghiệp vụ ở staging thay vì gán vào một tài khoản mặc định để import chạy hết. Mỗi thay đổi mapping cần ngày hiệu lực và người duyệt.

Cũng kiểm tra trạng thái kết nối nguồn. Tài liệu Pay2S phân biệt các kiểu liên kết và bước cần xác nhận tiếp. Bài liên kết tài khoản ngân hàng giúp rà cấu hình; dữ liệu ngừng cập nhật không nên bị hiểu là tài khoản không có giao dịch mới.

Lệch ngày do trộn thời gian giao dịch với thời gian nhận

Webhook đến sau nửa đêm có thể chứa giao dịch phát sinh hôm trước. Job nhập bù cũng nhận dữ liệu lịch sử ở thời điểm hiện tại. Nếu adapter dùng thời gian nhận làm ngày giao dịch, báo cáo ngày và đối chiếu kỳ sẽ lệch dù số lượng bản ghi đầy đủ.

Lưu timestamp nguồn, timestamp nhận và mốc nghiệp vụ do hệ thống kế toán quản lý riêng. Xác nhận múi giờ, cách hiểu khoảng lọc có bao gồm hai đầu hay không và quy tắc cắt ngày. Kiểm tra cả giao dịch sát ranh giới thay vì chỉ thử một khoản giữa giờ làm việc.

Khi kỳ đã khóa, ứng dụng phải chuyển sang quy trình được người có thẩm quyền duyệt. Không tự lùi ngày để import thành công. Cần phân biệt dữ liệu ngân hàng gốc với kỳ hạch toán được lựa chọn theo chính sách kế toán của doanh nghiệp.

Số tiền đúng hình thức nhưng sai kiểu hoặc đơn vị

Chuỗi có dấu chấm, dấu phẩy hoặc số thực có thể được chuyển đổi khác nhau giữa các hệ thống. Một dấu phân cách hàng nghìn bị hiểu thành dấu thập phân sẽ làm sai giá trị. Nếu có nhiều đồng tiền, cộng tất cả vào một tổng không kèm đơn vị tạo ra báo cáo không có nghĩa.

Chuẩn hóa tiền bằng kiểu thập phân chính xác hoặc biểu diễn đơn vị nhỏ nhất đã thống nhất, rồi kiểm tra currency. Giữ tài khoản và mã tham chiếu dưới dạng định danh, không chuyển thành số. Trường thiếu dữ liệu phải được phát hiện, không tự đổi thành không đồng để qua validation.

Chiều tiền cũng cần được ánh xạ rõ. Một API có thể tách IN/OUT, phần mềm khác dùng số có dấu. Viết test cho cả hai chiều và khoản điều chỉnh. Lấy trị tuyệt đối mọi giá trị có thể khiến khoản chi trở thành khoản thu mà không phát sinh lỗi cú pháp.

Một giao dịch bị nhập từ nhiều đường

Webhook, job truy vấn và file sao kê có thể cùng đưa một giao dịch vào hệ thống. Nếu mỗi đường tạo bản ghi riêng, số tiền bị cộng nhiều lần. Ngược lại, chống trùng theo cùng số tiền/ngày có thể loại mất hai giao dịch thật.

Cần định danh nguồn ổn định và quan hệ giữa các nguồn khi có thể xác minh. ID của nhà cung cấp và mã tham chiếu ngân hàng không phải lúc nào cùng phạm vi duy nhất. Giữ provenance để biết bản ghi đến từ đâu, rồi áp quy tắc hợp nhất đã được kiểm thử.

Chống trùng dữ liệu còn phải đi cùng chống trùng chứng từ. Nếu bản ghi nguồn đã tồn tại nhưng tác vụ tạo phiếu thu được chạy lại sau timeout, phần mềm vẫn có thể sinh thêm nghiệp vụ. Kiểm tra cả hai lớp và ràng buộc cạnh tranh, không chỉ một câu lệnh if trước insert.

Phân bổ công nợ theo số tiền làm khớp nhầm

Hai khách có cùng tổng nợ hoặc một khách có nhiều hóa đơn đồng giá rất phổ biến. Rule chọn chứng từ gần nhất cùng số tiền có thể tạo tỷ lệ khớp nhìn cao nhưng sai đối tượng. Triệu chứng thường xuất hiện sau khi khách báo đã trả mà hệ thống vẫn nhắc nợ.

Kiểm tra tham chiếu, khách hàng, chủ thể nhận và trạng thái khoản phải thu. Quan hệ thanh toán gộp hoặc nhiều lần cần bảng phân bổ riêng. Tổng phân bổ không được vượt tiền nhận hoặc bị sử dụng lại cho hai nhóm công nợ.

Khoản chưa đủ căn cứ nên ở danh sách chờ xác minh, có người nhận việc. Khi sửa ghép tay, lưu trước/sau và lý do. Không điều chỉnh số tiền ngân hàng để làm công nợ khớp, vì thao tác đó phá hủy chính bằng chứng cần dùng để tìm lỗi.

HTTP thành công bị hiểu thành nghiệp vụ đã hoàn tất

Response HTTP chỉ là một lớp. Body có thể mô tả lỗi nghiệp vụ, kết quả chưa rõ hoặc trạng thái đang xử lý. Adapter cần kiểm tra cấu trúc và mã kết quả theo tài liệu; không biến mọi response đọc được thành thành công hoặc mọi response lỗi parse thành danh sách rỗng.

Tài liệu Pay2S danh sách ngân hàng ghi endpoint danh mục cũ trả 404 trong lần kiểm tra được công bố. Nếu ứng dụng biến lỗi đó thành “không có ngân hàng”, người dùng sẽ chẩn đoán sai. Cần bảo tồn lỗi nguồn và phân biệt danh mục hỗ trợ với danh sách tài khoản đã liên kết.

Ở chiều gửi sang kế toán, timeout có thể xảy ra sau khi chứng từ đã được tạo. Giữ định danh nghiệp vụ và tra kết quả trước khi gửi lại. Một retry dùng mã mới có thể làm cùng khoản tiền tạo hai phiếu thu trong khi log mạng chỉ ghi một lỗi.

Lỗi bị nuốt hoặc retry vô hạn khiến dữ liệu mắc kẹt

Khối catch chỉ ghi “failed” rồi bỏ qua không cho biết giao dịch nào cần phục hồi. Retry mọi lỗi cũng không hợp lý: sai mapping hoặc kỳ khóa thường cần con người, còn lỗi mạng tạm thời có thể thử lại có giãn cách. Phân loại nguyên nhân để chọn hành động.

Ví dụ log dưới đây là cấu trúc giả định của adapter, dùng định danh an toàn và lý do có thể giao việc:

{
  "event": "reconciliation.blocked",
  "reason": "ERP_PERIOD_LOCKED",
  "source_ref": "DEMO_TX_018",
  "erp_document_ref": null,
  "retry_policy": "manual_review"
}

Danh sách lỗi cần số tiền ảnh hưởng, tuổi xử lý và đầu mối. Theo dõi thêm thời điểm đồng bộ cuối của từng tài khoản. Bài calls, log và lỗi API Pay2S hỗ trợ lớp kết nối; adapter kế toán cần quan sát riêng cho mapping và chứng từ.

Sửa dữ liệu rồi chạy lại theo phạm vi kiểm soát

Trước khi replay, xác định những bản ghi đã lưu, đã phân bổ và đã tạo chứng từ. Một lô lỗi giữa chừng có thể chỉ thiếu bước cuối, không phải chưa xử lý gì. Chạy lại toàn bộ tác động mà không phân biệt trạng thái sẽ làm lỗi lan rộng.

Giữ bản dữ liệu gốc và phiên bản mapping. Sửa rule trên staging hoặc chế độ đánh giá, so kết quả trước/sau và để người phụ trách nghiệp vụ duyệt các thay đổi. Khi dữ liệu đã ghi sổ, cách đảo hay điều chỉnh phải theo quy trình của phần mềm và doanh nghiệp.

Nếu dự án chưa tách được các lớp này, đọc phạm vi API ngân hàng để xác định lại đầu nguồn, rồi mô tả riêng staging, phân bổ và ghi sổ. Cần biết đang sửa bước nào trước khi bấm chạy lại.

Bộ thử nên tái hiện chính các lỗi đã gặp

Tạo fixture cho sai phạm vi, tài khoản chưa mapping, thời gian sát ngày, dữ liệu tiền bất thường, thông báo trùng và trả gộp. Thử thêm ERP timeout sau khi tạo chứng từ, kỳ khóa và hai worker đồng thời. Mỗi test cần kiểm tra kết quả nghiệp vụ cuối, không chỉ response.

Đối chiếu theo định danh và tổng phân bổ, đồng thời xác nhận bản ghi chưa rõ còn ở hàng đợi. Một test có giá trị phải chứng minh không tạo sai phiếu thu hoặc không mất khoản tiền, thay vì chỉ xác nhận hàm đã được gọi.

Khi có sự cố mới, bổ sung trường hợp đó vào bộ hồi quy sau khi hiểu nguyên nhân. Dần dần, những lỗi từng tốn nhiều giờ tra cứu sẽ có dấu hiệu và đường xử lý rõ. Mục tiêu là hệ thống báo đúng điều chưa biết, để kế toán cùng kỹ thuật sửa được mà không phải đoán từ một tổng tiền lệch.