Giao dịch

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.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/transaction-exports/{id}/file	Tải tệp xuất giao dịch	tx.read	export	Scalar
GET	/v1/transactions	Danh sách giao dịch	tx.read	read	Scalar
GET	/v1/transactions/summary	Tổng hợp giao dịch	tx.read	read	Scalar
GET	/v1/transactions/sync	Đồng bộ thay đổi giao dịch	tx.read	read	Scalar
GET	/v1/transactions/{id}	Chi tiết giao dịch	tx.read	read	Scalar
GET	/v1/transactions/{id}/events	Nhật ký của giao dịch	tx.read	read	Scalar
GET	/v1/transactions/{id}/sources	Nguồn gốc của giao dịch	tx.read_raw	read	Scalar
POST	/v1/transactions/{id}:decide-manual-verify	Duyệt hoặc từ chối xác nhận thủ công	tx.verify_manual.approve	write	Scalar
POST	/v1/transactions/{id}:manual-verify	Đề nghị xác nhận thủ công	tx.verify_manual.propose	write	Scalar
POST	/v1/transactions/{id}:reject-quarantine	Loại bỏ giao dịch cách ly	tx.release_quarantine	write	Scalar
POST	/v1/transactions/{id}:release-quarantine	Gỡ cách ly giao dịch	tx.release_quarantine	write	Scalar
POST	/v1/transactions/{id}:unmerge	Tách giao dịch đã gộp	tx.unmerge	write	Scalar
POST	/v1/transactions:bulk-note	Ghi chú / gắn thẻ hàng loạt	tx.annotate	write	Scalar
POST	/v1/transactions:export	Xuất giao dịch	tx.read	export	Scalar

Chi tiết endpoint

GET /v1/transaction-exports/{id}/file

Tải tệp xuất giao dịch

Chỉ người đã tạo lệnh xuất (hoặc cùng quyền xem trong công ty) tải được. Hết hạn sau 24 giờ trả 404. Mỗi lần tải được ghi nhật ký kiểm toán.

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: export
• Phản hồi thành công 200: Tệp CSV, JSON hoặc XLSX. — TransactionExportFile, application/json; string (binary), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; string, text/csv
• 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ó	JobId	Mã tác vụ bất đồng bộ (job_…).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import download_transaction_export

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

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

GET /v1/transactions

Danh sách giao dịch

Mới nhất trước. Mặc định không gồm giao dịch cách ly và giao dịch đã gộp. Để biết tiền đã về hãy dùng status=confirmed hoặc lắng nghe sự kiện transaction.confirmed.

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách giao dịch. — TransactionList, 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.
status	query	Không	TransactionStatus	confirmed: đã xác thực bởi nguồn đáng tin (tiền về). provisional: tạm tính, chưa đủ bằng chứng — không coi là tiền về.
since	query	Không	Timestamp | Date	Từ thời điểm (gồm) theo occurred_at.
until	query	Không	Timestamp | Date	Đến thời điểm (không gồm) theo occurred_at.
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
account_id	query	Không	AccountId	Mã tài khoản ngân hàng (acc_…).
direction	query	Không	string	—
memo	query	Không	string	Mã nội dung chuyển khoản DTP… (khớp chính xác, không phân biệt hoa/thường).
q	query	Không	string	Tìm trong nội dung/đối tác, không phân biệt dấu.
include_quarantined	query	Không	string	Gồm giao dịch bị cách ly (mặc định không).
include_merged	query	Không	string	Gồm giao dịch đã bị gộp vào giao dịch khác (mặc định không).
preset	query	Không	TransactionListPreset	Bộ lọc nhanh: all Tất cả · needs_action Cần xử lý (tạm tính >24 giờ hoặc đã xác thực nhưng chưa đối soát) · in_today Vào hôm nay (tiền vào từ 00:00 giờ Việt Nam) · provisional_24h Tạm tính >24 giờ · unreconciled Chưa đối soát · quarantined Cách ly (liệt kê cả giao dịch cách ly dù mặc định bị ẩn).
bank	query	Không	string	Mã ngân hàng (ACB, VCB…), không phân biệt hoa/thường.
source	query	Không	string	Chỉ giao dịch có ít nhất một nguồn đến từ kênh này.
verification	query	Không	string	Mức xác thực: provisional tạm tính, verified đã xác thực. Không dùng cùng status khác nghĩa.
amount_min	query	Không	integer | null	Số tiền tối thiểu (gồm), VND.
amount_max	query	Không	integer | null	Số tiền tối đa (gồm), VND; phải ≥ amount_min.
sort	query	Không	TransactionListSort	Thứ tự danh sách (mặc định occurred_at_desc, mới nhất trước). Con trỏ gắn với thứ tự: dùng con trỏ của thứ tự khác trả 400 invalid_cursor.

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import list_transactions

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

