Kiểm tra số dư qua API trước khi chạy hàng loạt đơn hàng

Tại sao cần truy vấn số dư trước khi chạy hàng đợi

Chạy hàng loạt đơn hàng mà không kiểm tra số dư mới nhất sẽ dẫn đến việc bị từ chối một phần: những đơn đầu tiên được tạo, còn các đơn sau nhận lỗi thiếu tiền. Tình huống này càng khó xử lý khi gửi song song, dùng nhiều dịch vụ khác nhau và có nhiều tiến trình cùng làm việc với một tài khoản.

Điều quan trọng để chạy không phải là tổng số tiền đã nạp hay số dư kế toán trong trang cá nhân. Cần biết số tiền mà dịch vụ cho phép trừ vào thời điểm tạo đơn hàng mới. Tiền cho các đơn đang hoạt động có thể đã nằm trong phần dự trữ, dù lần trừ cuối cùng chưa được ghi nhận trong lịch sử giao dịch.

Hãy so sánh ngân sách hàng đợi với trường số dư khả dụng, chứ không phải với tổng số tiền trong tài khoản.

Phản hồi của phương thức số dư trông như thế nào

Tên các trường do tài liệu của từng nền tảng quy định, nhưng một hợp đồng thuận tiện cho phương thức số dư thường trả về total, available, reserved, currency và updated_at. Dưới đây là ví dụ về cấu trúc có thể dùng làm tham chiếu khi tích hợp. Đây không phải phản hồi chung cho mọi dịch vụ, mà là ví dụ về một lược đồ dữ liệu dễ hiểu.

Yêu cầu có thể trông như sau:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Phản hồi:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Trong ví dụ này, total là toàn bộ tiền của tài khoản, available là tiền dành cho đơn hàng mới, reserved là số tiền cho các giao dịch đã tạo trước đó. Phép kiểm tra khớp: 125.80 trừ 41.30 bằng 84.50. Trường currency quy định đơn vị tính, còn updated_at giúp hiểu dữ liệu mới đến mức nào.

Cách phân tích available và reserved

Trường available được dùng để quyết định chạy. Nếu hàng đợi có giá 80.00 và available là 84.50, số tiền chỉ đủ với điều kiện API không cộng thêm phí riêng hoặc không tính lại giá vào lúc tạo đơn. Trường reserved không được cộng vào số dư khả dụng: số tiền này đã bị giữ.

reserved có thể bao gồm giá của các đơn ở trạng thái processing, pending hoặc review — tập hợp chính xác phụ thuộc vào quy định của nền tảng. Đôi khi phần dự trữ được giải phóng sau khi hủy, hoàn thành một phần hoặc kiểm tra thủ công. Vì vậy chỉ nên tự tính nó theo danh sách đơn hàng như một bước đối chiếu bổ sung.

• total phù hợp để đối chiếu với lịch sử nạp và trừ tiền;
• available phù hợp để cho phép hàng đợi mới được chạy;
• reserved cho biết bao nhiêu tiền đã bị khóa cho các giao dịch đang hoạt động;
• không thể bỏ qua currency ngay cả khi chỉ làm việc với một tài khoản;
• updated_at hữu ích cho nhật ký và chẩn đoán phản hồi cũ.

Phản hồi chỉ có trường balance dễ xử lý hơn, nhưng có nhược điểm: không thể biết số tiền đó có sẵn ngay hay một phần đã bị giữ cho các đơn khác.

Kiểm tra định dạng số tiền trong tài liệu API

Trong ví dụ, các số tiền được truyền dưới dạng chuỗi: "84.50", chứ không phải số 84.5. Định dạng này giữ nguyên giá trị chính xác mà dịch vụ trả về. Nếu API dùng chuỗi với dấu chấm thập phân, không nên chuyển ngay sang số dấu phẩy động và so sánh bằng float.

Ví dụ, phép tính của bạn có thể cho ra 84.499999 thay vì 84.50 như mong đợi. Ở ranh giới ngân sách, điều này có thể khiến hàng đợi bị bỏ qua nhầm hoặc ngược lại, bị dừng. Với các phép toán trên chuỗi thập phân, hãy dùng kiểu dữ liệu thập phân hỗ trợ độ chính xác của phần lẻ cố định.

