Tài khoản ngân hàng

Tài khoản ngân hàng của công ty: danh sách, tạo, cập nhật, lưu trữ, xem số tài khoản (có xác thực lại).

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/accounts/{id}/recommendations	Gợi ý tăng độ phủ cho tài khoản	account.read	read	Scalar
GET	/v1/bank-accounts	Danh sách tài khoản ngân hàng	account.read	read	Scalar
POST	/v1/bank-accounts	Thêm tài khoản ngân hàng	account.create	write	Scalar
GET	/v1/bank-accounts/{id}	Chi tiết tài khoản ngân hàng	account.read	read	Scalar
PATCH	/v1/bank-accounts/{id}	Cập nhật tài khoản ngân hàng	account.update	write	Scalar
POST	/v1/bank-accounts/{id}:archive	Lưu trữ tài khoản ngân hàng	account.archive	write	Scalar
POST	/v1/bank-accounts/{id}:reveal	Xem số tài khoản đầy đủ	account.reveal	write	Scalar

Chi tiết endpoint

GET /v1/accounts/{id}/recommendations

Gợi ý tăng độ phủ cho tài khoản

Dựa trên các kênh đang nhận tin của tài khoản. Tài khoản chỉ có iPhone Shortcut (tin tạm tính, không có chữ ký thiết bị) → gợi ý chuyển tiếp email và sao kê hằng ngày; automation parse_error → gợi ý sửa từ khoá. Chỉ gợi ý, không đổi dữ liệu.

Quyền: account.read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách. — CoverageRecommendationList, 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/accounts/$ID/recommendations" \
  -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/accounts/{id}/recommendations", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import list_account_recommendations

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

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

GET /v1/bank-accounts

Danh sách tài khoản ngân hàng

Trả các tài khoản trong phạm vi của thông tin xác thực, phân trang theo con trỏ. company_id giới hạn một công ty.

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

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách tài khoản. — BankAccountList, 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.
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
state	query	Không	string	—
bank_code	query	Không	string	Lọc theo mã ngân hàng.
expand	query	Không	string	Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: balance.

curl

curl -sS -X GET "https://api.dongtien.pro/v1/bank-accounts" \
  -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");

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import list_bank_accounts

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

MCP

Công cụ list_bank_accounts, scope accounts:read.

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

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

POST /v1/bank-accounts

Thêm tài khoản ngân hàng

Bắt buộc Idempotency-Key. Cùng ngân hàng + số tài khoản đã có trong tổ chức trả 409 conflict.

Quyền: account.create Idempotency-Key: bắt buộc

• Nhóm tốc độ: write
• Nội dung yêu cầu: CreateBankAccount (application/json, bắt buộc)
• Phản hồi thành công 201: Đã tạo. — BankAccount, application/json
• Mã lỗi riêng của endpoint: idempotency_key_required, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/bank-accounts" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "bank_code": "ACB",
  "account_number": "123456784521",
  "type": "business"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/bank-accounts", {
  params: {
    header: { "idempotency-key": crypto.randomUUID() },
  },
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "bank_code": "ACB",
    "account_number": "123456784521",
    "type": "business"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import create_bank_account
from dongtien_api.models import CreateBankAccount

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_bank_account.sync(
        client=dt.client,
        body=CreateBankAccount.from_dict({
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "bank_code": "ACB",
            "account_number": "123456784521",
            "type": "business",
        }),
    )

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

GET /v1/bank-accounts/{id}

Chi tiết tài khoản ngân hàng

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

• Nhóm tốc độ: read
• Phản hồi thành công 200: Tài khoản. — BankAccount, 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_…).
expand	query	Không	string	Mở rộng một cấp, phân cách bằng dấu phẩy. Giá trị: balance.

curl

curl -sS -X GET "https://api.dongtien.pro/v1/bank-accounts/$ID" \
  -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}", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import get_bank_account

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

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

PATCH /v1/bank-accounts/{id}

Cập nhật tài khoản ngân hàng

Không đổi được số tài khoản; muốn đổi hãy thêm tài khoản mới và lưu trữ tài khoản cũ.

Quyền: account.update Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: UpdateBankAccount (application/json, bắt buộc)
• Phản hồi thành công 200: Tài khoản sau cập nhật. — BankAccount, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

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_…).
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X PATCH "https://api.dongtien.pro/v1/bank-accounts/$ID" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "business",
  "state": "active"
}'

TypeScript

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

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

const { data } = await dt.PATCH("/v1/bank-accounts/{id}", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "type": "business",
    "state": "active"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import update_bank_account
from dongtien_api.models import UpdateBankAccount

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = update_bank_account.sync(
        id="acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=UpdateBankAccount.from_dict({
            "type": "business",
            "state": "active",
        }),
    )

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

POST /v1/bank-accounts/{id}:archive

Lưu trữ tài khoản ngân hàng

Ngừng nhận giao dịch mới; lịch sử giữ nguyên. Đã lưu trữ rồi trả 409 conflict.

Quyền: account.archive Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Tài khoản đã lưu trữ. — BankAccount, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

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_…).
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/bank-accounts/$ID:archive" \
  -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.POST("/v1/bank-accounts/{id}:archive", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import archive_bank_account

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

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

POST /v1/bank-accounts/{id}:reveal