dtp

Giao dịch từ đầu tháng của một tài khoản, dạng NDJSON.

dtp tx list --since 2026-10-01 --account acc_0f5k2m9q4h7t3n8r6v1w0x5yz0 --json

MCP

Công cụ list_transactions, scope transactions:read.

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

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

GET /v1/transactions/summary

Tổng hợp giao dịch

Số lượng theo bộ lọc nhanh và tổng vào/ra (kèm phần còn tạm tính). Giao dịch cách ly và đã gộp không nằm trong tổng.

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Tổng hợp. — TransactionSummary, application/json
• Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
from	query	Không	Timestamp | Date	Mặc định: đầu ngày hôm nay (giờ Việt Nam).
to	query	Không	Timestamp | Date	Mặc định: bây giờ.
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
account_id	query	Không	AccountId	Mã tài khoản ngân hàng (acc_…).
group_by	query	Không	string	—

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import summarize_transactions

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

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

GET /v1/transactions/sync

Đồng bộ thay đổi giao dịch

Đọc thay đổi theo con trỏ thay vì quét lại danh sách. Lần đầu bỏ cursor để bắt đầu từ đầu; sau đó luôn dùng next_cursor vừa nhận cho đến khi has_more=false. Tối đa 100 tài khoản trong phạm vi (nhiều hơn: lọc account_id, trả 422 too_many_accounts).

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Trang thay đổi. — SyncPage, 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ả
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.
limit	query	Không	integer	Số phần tử mỗi trang (1–100, mặc định 20).
account_id	query	Không	string	Chỉ đồng bộ một tài khoản.

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import sync_transactions

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

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

GET /v1/transactions/{id}

Chi tiết giao dịch

Giao dịch đã gộp vẫn truy cập được bằng mã cũ và trả merged_into.

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Giao dịch. — Transaction, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import get_transaction

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

dtp

Xem một giao dịch.

dtp tx get tx_0f5k2m9q4h7t3n8r6v1w0x5yz0

MCP

Công cụ get_transaction, scope transactions:read.

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

GET /v1/transactions/{id}/events

Nhật ký của giao dịch

Quyền: tx.read Scope: transactions:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Nhật ký theo thời gian. — TransactionEventList, application/json
• Mã lỗi riêng của endpoint: invalid_cursor, resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID/events" \
  -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/transactions/{id}/events", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import list_transaction_events

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

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

GET /v1/transactions/{id}/sources

Nguồn gốc của giao dịch

Các nguồn đã báo giao dịch và mức tin cậy lúc nhận. Cần quyền xem dữ liệu gốc; mỗi lần xem được ghi nhật ký.

Quyền: tx.read_raw

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

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID/sources" \
  -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/transactions/{id}/sources", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import list_transaction_sources

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

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

POST /v1/transactions/{id}:decide-manual-verify

Duyệt hoặc từ chối xác nhận thủ công

