Số dư & đối soát

Tra số dư, sổ cái ví, lịch sử giao dịch và tổng hợp sử dụng để đối soát (chỉ đọc).

📄️ Số dư sản lượng của đơn vị

Số dư ví của đơn vị sở hữu API key, theo từng loại sản lượng: `total_in` tổng đã nhận (cấp + được chia + thu hồi về), `total_out` tổng đã đi ra (rút + chia đi + bị thu hồi), `used` đã dùng, `reserved` đang giữ chỗ cho giao dịch chưa chốt, `balance` còn dùng được (= `total_in` − `total_out` − `used` − `reserved`). Ứng dụng của chi nhánh thấy ví chi nhánh; ứng dụng của đơn vị gốc thấy ví đơn vị gốc.

📄️ Lịch sử giao dịch của ứng dụng

Mặc định (`scope=app`) là giao dịch của CHÍNH ứng dụng đang gọi; `scope=enterprise` gồm mọi ứng dụng của cùng đơn vị (mỗi item có thêm `app_name`, `app_key_id`). Không bao giờ thấy chi nhánh hay đơn vị cha. Lọc thêm `quota_type` (mã loại sản lượng), `product`, `status`, `client_ref`. Mới nhất trước, phân trang bằng cursor (`next_cursor`, tối đa 100 giao dịch mỗi trang). Khoảng `from`–`to` tối đa 31 ngày (mặc định 31 ngày gần nhất). `status`: `SUCCEEDED` (có kết luận, đã trừ) hoặc `FAILED` (lỗi hoặc bị từ chối, không trừ — xem `error_code`). Giao dịch đang xử lý chưa hiện.

📄️ Sổ cái ví của đơn vị

Mọi biến động ví của đơn vị sở hữu API key (không thấy ví đơn vị cha / chi nhánh), mới nhất trước, phân trang bằng cursor (`next_cursor`, tối đa 100 bút toán mỗi trang). `kind`: `GRANT`/`REVOKE` (VTS cấp / rút, `counterparty = { name: 'VTS' }`), `ALLOCATE_IN`/`ALLOCATE_OUT`, `RECLAIM_IN`/`RECLAIM_OUT` (chia / thu hồi với đơn vị khác, `counterparty` là đơn vị bên kia), `DEBIT`/`REFUND` (`transaction_id` là giao dịch tương ứng). `amount` luôn dương — chiều tăng / giảm theo `kind`; `balance_after` là số dư ví ngay sau bút toán. `note` là ghi chú của đơn vị cha khi chia / thu hồi; ghi chú nội bộ của VTS (GRANT / REVOKE) luôn `null`. Lọc `quota_type` (mã), `kind` (nhiều giá trị cách nhau dấu phẩy), `from`–`to` (tối đa 366 ngày, mặc định 366 ngày gần nhất).

📄️ Tổng hợp sử dụng theo ngày / tháng

Gom giao dịch theo kỳ (`group_by=day|month`, tính theo giờ Việt Nam Asia/Ho_Chi_Minh) và loại sản lượng, kèm `totals`. Mặc định `scope=enterprise` (mọi ứng dụng của đơn vị); `scope=app` chỉ ứng dụng đang gọi. `total` là mọi giao dịch đã kết thúc (kể cả bị từ chối / lỗi; giao dịch đang xử lý chưa tính), `charged` số lượt đã trừ, `valid` / `invalid` số giao dịch có kết luận, `failed` = lỗi + bị từ chối. Chỉ trả kỳ có giao dịch. `from`, `to` bắt buộc, tối đa 366 ngày.