Kết nối API ngân hàng với Google Sheets: đồng bộ dữ liệu có kiểm soát

Kết nối API ngân hàng với Google Sheets giúp đội vận hành có bảng giao dịch cập nhật mà không phải nhập từng dòng sao kê. Tuy nhiên, một kết nối đáng tin cậy phải làm được nhiều hơn việc thêm hàng: xác thực nguồn gửi, chống trùng, phát hiện bản ghi thiếu và giữ dữ liệu gốc để đối chiếu.

Một phương án triển khai là nhận dữ liệu ngân hàng qua Pay2S, kiểm tra và lưu ở backend, rồi dùng Google Sheets API cho lớp báo cáo. Luồng này cần đội kỹ thuật xây dựng và nghiệm thu; sự tồn tại của API không đồng nghĩa đã có connector Sheets cài sẵn. Trên hoadontudong.com.vn, phần hướng dẫn dưới đây tập trung vào kiến trúc và các điểm dễ mất hoặc ghi trùng dữ liệu.

Kết nối API ngân hàng với Google Sheets theo kiến trúc nào?

Luồng đề xuất gồm ba lớp. Pay2S cung cấp dữ liệu giao dịch theo kết nối được cấp. Backend nhận và xác thực, lưu bản ghi bền vững. Một worker ghi dữ liệu đã chuẩn hóa vào Google Sheets. Bảng tính là lớp quan sát và phân tích, còn backend giữ định danh cùng trạng thái đồng bộ.

Tách worker giúp thời gian phản hồi nguồn gửi không phụ thuộc hoàn toàn vào Google. Nếu Sheets tạm lỗi hoặc đạt quota, giao dịch vẫn đã được lưu để xử lý tiếp. Ngược lại, nếu endpoint chỉ ghi Sheets rồi trả thành công, phản hồi bị mất có thể khiến lần gửi lại thêm một hàng trùng.

Người triển khai nên hiểu phạm vi BankHub và API ngân hàng Pay2S trước khi chọn luồng dữ liệu. Nhận mọi giao dịch tiền vào, ra khác với nhận kết quả một đơn thanh toán; bảng theo dõi sao kê không nên dùng IPN đơn hàng làm nguồn thay thế toàn bộ.

Chuẩn bị quyền và xác nhận dữ liệu được phép sử dụng

Trước tiên, xác nhận tài khoản ngân hàng đã liên kết, loại kết nối và quyền của doanh nghiệp. Ghi rõ cần lấy khoản tiền vào, tiền ra hay cả hai. Tài liệu webhook Pay2S mô tả lựa chọn IN, OUT hoặc ALL; cấu hình thực tế phải phù hợp với mục đích báo cáo và người được xem bảng.

Phía Google cần bật quyền truy cập API phù hợp và xác định tài khoản thực thi. Có thể dùng cơ chế OAuth hoặc service account theo kiến trúc tổ chức; người triển khai phải cấp quyền cho đúng bảng và giữ thông tin xác thực trong môi trường backend. Không đặt Secret Key ngân hàng hay token Google vào một ô chia sẻ.

Hãy tạo bảng thử độc lập trước khi dùng dữ liệu thật. Chỉ cấp quyền chỉnh sửa cho người cần thiết, tách người xem báo cáo với người quản lý cấu hình. Khi nhân viên đổi vai trò hoặc nghỉ việc, quyền bảng và quyền hệ thống đều phải được rà lại, không chỉ xóa một đường link.

Thiết kế bảng giao dịch để dữ liệu không bị mất nghĩa

Nên có tab dữ liệu gốc và tab báo cáo riêng. Người dùng lọc, làm công thức hoặc biểu đồ ở tab báo cáo; không sửa số tiền của tab gốc để làm tổng khớp. Nếu cần phân loại, lưu nhãn ở vùng riêng hoặc cơ sở dữ liệu, kèm người sửa và thời điểm.

Nhận webhook: xác thực trước, ghi bền vững trước khi xác nhận

Tài liệu Pay2S webhook ngân hàng mô tả token gửi qua Authorization và cấu hình gắn với tài khoản liên kết. Backend cần kiểm tra đúng cơ chế này, giới hạn kích thước dữ liệu và ánh xạ trường theo tài liệu của luồng đang dùng. Không sao chép cơ chế chữ ký IPN sang webhook ngân hàng rồi coi là tương đương.

Sau xác thực, kiểm tra khóa nguồn đã tồn tại hay chưa. Nếu bản ghi mới, lưu giao dịch và nhiệm vụ đồng bộ Sheets trong cùng giao dịch cơ sở dữ liệu khi kiến trúc cho phép. Chỉ phản hồi thành công sau khi đã lưu đủ để phục hồi. Nếu không lưu được, trả lỗi phù hợp để nguồn gửi có cơ hội thử lại.

Đoạn dưới là mã giả mô tả thứ tự, không phải endpoint hoặc schema Pay2S có thể sao chép chạy ngay:

Nhận thông báo → xác thực nguồn → chuẩn hóa giao dịch
Nếu khóa nguồn chưa tồn tại:
    lưu giao dịch và tác vụ đồng bộ trong database
Xác nhận đã nhận sau khi lưu thành công
Worker đọc tác vụ → ghi vùng dữ liệu Sheets → lưu kết quả

Chi tiết nguồn dữ liệu có thể đối chiếu tại hướng dẫn webhook biến động số dư. Phần lưu và chạy worker thuộc ứng dụng của doanh nghiệp.

Chọn cách ghi Sheets: thêm hàng hay cập nhật vị trí ổn định?