Xem số tài khoản đầy đủ

Cần xác thực lại gần đây (passkey/TOTP ≤ 15 phút) và được ghi nhật ký kiểm toán mức nhạy cảm. Kết quả không bao giờ được lưu lại cho Idempotency-Key; phản hồi có Cache-Control: no-store.

Quyền: account.reveal Cần xác thực lại gần đây

• Nhóm tốc độ: write
• Phản hồi thành công 200: Số tài khoản đầy đủ, hết hạn sau 5 phút. — RevealedAccountNumber, application/json
• Mã lỗi riêng của endpoint: step_up_required, resource_not_found, conflict

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 POST "https://api.dongtien.pro/v1/bank-accounts/$ID:reveal" \
  -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.POST("/v1/bank-accounts/{id}:reveal", {
  params: {
    path: { "id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.tai_khoan_ngan_hang import reveal_bank_account

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

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

Đối tượng

CoverageRecommendationList

Trường	Kiểu	Bắt buộc	Mô tả
account_id	AccountId	Có	—
channels	object	Có	—
channels.android	integer	Có	—
channels.bank_connection	integer	Có	—
channels.email	integer	Có	—
channels.ios	integer	Có	—
data	CoverageRecommendation[]	Có	—
data[].action	object | null	Có	—
data[].kind	string	Có	Giá trị: email_forward, daily_statement, bank_connection, android_device, fix_ios_keywords.
data[].object	string	Có	Giá trị: coverage_recommendation.
data[].priority	string	Có	Giá trị: high, normal.
data[].reason	string	Có	—
data[].title	string	Có	—
object	string	Có	Giá trị: list.

BankAccountList

Trường	Kiểu	Bắt buộc	Mô tả
data	BankAccount[]	Có	—
data[].account_number_masked	string	Có	Số tài khoản đã che, chỉ lộ 4 số cuối.
data[].archived_at	Timestamp | null	Có	—
data[].balance	object	Không	Chỉ có khi expand=balance.
data[].bank	object	Có	—
data[].company	object	Có	—
data[].created_at	Timestamp	Có	—
data[].currency	string	Có	Giá trị: VND.
data[].holder_name	string | null	Có	—
data[].id	AccountId	Có	—
data[].label	string	Có	Nhãn hiển thị, vd. ACB •••4521.
data[].last4	string	Có	—
data[].object	string	Có	Giá trị: bank_account.
data[].state	string	Có	Giá trị: active, stopped_receiving, archived.
data[].type	string	Có	Giá trị: business, virtual_sub, savings.
data[].va_number	string | null	Có	Số tài khoản định danh (VA) nếu ngân hàng cấp.
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.

CreateBankAccount

Trường	Kiểu	Bắt buộc	Mô tả
account_number	string	Có	Số tài khoản đầy đủ. Chỉ ghi: được mã hoá ngay khi nhận và không bao giờ trả lại ở các route đọc.
bank_code	string	Có	—
company_id	OrgId	Có	—
holder_name	string	Không	—
label	string	Không	—
type	string	Không	Giá trị: business, virtual_sub, savings.
va_number	string	Không	—

BankAccount

Trường	Kiểu	Bắt buộc	Mô tả
account_number_masked	string	Có	Số tài khoản đã che, chỉ lộ 4 số cuối.
archived_at	Timestamp | null	Có	—
balance	object	Không	Chỉ có khi expand=balance.
balance.account_id	AccountId	Có	—
balance.as_of	string	Có	Thời điểm tính của phản hồi này.
balance.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.
balance.difference	integer | null	Có	reported − computed khi có cả hai.
balance.evidence	object	Có	—
balance.object	string	Có	Giá trị: balance.
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.
balance.trust	BalanceChainTrust	Có	Giá trị: consistent, mismatch, gap_suspected, unchecked.
bank	object	Có	—
bank.code	string	Có	Mã ngân hàng trong danh mục (vd. ACB).
bank.name	string	Có	—
company	object	Có	—
company.id	OrgId	Có	—
company.mst	string | null	Có	Mã số thuế của công ty.
created_at	Timestamp	Có	—
currency	string	Có	Giá trị: VND.
holder_name	string | null	Có	—
id	AccountId	Có	—
label	string	Có	Nhãn hiển thị, vd. ACB •••4521.
last4	string	Có	—
object	string	Có	Giá trị: bank_account.
state	string	Có	Giá trị: active, stopped_receiving, archived.
type	string	Có	Giá trị: business, virtual_sub, savings.
va_number	string | null	Có	Số tài khoản định danh (VA) nếu ngân hàng cấp.

UpdateBankAccount

Trường	Kiểu	Bắt buộc	Mô tả
holder_name	string | null	Không	—
label	string	Không	—
state	string	Không	stopped_receiving: ngừng nhận giao dịch mới nhưng giữ lịch sử. Giá trị: active, stopped_receiving.
type	string	Không	Giá trị: business, virtual_sub, savings.

RevealedAccountNumber

Trường	Kiểu	Bắt buộc	Mô tả
account_number	string	Có	—
expires_at	string	Có	Thời điểm hết hạn hiển thị (5 phút sau khi cấp).
id	AccountId	Có	—
object	string	Có	Giá trị: bank_account_secret.

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.