Một hợp đồng phổ biến khác là đơn vị tối thiểu dạng số nguyên. Khi đó phản hồi có thể chứa "available_minor": 8450 và "currency": "USD", còn giá đơn hàng là "price_minor": 1250. Trong API như vậy, 8450 nghĩa là 84.50 nếu quy tắc tiền tệ giả định hai vị trí thập phân. Chỉ được chia giá trị cho 100 khi tài liệu quy định rõ điều đó.

Không trộn lẫn tiền tệ và định dạng giá

Trước khi tính hàng đợi, hãy so sánh currency từ số dư với tiền tệ của phương thức giá hoặc phản hồi khi tạo đơn hàng. Nếu số dư trả về một loại tiền tệ còn danh mục dịch vụ trả về loại khác, không thể thay số trực tiếp. Cần dùng phép tính do chính nền tảng cung cấp, hoặc một phương thức quy đổi riêng đã được xác nhận.

Quy đổi trước ở phía bạn thuận tiện cho việc lập kế hoạch, nhưng có nhược điểm: dịch vụ có thể áp dụng tỷ giá, phí hoặc quy tắc làm tròn khác vào lúc trừ tiền. Đáng tin cậy hơn là gửi đơn hàng với các tham số mà API trả về tổng chi phí bằng tiền tệ của số dư, hoặc lấy báo giá ngay trước khi tạo.

Nếu phương thức giá trả về "price": "12.345" còn số dư lưu giá trị với hai chữ số, hãy xác nhận quy tắc làm tròn. Không tự động làm tròn xuống: khoản trừ thực tế có thể cao hơn. Để cho phép hàng đợi chạy, hãy dùng đúng số tiền mà API gọi là tổng chi phí của đơn hàng.

Tính ngân sách hàng đợi trước yêu cầu đầu tiên

Trước khi chạy, hãy tập hợp tất cả đơn và tính chi phí của chúng có tính đến số lượng, dịch vụ đã chọn, khu vực, tùy chọn bổ sung và phí nếu phí được truyền riêng. Không so sánh available với giá cơ bản trong giao diện: trong API, tổng có thể phụ thuộc vào tham số của từng đơn hàng cụ thể.

Giả sử hàng đợi có ba đơn hàng. API tính giá trả về cho chúng 18.40, 27.15 và 31.60 cùng loại tiền tệ ghi trong balance.currency. Ngân sách là 77.15. Nếu balance.available là 84.50, sau khi chạy theo kế hoạch còn lại 7.35. Nếu available là 76.90, không thể chạy toàn bộ hàng đợi.

1. Lấy giá theo tham số thực tế của từng đơn hàng.
2. Cộng các tổng chi phí mà không đổi định dạng và tiền tệ của chúng.
3. So sánh ngân sách với available từ phản hồi số dư mới nhất.
4. Nếu số dư đủ, ghi nhận số tiền làm dự trữ chạy cục bộ.
5. Sau khi tạo mỗi đơn, giảm dự trữ cục bộ theo chi phí đã xác nhận.

Khoản dự phòng giảm rủi ro bị từ chối khi có khoản trừ bổ sung, nhưng có nhược điểm: một phần tiền khả dụng sẽ không được dùng, dù hàng đợi có thể đã chạy hết.

Kiểm tra lần hai ngay trước khi gửi

Số dư lấy được khi chuẩn bị chiến dịch nhanh chóng mất tính thời sự. Trong khoảng thời gian giữa lúc tính và lúc chạy, một nhân viên khác, hệ thống tự động hoặc một đơn đang hoạt động có thể thay đổi available và reserved. Cần truy vấn lại sau khi hình thành hàng đợi và ngay trước đơn đầu tiên.

Quy trình làm việc gồm hai bước: trước tiên lấy giá và ước tính ngân sách, sau đó truy vấn balance một lần nữa. Nếu giá trị available giảm xuống dưới tổng đã tính, không gửi toàn bộ hàng đợi. Giữa lần kiểm tra cuối và lúc chạy, không nên thực hiện các khoản trừ khác từ cùng tài khoản.

Một yêu cầu cho toàn bộ lần chạy giảm tải cho API, nhưng nhược điểm là số dư khả dụng có thể thay đổi trong khi hàng đợi dài vẫn đang được xử lý.