Google Sheets API có phương thức append để thêm dữ liệu sau bảng được nhận diện trong vùng chỉ định. Cách này thuận tiện khi ghi nối tiếp, nhưng không tự cung cấp khóa giao dịch duy nhất. Nếu request đã ghi thành công mà response bị mất, việc gọi append lại có thể tạo hàng thứ hai.

Với append, backend cần lưu trạng thái và có bước kiểm tra khóa nguồn khi kết quả request chưa rõ. Không được kết luận “không có response” đồng nghĩa “chưa ghi”. Nếu yêu cầu chống trùng chặt hơn, có thể quản lý ánh xạ giao dịch sang vị trí hàng cố định và cập nhật lại cùng vùng khi thử lại.

Cách hàng cố định yêu cầu vùng gốc được bảo vệ khỏi thao tác chèn, xóa hoặc sắp xếp làm thay đổi vị trí. Báo cáo nên đọc từ vùng gốc sang tab khác. Lựa chọn phụ thuộc quy mô và cách người dùng làm việc; cần nghiệm thu cả trường hợp mất phản hồi, không chỉ trường hợp request trả thành công.

Giữ đúng kiểu số, văn bản và nội dung chuyển khoản

Số tài khoản, mã giao dịch và mã đơn nên được xử lý như định danh văn bản; không chuyển thành số làm mất số không đầu hoặc sai ký tự. Số tiền cần được chuẩn hóa trước khi ghi và có quy ước đơn vị. Không bỏ dấu phân cách theo cảm tính rồi vô tình làm tăng hoặc giảm giá trị.

Với dữ liệu khách có thể nhập như nội dung chuyển khoản, cần tránh để bảng tính diễn giải thành công thức. Google có tùy chọn cách nhập dữ liệu; dùng chế độ phù hợp như RAW cho vùng dữ liệu gốc khi muốn giữ giá trị văn bản. Định dạng hiển thị và tính toán số tiền nên được cấu hình riêng.

Múi giờ cũng cần rõ ràng. Giữ timestamp nguồn và hiển thị theo múi giờ vận hành đã thống nhất. Một giao dịch cuối ngày có thể rơi sang ngày khác nếu hệ thống tự chuyển giờ; đây là nguyên nhân khiến báo cáo ngày lệch dù số tiền và số bản ghi đều đủ.

Quota, hàng đợi và cách thử lại khi Google tạm lỗi

Google áp dụng quota theo phút cho đọc và ghi Sheets API. Khi vượt giới hạn, ứng dụng có thể nhận HTTP 429 và cần thử lại có giãn cách. Vì quota còn phụ thuộc dự án và tài khoản, nên kiểm tra trong Google Cloud cùng tài liệu chính thức trước khi đặt nhịp đồng bộ.

Worker có thể gom nhiều giao dịch thành một lần ghi để giảm số request. Tuy nhiên, mỗi lô cần biết những giao dịch nào đã hoàn tất và những giao dịch nào đang chờ. Không xóa tác vụ chỉ vì đã gửi request; chỉ chuyển trạng thái sau khi kết quả được xác định hoặc đã đối soát lại trường hợp không rõ.

Đặt giới hạn số lần thử và chuyển lỗi kéo dài sang danh sách cần người kiểm tra. Một cột “lần đồng bộ cuối” trên dashboard giúp người dùng biết bảng đang mới hay cũ. Nếu không có chỉ báo này, người xem dễ dùng một bảng đã ngừng cập nhật để chốt số liệu.

Đối soát bổ sung và xử lý hàng bị sửa tay

Webhook hỗ trợ cập nhật kịp thời, nhưng vẫn cần kiểm tra định kỳ với nguồn giao dịch được phép truy vấn hoặc sao kê phù hợp. Đối chiếu theo khóa và số tiền, không chỉ tổng cộng. Hai lỗi thiếu và thừa cùng giá trị có thể làm tổng vẫn khớp trong khi dữ liệu sai.

Nếu một hàng gốc bị xóa hoặc sửa, hệ thống cần phát hiện và khôi phục theo chính sách đã thống nhất. Không để thao tác sửa bảng âm thầm làm thay đổi bản ghi giao dịch trong backend. Ngược lại, nếu bảng chỉ là bản sao báo cáo, có thể tái tạo từ nguồn đã lưu sau khi thông báo cho người dùng.

Lưu log có thể kiểm tra nhưng che thông tin nhạy cảm. Khi cần theo dõi lỗi kết nối Pay2S, tham khảo cách theo dõi calls, log và lỗi API. Log nên trả lời được giao dịch nào bị ảnh hưởng và bước nào cần chạy lại.

Nghiệm thu trước khi giao bảng cho kế toán hoặc vận hành

Thử khoản tiền vào, tiền ra, giao dịch cùng số tiền, dữ liệu tiếng Việt và mã có số không đầu. Gửi lại cùng thông báo, mô phỏng lỗi Sheets, mất response và tác vụ worker chạy đồng thời. Kết quả cần giữ đủ bản ghi, không thêm trùng và không tự đổi giá trị.

Kiểm tra quyền bằng tài khoản người xem thật, gồm khả năng tải, chia sẻ và xem dữ liệu gốc. Đội kỹ thuật nên rà cách quản lý xác thực API Pay2S, đồng thời bàn giao đầu mối xử lý khi token hoặc quyền Google thay đổi.

Bảng giao dịch chỉ đáng tin khi người xem biết dữ liệu đã đủ đến đâu, được kiểm tra thế nào và lần đồng bộ gần nhất là lúc nào. Hãy triển khai từ một tài khoản thử, nghiệm thu chống trùng và phục hồi trước khi mở rộng. Khi lượng dữ liệu hoặc yêu cầu kiểm soát tăng, giữ backend làm nền dữ liệu và dùng Sheets cho báo cáo sẽ dễ quản trị hơn.