Số dư

Số dư báo cáo (từ ngân hàng/sao kê) tách khỏi số dư tính toán (từ giao dịch).

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/balances	Số dư của các tài khoản	account.read	read	Scalar
GET	/v1/bank-accounts/{id}/balance	Số dư của một tài khoản	account.read	read	Scalar

Chi tiết endpoint

GET /v1/balances

Số dư của các tài khoản

Số dư từng tài khoản trong phạm vi, phân trang theo con trỏ.

Quyền: account.read Scope: balances:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách số dư. — BalanceList, application/json
• Mã lỗi riêng của endpoint: invalid_cursor

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
limit	query	Không	integer	Số phần tử mỗi trang (1–100, mặc định 20).
cursor	query	Không	Cursor	Con trỏ phân trang mờ (cur_…) lấy từ next_cursor; không tự tạo hay sửa.

curl

curl -sS -X GET "https://api.dongtien.pro/v1/balances" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/balances");

Python

import os

from dongtien import DongTien
from dongtien_api.api.so_du import list_balances

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_balances.sync(client=dt.client)

MCP

Công cụ get_balances, scope balances:read.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_balances",
    "arguments": {}
  }
}

Mở trong tài liệu tương tác

GET /v1/bank-accounts/{id}/balance

Số dư của một tài khoản

Quyền: account.read Scope: balances:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Số dư. — Balance, application/json
• Mã lỗi riêng của endpoint: resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	AccountId	Mã tài khoản ngân hàng (acc_…).

curl

curl -sS -X GET "https://api.dongtien.pro/v1/bank-accounts/$ID/balance" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/bank-accounts/{id}/balance", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.so_du import get_bank_account_balance

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = get_bank_account_balance.sync(id="acc_0f5k2m9q4h7t3n8r6v1w0x5yz0", client=dt.client)

Mở trong tài liệu tương tác

Đối tượng

BalanceList

Trường	Kiểu	Bắt buộc	Mô tả
data	Balance[]	Có	—
data[].account_id	AccountId	Có	—
data[].as_of	string	Có	Thời điểm tính của phản hồi này.
data[].computed	object | null	Có	Số dư tính từ mốc neo + giao dịch đã xác thực; null nếu chưa có mốc neo.
data[].difference	integer | null	Có	reported − computed khi có cả hai.
data[].evidence	object	Có	—
data[].object	string	Có	Giá trị: balance.
data[].reported	object | null	Có	Số dư do ngân hàng/sao kê báo cáo; null nếu chưa nhận được.
data[].trust	BalanceChainTrust	Có	Giá trị: consistent, mismatch, gap_suspected, unchecked.
has_more	boolean	Có	—
next_cursor	string | null	Có	Con trỏ trang kế; null khi hết dữ liệu.
object	string	Có	Giá trị: list.

Balance

Trường	Kiểu	Bắt buộc	Mô tả
account_id	AccountId	Có	—
as_of	string	Có	Thời điểm tính của phản hồi này.
computed	object | null	Có	Số dư tính từ mốc neo + giao dịch đã xác thực; null nếu chưa có mốc neo.
computed.amount	Vnd	Có	—
computed.as_of	Timestamp	Có	—
difference	integer | null	Có	reported − computed khi có cả hai.
evidence	object	Có	—
evidence.anchor_as_of	Timestamp | null	Có	—
evidence.anchor_state	string | null	Có	Giá trị: ok, mismatch, gap_suspected.
evidence.transactions_since_anchor	integer	Có	—
object	string	Có	Giá trị: balance.
reported	object | null	Có	Số dư do ngân hàng/sao kê báo cáo; null nếu chưa nhận được.
reported.amount	Vnd	Có	—
reported.as_of	Timestamp	Có	—
reported.source	string	Có	Nguồn của số dư báo cáo. Giá trị: openapi, statement, sms_verified, sms_provisional, computed.
trust	BalanceChainTrust	Có	Giá trị: consistent, mismatch, gap_suspected, unchecked.

Lưu ý về từ "đã xác thực": đây là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.