Cách chạy hàng đợi khi thiếu tiền

Nếu available nhỏ hơn ngân sách, đừng gửi tất cả yêu cầu với hy vọng một phần sẽ thành công. Hãy chia hàng đợi thành các gói có chi phí nằm trong hạn mức khả dụng. Trong ví dụ với số dư 76.90, có thể gửi hai đơn đầu với giá 45.55, sau đó dừng lại: đơn thứ ba giá 31.60 cần kiểm tra lại.

Hãy đặt thứ tự đơn hàng khi chia gói một cách rõ ràng. Có thể gửi các đơn ưu tiên trước, hoặc tạo các gói có chi phí gần nhau. Mỗi cách đều có nhược điểm: thứ tự ưu tiên sẽ trì hoãn các mục ít quan trọng hơn, còn sắp xếp theo giá có thể làm sai lệch kế hoạch chiến dịch ban đầu.

• Tạo gói có tổng không vượt quá available hiện tại.
• Tạo các đơn từ gói và lưu mã định danh của chúng.
• Chờ phản hồi hoặc kiểm tra trạng thái giao dịch sau khi hết thời gian chờ.
• Tạm dừng nếu giới hạn API hoặc quy định dịch vụ yêu cầu.
• Truy vấn balance lại trước gói tiếp theo.

Sau mỗi gói, hãy dựa vào phản hồi API mới, chứ không chỉ vào khoản trừ cục bộ từ số dư trước đó. Phép tính cục bộ hữu ích để kiểm soát, nhưng nó không thấy các khoản hoàn, khoản trừ bên ngoài và việc tính lại dự trữ.

Bảo vệ ngân sách khi gửi song song

Khi xử lý tuần tự, chỉ cần giảm hạn mức cục bộ sau khi đơn hàng được xác nhận. Với mô hình song song, hai worker có thể cùng lúc thấy available 84.50 và mỗi bên lên kế hoạch chi 60.00. Cả hai quyết định đều có vẻ hợp lệ riêng lẻ, nhưng cộng lại thì vượt quá số dư khả dụng.

Để bảo vệ, cần một bộ đếm dự trữ cục bộ dùng chung hoặc một hàng đợi được truy cập nguyên tử. Trước khi gửi, worker cố gắng giữ số tiền của đơn hàng trong bộ đếm này. Nếu hạn mức trống không đủ, đơn sẽ chờ kiểm tra số dư lại.

• Hàng đợi tuần tự dễ kiểm soát hơn, nhưng chạy chậm hơn.
• Gửi song song rút ngắn thời gian chạy, nhưng cần khóa ngân sách dùng chung.
• Dự trữ cục bộ giảm xung đột, nhưng có thể bị treo sau khi worker gặp sự cố.
• Dự trữ phía API đáng tin cậy hơn, nhưng không phải nền tảng nào cũng có.

Nếu tiến trình kết thúc trước khi nhận phản hồi, không thể coi ngay dự trữ cục bộ là đã chi hay còn trống. Trước tiên hãy kiểm tra xem đơn hàng đã được tạo chưa, qua mã định danh bên ngoài của nó hoặc bằng phương thức tìm kiếm giao dịch.

Dùng dự trữ API nếu có hỗ trợ

Một số API cho phép tạo dự trữ cho một tập giao dịch hoặc thực hiện đơn hàng theo hai bước: tính giá, khóa số tiền, xác nhận. Trong mô hình này, khoảng thời gian giữa kiểm tra và trừ tiền ngắn hơn, khiến tiến trình khác khó tiêu hết tiền của tài khoản hơn.

Nếu có phương thức như vậy, hãy lưu mã định danh dự trữ, số tiền, tiền tệ, thời hạn hiệu lực và trạng thái của nó. Sau đó truyền mã định danh này khi tạo đơn hàng nếu hợp đồng API yêu cầu. Sau khi hoàn tất hàng đợi, hãy đối chiếu phần chưa dùng và việc gỡ khóa.

