Tham chiếu API

Trang này tóm tắt địa chỉ gốc, phiên bản và các nhóm endpoint của Dòng Tiền Pro API; mỗi nhóm có trang riêng với bảng tham số, ví dụ gọi và mã lỗi.

Địa chỉ gốc và phiên bản

• Địa chỉ gốc (base URL): https://api.dongtien.pro
• Máy chủ khác: https://api.staging.dongtien.pro (Staging (dữ liệu thử))
• Phiên bản API (info.version): 2026-10-19
• Đặc tả: OpenAPI 3.1.0
• Header DongTien-Version: Phiên bản API (YYYY-MM-DD). Bỏ trống: dùng phiên bản ghim theo khoá. Xem Phiên bản API.

Tài liệu tương tác và đặc tả

• Tài liệu tương tác (Scalar): gọi thử với khoá dt_test_…
• Đặc tả OpenAPI (JSON): https://api.dongtien.pro/v1/openapi.json

Xác thực

Tên	Kiểu	Scheme	Định dạng token (bearerFormat)	Mô tả
bearerAuth	http	bearer	dt_live_… | dt_test_…	Khoá API dt_live_… (dữ liệu thật) hoặc dt_test_… (dữ liệu thử), hoặc token OAuth của CLI/MCP.

Gửi khoá trong header Authorization: Bearer $DT_API_KEY. Cách lấy khoá và các loại khoá: xem Xác thực.

Nhóm endpoint

Nhóm	Số endpoint	Mô tả
Tài khoản ngân hàng	7	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).
Số dư	2	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).
Giao dịch	14	Giao dịch ngân hàng: danh sách, chi tiết, nguồn gốc, nhật ký, đồng bộ theo con trỏ và tổng hợp.
Tác vụ	1	Tác vụ bất đồng bộ (nhập, xuất, đồng bộ): theo dõi tiến độ và kết quả.
Chế độ xem	4	Bộ lọc giao dịch đã lưu (riêng tôi, cả công ty, cả firm) và ghim lên bảng điều khiển.
Bảng điều khiển	1	Số liệu tổng quan từ sổ giao dịch: số dư, vào/ra hôm nay, việc cần xử lý.
Thời gian thực	3	Vé một lần và luồng sự kiện (WebSocket/SSE) cho giao diện: giao dịch mới, nâng cấp, gộp, cách ly.
Hệ thống	2	Thông tin phiên bản và tài liệu API.
Danh tính	9	Người gọi là ai, đang làm việc ở tổ chức nào, tra cứu MST, tiến độ làm quen và phiên đăng nhập.
Tổ chức	15	Gốc tổ chức và công ty (MST), mẫu công ty mới, bàn giao, xoá công ty có hai người duyệt, đồng bộ hồ sơ từ nguồn MST.
Thành viên	11	Thành viên, vai trò, lời mời và quyền truy cập chéo giữa hãng kế toán và khách hàng (access grants).
Bảo mật	2	Chính sách bảo mật của tổ chức: 2FA, dải IP quản trị, thời lượng phiên, tự duyệt.
Khoá API	7	Khoá API: tạo, xoay, thu hồi, gia hạn và xem các lần gọi gần đây (không bao giờ hiện lại khoá).
Nhật ký kiểm toán	3	Chuỗi nhật ký kiểm toán chỉ-thêm, tra cứu và xuất CSV.
Phê duyệt	3	Hàng chờ duyệt hai người (maker–checker) và độ sẵn sàng người duyệt của công ty.
Thiết bị	22	Thiết bị chuyển tiếp tin (Android, iOS Shortcuts): mã ghép, trạng thái, lệnh kiểm tra, nhật ký, quy tắc cảnh báo và bản phát hành ứng dụng.
Thu tiền	15	Yêu cầu thanh toán VietQR, bill POS, việc cần xử lý của thu tiền và mẫu mã đơn riêng của công ty. Không giữ tiền: paid chỉ khi giao dịch đã xác thực.
Nhập sao kê	15	Tải sao kê ngân hàng (Excel, CSV, MT940, CAMT.053): xem trước, kiểm tra số dư đầu/cuối, ánh xạ cột, lịch nhận sao kê. Không có nhập ép: số dư lệch thì dừng.
Dòng tiền	31	Dòng tiền hợp nhất, dự báo 13 tuần, danh mục thu chi, quy tắc phân loại và cảnh báo.
Trí tuệ nhân tạo	15	Cài đặt AI tự chủ theo tổ chức, kết nối BYOK, mô hình, ngân sách và phân loại giao dịch.
Tích hợp	46	Tích hợp kênh ngoài (Lark, Telegram, Slack, Discord, Google Sheets, Lark Base, WooCommerce, Haravan, Shopify) và quy tắc định tuyến sự kiện.
Gói & sử dụng	12	Gói dịch vụ, đo lường giao dịch, thanh quota, trần chi tiêu, hoá đơn và nạp credit dịch vụ.
Đối soát	116	Đề nghị phân bổ giao dịch vào công nợ, gợi ý khớp và quy tắc đối soát; duyệt theo chính sách người lập và người duyệt.
Hoá đơn	7	Kết nối hoá đơn, đồng bộ công nợ và theo dõi ghi ngược các phân bổ đã duyệt.
Đối tác	17	Đối tác thanh toán, khoản thu dự kiến và công việc theo dõi công nợ.
Thông báo	15	Cài đặt thông báo cá nhân và quy tắc định tuyến của tổ chức, push token, Web Push, liên kết Zalo, hộp thư trong app và widget.
Bảo mật sinh trắc	4	Khoá sinh trắc trên thiết bị (Secure Enclave, Android Keystore) và challenge ký để duyệt lệnh trên ứng dụng di động.

Nhóm tốc độ

Mỗi endpoint thuộc một nhóm tốc độ; hạn mức và cách xử lý 429 nằm ở Giới hạn tốc độ.

Nhóm tốc độ	Số endpoint
collect	2
export	11
read	166
replay	6
write	214

Mã lỗi chung

Hầu hết endpoint có thể trả các mã lỗi dưới đây (xác thực, quyền, kiểm tra dữ liệu, giới hạn tốc độ, lỗi hệ thống); trang từng nhóm chỉ liệt kê thêm mã riêng của endpoint.

HTTP	Mã lỗi	Ý nghĩa	Thử lại
401	unauthenticated	Cần đăng nhập	Không
401	invalid_api_key	Khoá API không hợp lệ	Không
401	api_key_expired	Khoá API đã hết hạn	Không
401	api_key_revoked	Khoá API đã bị thu hồi	Không
403	ip_not_allowed	Địa chỉ IP không được phép với khoá này	Không
403	permission_denied	Không đủ quyền	Không
403	scope_not_allowed	Phạm vi khoá không cho phép route này	Không
403	account_scope_denied	Tài khoản ngân hàng nằm ngoài phạm vi khoá	Không
400	bad_request	Yêu cầu không hợp lệ	Không
400	invalid_json	Nội dung JSON sai cú pháp	Không
422	validation_failed	Dữ liệu không hợp lệ	Không
400	unsupported_version	Phiên bản API không được hỗ trợ	Không
429	rate_limited	Gọi quá nhanh	Có
503	service_unavailable	Dịch vụ tạm thời không khả dụng	Có
500	internal_error	Lỗi hệ thống	Có

Tham chiếu chung

• Lỗi RFC 9457: cấu trúc application/problem+json
• Danh mục mã lỗi: mọi mã code kèm cách xử lý
• Phân trang và Idempotency

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.