Người thứ hai quyết định yêu cầu đang chờ của giao dịch. Cùng người đề nghị trả 403 approver_same_as_maker. Duyệt xong giao dịch thành verified với verified_by=manual và phát đúng một transaction.confirmed.

Quyền: tx.verify_manual.approve Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: DecideManualVerify (application/json, bắt buộc)
• Phản hồi thành công 200: Giao dịch sau quyết định (vẫn provisional nếu từ chối). — Transaction, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID:decide-manual-verify" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions/{id}:decide-manual-verify", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "decision": "approve"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import decide_manual_verify_transaction
from dongtien_api.models import DecideManualVerify

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = decide_manual_verify_transaction.sync(
        id="tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=DecideManualVerify.from_dict({
            "decision": "approve",
        }),
    )

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

POST /v1/transactions/{id}:manual-verify

Đề nghị xác nhận thủ công

Chỉ tạo yêu cầu duyệt (tx_verify_manual): giao dịch vẫn provisional cho tới khi người thứ hai (khác người đề nghị) duyệt bằng :decide-manual-verify. Cần reason và evidence. Đã có yêu cầu đang chờ trả 409 conflict; giao dịch đã verified, cách ly hoặc đã gộp trả 409 conflict.

Quyền: tx.verify_manual.propose Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: ManualVerifyTransaction (application/json, bắt buộc)
• Phản hồi thành công 202: Đã tạo yêu cầu duyệt. — TransactionApprovalRef, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID:manual-verify" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Đã đối chiếu sao kê",
  "evidence": "Sao kê VCB ngày 19/10, dòng 12"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions/{id}:manual-verify", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Đã đối chiếu sao kê",
    "evidence": "Sao kê VCB ngày 19/10, dòng 12"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import manual_verify_transaction
from dongtien_api.models import ManualVerifyTransaction

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = manual_verify_transaction.sync(
        id="tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=ManualVerifyTransaction.from_dict({
            "reason": "Đã đối chiếu sao kê",
            "evidence": "Sao kê VCB ngày 19/10, dòng 12",
        }),
    )

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

POST /v1/transactions/{id}:reject-quarantine

Loại bỏ giao dịch cách ly

Bắt buộc reason và evidence; ghi nhật ký kiểm toán. Giao dịch chuyển rejected (cuối cùng, không tính vào số dư/quota/xuất). Không ở trạng thái cách ly trả 409 conflict.

Quyền: tx.release_quarantine Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: QuarantineDecision (application/json, bắt buộc)
• Phản hồi thành công 200: Giao dịch sau khi loại bỏ. — Transaction, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID:reject-quarantine" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Đã gọi ngân hàng xác nhận",
  "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions/{id}:reject-quarantine", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Đã gọi ngân hàng xác nhận",
    "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import reject_quarantined_transaction
from dongtien_api.models import QuarantineDecision

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = reject_quarantined_transaction.sync(
        id="tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=QuarantineDecision.from_dict({
            "reason": "Đã gọi ngân hàng xác nhận",
            "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê",
        }),
    )

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

POST /v1/transactions/{id}:release-quarantine

Gỡ cách ly giao dịch

Bắt buộc reason và evidence; ghi nhật ký kiểm toán. Giao dịch trở lại active nhưng vẫn provisional (không bao giờ tự xác thực). Không ở trạng thái cách ly trả 409 conflict.

Quyền: tx.release_quarantine Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: QuarantineDecision (application/json, bắt buộc)
• Phản hồi thành công 200: Giao dịch sau khi gỡ cách ly. — Transaction, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID:release-quarantine" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Đã gọi ngân hàng xác nhận",
  "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions/{id}:release-quarantine", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Đã gọi ngân hàng xác nhận",
    "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import release_quarantined_transaction