Dự trữ API không giải quyết mọi vấn đề: nó có thể có thời hạn ngắn, không bao gồm phí hoặc được giải phóng sau lỗi xác nhận. Dự trữ cục bộ dễ triển khai hơn, nhưng nhược điểm là không bảo vệ khỏi các khoản chi được tạo bên ngoài ứng dụng của bạn.

Phân biệt lỗi số dư với số dư bằng không

Phản hồi mã lỗi, hết thời gian chờ hoặc giới hạn tần suất yêu cầu không có nghĩa là available bằng không. Không tự động thay bằng giá trị gần nhất đã biết nếu một lần chạy lớn phụ thuộc vào nó. Khi không thể lấy số dư mới, cần tạm dừng hàng đợi.

Hãy xử lý riêng việc bị từ chối khi tạo đơn hàng. Nó có thể do thiếu tiền, nhưng cũng có thể do mã dịch vụ sai, số lượng không hợp lệ, giới hạn kênh hoặc lặp lại một giao dịch. Lưu mã và nội dung lỗi cùng với mã định danh bên ngoài của đơn.

• Khi lỗi xác thực, hãy làm mới quyền truy cập rồi mới lặp lại yêu cầu.
• Khi bị giới hạn yêu cầu, hãy chờ theo quy định API.
• Khi hết thời gian chờ tạo đơn, trước tiên hãy kiểm tra xem giao dịch có thực sự xuất hiện chưa.
• Khi lỗi thiếu tiền, hãy dừng gói và truy vấn balance lại.

Không tạo bản trùng sau khi hết thời gian chờ

Hết thời gian chờ nghĩa là client của bạn không nhận được phản hồi, chứ không phải máy chủ chưa xử lý yêu cầu. Gửi lại mà không kiểm tra có thể tạo đơn thứ hai và giữ tiền lần nữa. Điều này đặc biệt nguy hiểm trong hàng đợi có cấu hình tự động thử lại nhiều lần.

Hãy truyền mã định danh đơn hàng bên ngoài duy nhất nếu API hỗ trợ trường client_order_id, external_id hoặc idempotency_key. Lưu nó trước khi gửi yêu cầu. Sau khi hết thời gian chờ, tìm giao dịch theo giá trị này hoặc truy vấn trạng thái theo mã định danh đã nhận trước đó.

Thử lại mà không kiểm tra thì nhanh hơn, nhưng nhược điểm rất rõ: có thể có đơn trùng, dự trữ hai lần và chênh lệch giữa phép tính ngân sách của bạn với các khoản trừ thực tế.

Những gì cần lưu trong nhật ký chạy

Nhật ký giúp khôi phục diễn biến của thao tác hàng loạt và giải thích vì sao một gói cụ thể bị dừng. Với mỗi lần chạy, hãy lưu thời điểm hai lần kiểm tra, total, available, reserved, currency, ngân sách đã tính, kích thước dự trữ cục bộ và danh sách mã định danh bên ngoài của các đơn.

Với mỗi lần thử tạo đơn, hãy ghi lại chi phí, mã phản hồi, mã định danh kỹ thuật của giao dịch và trạng thái cuối cùng. Không đưa thông tin bí mật vào nhật ký: token xác thực, khóa API, toàn bộ header yêu cầu và dữ liệu cá nhân cần được che hoặc loại bỏ trước khi ghi.

Ghi log đầy đủ thuận tiện khi gỡ lỗi, nhưng có nhược điểm: nếu không lọc, dữ liệu truy cập và thông tin khách hàng có thể lọt vào kho lưu trữ.

Kiểm tra quy trình trên một hàng đợi nhỏ

Trước lần chạy lớn, hãy thực hiện một kịch bản ngắn: lấy balance, truy vấn tổng giá, tạo một gói giới hạn, truy vấn balance lần nữa và so sánh thay đổi mong đợi của available và reserved với phản hồi thực tế. Như vậy có thể nhận ra khi nào dịch vụ giữ tiền và khi nào trừ hẳn.

Gói thử nghiệm không đảm bảo hành vi giống nhau dưới tải lớn: giới hạn, tiến trình song song hoặc hạn chế của dịch vụ cụ thể có thể phát sinh. Vì vậy trong hàng đợi lớn, hãy tiếp tục chia lần chạy thành các gói, kiểm tra số dư khả dụng giữa các gói và xử lý riêng từng lần từ chối.