from dongtien_api.models import QuarantineDecision

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = release_quarantined_transaction.sync(
        id="tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=QuarantineDecision.from_dict({
            "reason": "Đã gọi ngân hàng xác nhận",
            "evidence": "Mã tham chiếu FT26292xxxxx khớp sao kê",
        }),
    )

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

POST /v1/transactions/{id}:unmerge

Tách giao dịch đã gộp

Giao dịch con (merged_into có giá trị) trở lại active; giao dịch chính giảm số nguồn. Ghi nhật ký kiểm toán; quota được tính lại bất đồng bộ. Giao dịch không phải bản gộp trả 409 conflict.

Quyền: tx.unmerge Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: UnmergeTransaction (application/json)
• Phản hồi thành công 200: Giao dịch sau khi tách. — Transaction, 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ó	TxId	Mã giao dịch (tx_…), ổn định vĩnh viễn kể cả khi bị gộp.
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/transactions/$ID:unmerge" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Hai giao dịch khác nhau, gộp nhầm"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions/{id}:unmerge", {
  params: {
    path: { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Hai giao dịch khác nhau, gộp nhầm"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import unmerge_transaction
from dongtien_api.models import UnmergeTransaction

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = unmerge_transaction.sync(
        id="tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=UnmergeTransaction.from_dict({
            "reason": "Hai giao dịch khác nhau, gộp nhầm",
        }),
    )

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

POST /v1/transactions:bulk-note

Ghi chú / gắn thẻ hàng loạt

Tối đa 100 giao dịch một lần. Chỉ là nhãn của người dùng, không tạo bút toán. Giao dịch ngoài phạm vi của người gọi báo not_found thay vì lỗi cả lô.

Quyền: tx.annotate Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: BulkNote (application/json, bắt buộc)
• Phản hồi thành công 200: Kết quả. — BulkNoteResult, application/json
• Mã lỗi riêng của endpoint: 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ũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/transactions:bulk-note" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tx_ids": [
    "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"
  ]
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions:bulk-note", {
  body: {
    "tx_ids": [
      "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0"
    ]
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import bulk_note_transactions
from dongtien_api.models import BulkNote

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = bulk_note_transactions.sync(
        client=dt.client,
        body=BulkNote.from_dict({
            "tx_ids": [
                "tx_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            ],
        }),
    )

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

POST /v1/transactions:export

Xuất giao dịch

Trả 202 và mã tác vụ. Tối đa 50,000 dòng; ô bắt đầu bằng = + - @ được trung hoà để không chạy thành công thức. Không tính quota; ghi nhật ký kiểm toán. Giao dịch cách ly chỉ xuất khi include_quarantined=true.

Quyền: tx.read Scope: transactions:read Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: export
• Nội dung yêu cầu: ExportTransactions (application/json, bắt buộc)
• Phản hồi thành công 202: Đã nhận lệnh xuất. Tác vụ export.transactions thường đã xong khi trả lời; result.download_path trỏ tới tệp (hết hạn sau 24 giờ). — JobAccepted, application/json
• Mã lỗi riêng của endpoint: 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ũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/transactions:export" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "format": "csv",
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "status": "provisional",
  "direction": "in",
  "include_quarantined": false
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/transactions:export", {
  body: {
    "format": "csv",
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "status": "provisional",
    "direction": "in",
    "include_quarantined": false
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.giao_dich import export_transactions
from dongtien_api.models import ExportTransactions

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = export_transactions.sync(
        client=dt.client,
        body=ExportTransactions.from_dict({
            "format": "csv",
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "status": "provisional",
            "direction": "in",
            "include_quarantined": False,
        }),
    )

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

Đối tượng

TransactionExportFile

Trường	Kiểu	Bắt buộc	Mô tả
data	map<string, string | number | null>[]	Có	—
object	string	Có	Giá trị: transaction_export.

TransactionList

Trường	Kiểu	Bắt buộc	Mô tả
data	Transaction[]	Có	—
data[].account	object	Có	—
data[].amount	PositiveVnd	Có	—
data[].balance_after	integer | null	Có	Số dư sau giao dịch nếu nguồn có; không bao giờ suy đoán.
data[].chain_flag	string | null	Không	Chuỗi số dư nghi ngờ quanh giao dịch: chain_mismatch số dư mâu thuẫn, gap_suspected nghi thiếu giao dịch. Chỉ đánh dấu nhất quán — không đổi trạng thái xác thực (D36). Giá trị: chain_mismatch, gap_suspected.
data[].company	object	Có	—
data[].counterparty	object | null	Có	—
data[].currency	string	Có	Giá trị: VND.
data[].dedupe_hint	string | null	Không	Gợi ý khử trùng lúc nhập: ambiguous (nhiều ứng viên, không gộp), near_duplicate (giống nhưng chưa đủ điểm), locked_period (kỳ đã khoá), quarantined_source (nguồn bị cách ly nên không gộp). Giá trị: ambiguous, near_duplicate, locked_period, quarantined_source.
data[].description	string | null	Có	—
data[].direction	string	Có	Giá trị: in, out.
data[].id	TxId	Có	—
data[].lifecycle	string	Có	Giá trị: active, merged_child, quarantined, rejected, released.
data[].memo_code	string | null	Có	Mã nội dung chuyển khoản DTP… đã trích.
data[].merged_into	string | null	Có	Khi bị gộp, mã giao dịch chính; mã tx_ cũ vẫn truy cập được.
data[].object	string	Có	Giá trị: transaction.
data[].occurred_at	Timestamp	Có	—
data[].occurred_precision	string	Có	Giá trị: date, minute, second.
data[].payment_request	PaymentRequestId | null	Có	—
data[].quarantine_reason	string | null	Không	Lý do cách ly khi lifecycle là quarantined/rejected: unverified_sender, device_sig_invalid, dkim_fail, domain_mismatch hoặc lý do do người vận hành nhập; null nếu không bị cách ly.
data[].received_at	Timestamp	Có	—
data[].recon_status	string	Có	Giá trị: unreconciled, suggested, pending_approval, reconciled, not_required, routed_settlement.
data[].source_count	integer	Không	Số nguồn đã gộp vào giao dịch này (“Gộp từ n nguồn”).
data[].sources	string[]	Có	Các kênh đã báo giao dịch này (sau khi gộp). Giá trị: android, ios, email, openapi, statement, import.
data[].status	TransactionStatus	Có	Giá trị: provisional, confirmed.
data[].verified_by	string | null	Có	Bằng chứng đã xác thực giao dịch; null khi còn provisional. Giá trị: openapi, statement, trusted_sender, email_dkim, manual, import.
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.

TransactionSummary

Trường	Kiểu	Bắt buộc	Mô tả
from	Timestamp | Date	Có	—
groups	object[]	Không	Chỉ có khi truyền group_by.
groups[].count	integer	Có	—
groups[].in	integer	Có	Tổng tiền vào (gồm cả tạm tính).
groups[].key	string	Có	—
groups[].label	string | null	Có	—
groups[].out	integer	Có	Tổng tiền ra (gồm cả tạm tính).
groups[].provisional_in	integer	Có	Trong đó tiền vào còn tạm tính.
groups[].provisional_out	integer	Có	Trong đó tiền ra còn tạm tính.
object	string	Có	Giá trị: transaction_summary.
presets	object	Có	Số giao dịch theo các bộ lọc nhanh: Tất cả · Cần xử lý · Vào hôm nay · Tạm tính >24h · Chưa đối soát · Cách ly.
presets.all	integer	Có	—
presets.in_today	integer	Có	—
presets.needs_attention	integer	Có	—
presets.provisional_over_24h	integer	Có	—
presets.quarantined	integer	Có	—
presets.unreconciled	integer	Có	—
to	Timestamp | Date	Có	—
totals	object	Có	—
totals.count	integer	Có	—
totals.in	integer	Có	Tổng tiền vào (gồm cả tạm tính).
totals.out	integer	Có	Tổng tiền ra (gồm cả tạm tính).
totals.provisional_in	integer	Có	Trong đó tiền vào còn tạm tính.
totals.provisional_out	integer	Có	Trong đó tiền ra còn tạm tính.

SyncPage

Trường	Kiểu	Bắt buộc	Mô tả
changes	SyncChange[]	Có	—
changes[].account_id	AccountId	Có	—
changes[].change	string	Có	Giá trị: created, verified, merged, unmerged, quarantined, released, annotated, source_added, rejected, recon_changed.
changes[].seq	integer	Có	Số thứ tự thay đổi trong tài khoản (tăng đơn điệu, không bỏ sót).
changes[].transaction	Transaction	Có	—
has_more	boolean	Có	—
next_cursor	string	Có	Luôn có; lưu lại và dùng cho lần gọi kế tiếp, kể cả khi changes rỗng.
object	string	Có	Giá trị: sync_page.

Transaction

Trường	Kiểu	Bắt buộc	Mô tả
account	object	Có	—
account.bank	string	Có	—
account.id	AccountId	Có	—
account.label	string	Có	—
account.last4	string	Có	—
amount	PositiveVnd	Có	—
balance_after	integer | null	Có	Số dư sau giao dịch nếu nguồn có; không bao giờ suy đoán.
chain_flag	string | null	Không	Chuỗi số dư nghi ngờ quanh giao dịch: chain_mismatch số dư mâu thuẫn, gap_suspected nghi thiếu giao dịch. Chỉ đánh dấu nhất quán — không đổi trạng thái xác thực (D36). Giá trị: chain_mismatch, gap_suspected.
company	object	Có	—
company.id	OrgId	Có	—
company.mst	string | null	Có	—
counterparty	object | null	Có	—
counterparty.name_masked	string | null	Có	—
currency	string	Có	Giá trị: VND.
dedupe_hint	string | null	Không	Gợi ý khử trùng lúc nhập: ambiguous (nhiều ứng viên, không gộp), near_duplicate (giống nhưng chưa đủ điểm), locked_period (kỳ đã khoá), quarantined_source (nguồn bị cách ly nên không gộp). Giá trị: ambiguous, near_duplicate, locked_period, quarantined_source.
description	string | null	Có	—
direction	string	Có	Giá trị: in, out.
id	TxId	Có	—
lifecycle	string	Có	Giá trị: active, merged_child, quarantined, rejected, released.
memo_code	string | null	Có	Mã nội dung chuyển khoản DTP… đã trích.
merged_into	string | null	Có	Khi bị gộp, mã giao dịch chính; mã tx_ cũ vẫn truy cập được.
object	string	Có	Giá trị: transaction.
occurred_at	Timestamp	Có	—
occurred_precision	string	Có	Giá trị: date, minute, second.
payment_request	PaymentRequestId | null	Có	—
quarantine_reason	string | null	Không	Lý do cách ly khi lifecycle là quarantined/rejected: unverified_sender, device_sig_invalid, dkim_fail, domain_mismatch hoặc lý do do người vận hành nhập; null nếu không bị cách ly.
received_at	Timestamp	Có	—
recon_status	string	Có	Giá trị: unreconciled, suggested, pending_approval, reconciled, not_required, routed_settlement.
source_count	integer	Không	Số nguồn đã gộp vào giao dịch này (“Gộp từ n nguồn”).
sources	string[]	Có	Các kênh đã báo giao dịch này (sau khi gộp). Giá trị: android, ios, email, openapi, statement, import.
status	TransactionStatus	Có	Giá trị: provisional, confirmed.
verified_by	string | null	Có	Bằng chứng đã xác thực giao dịch; null khi còn provisional. Giá trị: openapi, statement, trusted_sender, email_dkim, manual, import.

TransactionEventList

Trường	Kiểu	Bắt buộc	Mô tả
data	TransactionEvent[]	Có	—
data[].actor	string	Có	user:usr_…, system:pipeline, key:apk_……
data[].at	Timestamp	Có	—
data[].detail	map<string, any>	Có	—
data[].kind	string	Có	Giá trị: created, verified, merged, unmerged, quarantined, released, activated, rejected, recon_changed, annotated, source_added, relation_added, quota_eligible.
data[].object	string	Có	Giá trị: transaction_event.
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.

TransactionSourceList

Trường	Kiểu	Bắt buộc	Mô tả
data	TransactionSource[]	Có	—
data[].channel	string	Có	Giá trị: android, ios, email, openapi, statement, import.
data[].confidence	number | null	Không	Độ tin cậy của parser (0–1). null khi hệ thống không lưu — hiện tx_sources chưa có cột này.
data[].device_id	string | null	Không	Thiết bị đã gửi tin (dev_…).
data[].dkim_summary	object | null	Không	Kết quả DKIM của email: miền ký, selector, kết quả, có chuyển tiếp hay không.
data[].object	string	Có	Giá trị: transaction_source.
data[].parser_id	string | null	Không	Bộ phân tích đã đọc tin (vcb.sms…); null với nguồn không qua parser.
data[].parser_version	string | null	Không	Phiên bản bộ phân tích.
data[].raw_masked	string | null	Không	Nội dung gốc đã che mọi chuỗi ≥ 8 chữ số (•••1234). Chỉ có khi người gọi có tx.read_raw; null khi bản gốc đã hết hạn lưu hoặc không còn giải mã được.
data[].raw_sha256	string | null	Không	SHA-256 (hex) của nội dung gốc; còn sau khi bản gốc hết hạn lưu.
data[].received_at	Timestamp	Có	—
data[].sender_trust	string	Có	Giá trị: os_sender_match, app_package_match, unverified_sender, unavailable, none.
data[].sms_sent_at	string | null	Không	Thời điểm SMSC gửi tin.
data[].source_ref	string | null	Có	Mã tham chiếu của nguồn (id ngân hàng, message-id…), đã che nếu nhạy cảm.
data[].trust_at_receipt	string	Có	Giá trị: verified, provisional, quarantined.
data[].trust_basis	string | null	Có	Giá trị: trusted_sender, sender_verified_ios, email_dkim_direct, email_dkim_forwarded, none.
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.

DecideManualVerify

Trường	Kiểu	Bắt buộc	Mô tả
decision	string	Có	Giá trị: approve, reject.
reason	string	Không	—

ManualVerifyTransaction

Trường	Kiểu	Bắt buộc	Mô tả
evidence	string	Có	Bằng chứng người duyệt đã đối chiếu (ví dụ: sao kê, cuộc gọi ngân hàng). Ghi nhật ký kiểm toán.
reason	string	Có	—

TransactionApprovalRef

Trường	Kiểu	Bắt buộc	Mô tả
expires_at	Timestamp	Có	—
id	ApprovalRequestId	Có	—
kind	string	Có	Giá trị: tx_verify_manual.
object	string	Có	Giá trị: approval_request.
state	string	Có	Giá trị: pending, approved, rejected, withdrawn, expired.
transaction_id	TxId	Có	—

QuarantineDecision

Trường	Kiểu	Bắt buộc	Mô tả
evidence	string	Có	Bằng chứng người duyệt đã đối chiếu (ví dụ: sao kê, cuộc gọi ngân hàng). Ghi nhật ký kiểm toán.
reason	string	Có	—

UnmergeTransaction

Trường	Kiểu	Bắt buộc	Mô tả
reason	string	Không	—

Đối tượng khác của nhóm này (xem tài liệu tương tác): BulkNote, BulkNoteResult, ExportTransactions, JobAccepted

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.