Nhập sao kê

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.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/statement-mappings	Danh sách mẫu ánh xạ cột	statement.import	read	Scalar
PUT	/v1/statement-mappings	Lưu mẫu ánh xạ cột	statement.import	write	Scalar
GET	/v1/statement-schedules	Danh sách lịch nhận sao kê	statement_schedule.manage	read	Scalar
POST	/v1/statement-schedules	Tạo lịch nhận sao kê	statement_schedule.manage	write	Scalar
PATCH	/v1/statement-schedules/{id}	Sửa lịch nhận sao kê	statement_schedule.manage	write	Scalar
DELETE	/v1/statement-schedules/{id}	Xoá lịch nhận sao kê	statement_schedule.manage	write	Scalar
POST	/v1/statement-schedules/{id}:run	Chạy lịch ngay	statement_schedule.manage	write	Scalar
GET	/v1/statements	Danh sách sao kê đã tải	statement.import	read	Scalar
POST	/v1/statements/preview	Tải sao kê lên để xem trước	statement.import	write	Scalar
GET	/v1/statements/{id}	Chi tiết sao kê	statement.import	read	Scalar
GET	/v1/statements/{id}/errors	Tải nhật ký dòng lỗi	statement.import	export	Scalar
GET	/v1/statements/{id}/rows	Dòng xem trước của sao kê	statement.import	read	Scalar
POST	/v1/statements/{id}:cancel	Huỷ sao kê chưa nhập	statement.import	write	Scalar
POST	/v1/statements/{id}:commit	Nhập sao kê vào sổ	statement.import	write	Scalar
POST	/v1/statements/{id}:rerun	Chạy lại xem trước với ánh xạ khác	statement.import	write	Scalar

Chi tiết endpoint

GET /v1/statement-mappings

Danh sách mẫu ánh xạ cột

Mẫu mới cập nhật trước, tối đa 200. Lọc theo mã ngân hàng và/hoặc dấu vân tay tiêu đề.

Quyền: statement.import

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách. — StatementMappingList, 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ả
bank_code	query	Không	string	—
header_fingerprint	query	Không	string	—

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import list_statement_mappings

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

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

PUT /v1/statement-mappings

Lưu mẫu ánh xạ cột

Mỗi (ngân hàng, dấu vân tay tiêu đề) chỉ có một mẫu: lưu lại cùng khoá thì thay thế mẫu cũ (200 cả khi tạo mới). Cần có cột ngày và cột số tiền (hoặc cả ghi nợ lẫn ghi có).

Quyền: statement.import Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: PutStatementMapping (application/json, bắt buộc)
• Phản hồi thành công 200: Mẫu đã lưu. — StatementMapping, 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 PUT "https://api.dongtien.pro/v1/statement-mappings" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "bank_code": "ACB",
  "header_fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "mapping": {
    "layout_id": "acb",
    "header_row": 8,
    "columns": {
      "date": 0,
      "debit": 3,
      "credit": 4,
      "balance": 5,
      "description": 2
    }
  }
}'

TypeScript

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

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

const { data } = await dt.PUT("/v1/statement-mappings", {
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "bank_code": "ACB",
    "header_fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "mapping": {
      "layout_id": "acb",
      "header_row": 8,
      "columns": {
        "date": 0,
        "debit": 3,
        "credit": 4,
        "balance": 5,
        "description": 2
      }
    }
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import put_statement_mapping
from dongtien_api.models import PutStatementMapping

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = put_statement_mapping.sync(
        client=dt.client,
        body=PutStatementMapping.from_dict({
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "bank_code": "ACB",
            "header_fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "mapping": {
                "layout_id": "acb",
                "header_row": 8,
                "columns": {
                    "date": 0,
                    "debit": 3,
                    "credit": 4,
                    "balance": 5,
                    "description": 2,
                },
            },
        }),
    )

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

GET /v1/statement-schedules

Danh sách lịch nhận sao kê

Mới tạo trước, tối đa 200. Lọc theo tài khoản.

Quyền: statement_schedule.manage

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách. — StatementScheduleList, 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ả
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
bank_account_id	query	Không	AccountId	Mã tài khoản ngân hàng (acc_…).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import list_statement_schedules

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

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

POST /v1/statement-schedules

Tạo lịch nhận sao kê

email_attachment: sao kê đến qua alias thư của công ty. manual_upload: nhắc người tải tay theo cron; quá overdue_after_days ngày mà chưa có thì trạng thái overdue. sftp: ngân hàng đẩy CAMT.053 lên máy chủ SFTP, cổng ngân hàng lấy về theo cron. Cần cron trừ nguồn thư; SFTP cần cấu hình máy chủ.

Quyền: statement_schedule.manage Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: CreateStatementSchedule (application/json, bắt buộc)
• Phản hồi thành công 201: Đã tạo. — StatementSchedule, 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/statement-schedules" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bank_account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "source": "email_attachment",
  "format": "auto",
  "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "sftp": {
    "port": 22
  },
  "auto_commit": true,
  "overdue_after_days": 7
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/statement-schedules", {
  body: {
    "bank_account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "source": "email_attachment",
    "format": "auto",
    "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "sftp": {
      "port": 22
    },
    "auto_commit": true,
    "overdue_after_days": 7
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import create_statement_schedule
from dongtien_api.models import CreateStatementSchedule

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_statement_schedule.sync(
        client=dt.client,
        body=CreateStatementSchedule.from_dict({
            "bank_account_id": "acc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "source": "email_attachment",
            "format": "auto",
            "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "sftp": {
                "port": 22,
            },
            "auto_commit": True,
            "overdue_after_days": 7,
        }),
    )

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

PATCH /v1/statement-schedules/{id}

Sửa lịch nhận sao kê

Sửa định dạng, lịch, cấu hình SFTP, tự nhập, hạn quá hạn, bật/tắt. Tài khoản và nguồn không đổi. cron chỉ với manual_upload/sftp; sftp chỉ với lịch SFTP.

Quyền: statement_schedule.manage Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: UpdateStatementSchedule (application/json, bắt buộc)
• Phản hồi thành công 200: Sau cập nhật. — StatementSchedule, 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ó	StatementScheduleId	Mã lịch nhận sao kê (ssc_…).
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/statement-schedules/$ID" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "format": "auto",
  "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "sftp": {
    "port": 22
  }
}'

TypeScript

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

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

const { data } = await dt.PATCH("/v1/statement-schedules/{id}", {
  params: {
    path: { "id": "ssc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "format": "auto",
    "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "sftp": {
      "port": 22
    }
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import update_statement_schedule
from dongtien_api.models import UpdateStatementSchedule

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = update_statement_schedule.sync(
        id="ssc_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=UpdateStatementSchedule.from_dict({
            "format": "auto",
            "alias_id": "eal_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "sftp": {
                "port": 22,
            },
        }),
    )

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

DELETE /v1/statement-schedules/{id}

Xoá lịch nhận sao kê

Xoá lịch; các sao kê đã nhập từ lịch này được giữ.

Quyền: statement_schedule.manage Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 204: Đã xoá. — không có nội dung
• 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ó	StatementScheduleId	Mã lịch nhận sao kê (ssc_…).
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 DELETE "https://api.dongtien.pro/v1/statement-schedules/$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.DELETE("/v1/statement-schedules/{id}", {
  params: {
    path: { "id": "ssc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import delete_statement_schedule

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

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

POST /v1/statement-schedules/{id}:run

Chạy lịch ngay

Xử lý lại tệp gần nhất của lịch như một sao kê mới (theo auto_commit của lịch). 409 conflict khi lịch chưa có tệp nào, hoặc là lịch manual_upload (tải tệp lên qua POST /v1/statements/preview). Việc lấy tệp từ SFTP do cổng ngân hàng thực hiện theo lịch.

Quyền: statement_schedule.manage Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 202: Đã nhận. — StatementAccepted, 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ó	StatementScheduleId	Mã lịch nhận sao kê (ssc_…).
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/statement-schedules/$ID:run" \
  -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/statement-schedules/{id}:run", {
  params: {
    path: { "id": "ssc_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import run_statement_schedule

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

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

GET /v1/statements

Danh sách sao kê đã tải

Mới nhất trước. Lọc theo tài khoản và trạng thái.

Quyền: statement.import

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách. — StatementImportList, 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ả
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
bank_account_id	query	Không	AccountId	Mã tài khoản ngân hàng (acc_…).
state	query	Không	StatementImportState	created → validating → preview_ready → committing → completed | completed_with_errors; failed, cancelled. halted_balance_mismatch: số dư không khớp, không nhập được.
limit	query	Không	integer	—
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/statements" \
  -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/statements");

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import list_statements

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

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

POST /v1/statements/preview

Tải sao kê lên để xem trước

Nhận tệp (multipart/form-data, tối đa 25 MB), kiểm tra nội dung bằng chữ ký tệp, niêm phong rồi lưu và chạy xem trước: nhận dạng bố cục, kiểm số dư đầu/cuối, chạy thử gộp trùng. Chưa ghi gì vào sổ. Trả 202 với tác vụ để theo dõi; khi state=preview_ready đọc GET /v1/statements/{id}. Cùng một tệp đã có trên tài khoản này: 200 kèm sao kê cũ, không tạo thêm. Tệp sai chữ ký: 422; quá 25 MB: 413.

Quyền: statement.import

• Nhóm tốc độ: write
• Nội dung yêu cầu: PreviewStatementForm (multipart/form-data, bắt buộc)
• Phản hồi thành công 200: Tệp này đã được tải lên trước đó cho tài khoản: trả sao kê cũ. — StatementAccepted, application/json
• Phản hồi thành công 202: Đã nhận tệp; đang nhận dạng và xem trước. — StatementAccepted, application/json
• Mã lỗi riêng của endpoint: conflict

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import preview_statement

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

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

GET /v1/statements/{id}

Chi tiết sao kê

Trạng thái, tệp, kỳ, đếm, bản xem trước (kiểm số dư, đếm mới/khớp/trùng/lỗi, ánh xạ cột) và kết quả sau khi nhập (neo số dư, giao dịch tạm tính không có trong sao kê).

Quyền: statement.import

• Nhóm tốc độ: read
• Phản hồi thành công 200: Sao kê. — StatementImport, 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import get_statement

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

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

GET /v1/statements/{id}/errors

Tải nhật ký dòng lỗi

Văn bản thuần (text/plain) theo dạng NDJSON: mỗi dòng một JSON {row_no, code} của một dòng lỗi trong sao kê. 404 khi sao kê không có dòng lỗi.

Quyền: statement.import

• Nhóm tốc độ: export
• Phản hồi thành công 200: Nhật ký lỗi, mỗi dòng một JSON. — string (binary), text/plain
• 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import get_statement_errors

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

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

GET /v1/statements/{id}/rows

Dòng xem trước của sao kê

Một trang 500 dòng của bản xem trước, theo thứ tự thời gian. status lọc các dòng trong trang. Chỉ có khi sao kê đã tới preview_ready (hoặc sau đó); trước đó trả 409 conflict.

Quyền: statement.import

• Nhóm tốc độ: read
• Phản hồi thành công 200: Trang dòng. — StatementRowsPage, 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).
page	query	Không	integer	—
status	query	Không	string	—

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import list_statement_rows

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

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

POST /v1/statements/{id}:cancel

Huỷ sao kê chưa nhập

Bỏ bản xem trước chưa nhập (created, preview_ready hoặc halted_balance_mismatch). Đang nhập hoặc đã xong trả 409 conflict. Tệp cùng nội dung có thể tải lên lại sau khi huỷ.

Quyền: statement.import Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Sao kê đã huỷ. — StatementImportSummary, 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).
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/statements/$ID:cancel" \
  -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/statements/{id}:cancel", {
  params: {
    path: { "id": "imp_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import cancel_statement

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

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

POST /v1/statements/{id}:commit

Nhập sao kê vào sổ

Chỉ khi state=preview_ready. Sao kê số dư lệch (halted_balance_mismatch) trả 409 balance_mismatch: không có cách ép nhập, hãy sửa ánh xạ cột rồi chạy lại hoặc huỷ. Trạng thái khác trả 409 conflict. Gọi lại khi đang nhập trả chính tác vụ đó.

Quyền: statement.import Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 202: Đã nhận lệnh nhập. — StatementAccepted, 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).
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/statements/$ID:commit" \
  -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/statements/{id}:commit", {
  params: {
    path: { "id": "imp_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import commit_statement

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

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

POST /v1/statements/{id}:rerun

Chạy lại xem trước với ánh xạ khác

Chỉ từ preview_ready hoặc halted_balance_mismatch. Đọc lại tệp đã lưu với ánh xạ mới (mapping_id hoặc mapping), tuỳ chọn lưu làm mẫu. Trả 202 với tác vụ xem trước mới.

Quyền: statement.import Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: RerunStatement (application/json, bắt buộc)
• Phản hồi thành công 202: Đã nhận lệnh chạy lại. — StatementAccepted, 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ó	StatementImportId	Mã lần nhập sao kê (imp_…).
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/statements/$ID:rerun" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mapping_id": "smp_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "mapping": {
    "layout_id": "acb",
    "header_row": 8,
    "columns": {
      "date": 0,
      "debit": 3,
      "credit": 4,
      "balance": 5,
      "description": 2
    }
  }
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/statements/{id}:rerun", {
  params: {
    path: { "id": "imp_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "mapping_id": "smp_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "mapping": {
      "layout_id": "acb",
      "header_row": 8,
      "columns": {
        "date": 0,
        "debit": 3,
        "credit": 4,
        "balance": 5,
        "description": 2
      }
    }
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhap_sao_ke import rerun_statement
from dongtien_api.models import RerunStatement

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = rerun_statement.sync(
        id="imp_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=RerunStatement.from_dict({
            "mapping_id": "smp_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "mapping": {
                "layout_id": "acb",
                "header_row": 8,
                "columns": {
                    "date": 0,
                    "debit": 3,
                    "credit": 4,
                    "balance": 5,
                    "description": 2,
                },
            },
        }),
    )

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

Đối tượng

StatementMappingList

Trường	Kiểu	Bắt buộc	Mô tả
data	StatementMapping[]	Có	—
data[].bank_code	string	Có	—
data[].company_id	OrgId	Có	—
data[].created_at	Timestamp	Có	—
data[].header_fingerprint	string	Có	SHA-256 của các ô tiêu đề đã chuẩn hoá.
data[].id	StatementMappingId	Có	—
data[].mapping	StatementColumnMapping	Có	—
data[].object	string	Có	Giá trị: statement_mapping.
data[].template_name	string | null	Có	—
data[].updated_at	Timestamp	Có	—
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.

PutStatementMapping

Trường	Kiểu	Bắt buộc	Mô tả
bank_code	string	Có	—
company_id	string	Có	Công ty sở hữu mẫu.
header_fingerprint	string	Có	—
mapping	StatementColumnMapping	Có	—
mapping.columns	object	Có	Chỉ số cột (đếm từ 0) của từng trường; trường nào không có cột thì bỏ qua.
mapping.header_row	integer	Có	Dòng tiêu đề (đếm từ 0).
mapping.header_rows	number | number	Không	Số dòng tiêu đề (mặc định 1).
mapping.layout_id	string	Không	Mã bố cục đã nhận dạng (ví dụ acb).
template_name	string	Không	—

StatementMapping

Trường	Kiểu	Bắt buộc	Mô tả
bank_code	string	Có	—
company_id	OrgId	Có	—
created_at	Timestamp	Có	—
header_fingerprint	string	Có	SHA-256 của các ô tiêu đề đã chuẩn hoá.
id	StatementMappingId	Có	—
mapping	StatementColumnMapping	Có	—
mapping.columns	object	Có	Chỉ số cột (đếm từ 0) của từng trường; trường nào không có cột thì bỏ qua.
mapping.header_row	integer	Có	Dòng tiêu đề (đếm từ 0).
mapping.header_rows	number | number	Không	Số dòng tiêu đề (mặc định 1).
mapping.layout_id	string	Không	Mã bố cục đã nhận dạng (ví dụ acb).
object	string	Có	Giá trị: statement_mapping.
template_name	string | null	Có	—
updated_at	Timestamp	Có	—

StatementScheduleList

Trường	Kiểu	Bắt buộc	Mô tả
data	StatementSchedule[]	Có	—
data[].alias_id	EmailAliasId | null	Có	—
data[].auto_commit	boolean	Có	true: tự nhập khi không có dòng lỗi và số dư khớp; ngược lại chờ người xác nhận.
data[].bank_account_id	AccountId	Có	—
data[].company_id	OrgId	Có	—
data[].created_at	Timestamp	Có	—
data[].cron	string | null	Có	—
data[].enabled	boolean	Có	—
data[].format	string	Có	Giá trị: auto, xlsx, csv, mt940, camt053.
data[].id	StatementScheduleId	Có	—
data[].last_job_id	StatementImportId | null	Có	Sao kê của lần chạy gần nhất.
data[].last_result	map<string, any> | null	Có	Đếm của lần chạy gần nhất (rows, new, skipped, error…), không có nội dung dòng.
data[].last_run_at	Timestamp | null	Có	—
data[].next_run_at	Timestamp | null	Có	—
data[].object	string	Có	Giá trị: statement_schedule.
data[].overdue_after_days	integer	Có	Quá số ngày này kể từ lúc đến hạn mà chưa có sao kê: trạng thái overdue ("Quá hạn nhắc").
data[].sftp	SftpConfig | null	Có	Chỉ có với source=sftp. Mật khẩu/khoá không bao giờ trả về.
data[].source	string	Có	Giá trị: email_attachment, manual_upload, sftp.
data[].status	string	Có	Giá trị: never, ok, failed, overdue.
data[].updated_at	Timestamp	Có	—
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.

CreateStatementSchedule

Trường	Kiểu	Bắt buộc	Mô tả
alias_id	string	Không	Chỉ với email_attachment: alias thư nhận sao kê.
auto_commit	boolean	Không	—
bank_account_id	AccountId	Có	—
cron	string	Không	Bắt buộc với manual_upload và sftp; không dùng với email_attachment.
format	string	Không	Giá trị: auto, xlsx, csv, mt940, camt053.
overdue_after_days	integer	Không	—
sftp	object	Không	Bắt buộc với sftp, cấm với nguồn khác. SFTP chỉ nhận CAMT.053.
sftp.host	string	Có	—
sftp.host_key_sha256	string	Có	Dấu vân tay khoá máy chủ SFTP (SHA256:…, như ssh-keygen -lf). Cổng ngân hàng chỉ kết nối khi máy chủ trình đúng khoá này; không khớp thì từ chối, không tự tin cậy lần đầu.
sftp.path	string	Có	Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ /out/camt053/*.xml.
sftp.port	integer	Không	—
sftp.secret	string	Có	Mật khẩu hoặc khoá riêng; được niêm phong cho cổng ngân hàng, không bao giờ trả về.
sftp.username	string	Có	—
source	string	Có	Giá trị: email_attachment, manual_upload, sftp.

StatementSchedule

Trường	Kiểu	Bắt buộc	Mô tả
alias_id	EmailAliasId | null	Có	—
auto_commit	boolean	Có	true: tự nhập khi không có dòng lỗi và số dư khớp; ngược lại chờ người xác nhận.
bank_account_id	AccountId	Có	—
company_id	OrgId	Có	—
created_at	Timestamp	Có	—
cron	string | null	Có	—
enabled	boolean	Có	—
format	string	Có	Giá trị: auto, xlsx, csv, mt940, camt053.
id	StatementScheduleId	Có	—
last_job_id	StatementImportId | null	Có	Sao kê của lần chạy gần nhất.
last_result	map<string, any> | null	Có	Đếm của lần chạy gần nhất (rows, new, skipped, error…), không có nội dung dòng.
last_run_at	Timestamp | null	Có	—
next_run_at	Timestamp | null	Có	—
object	string	Có	Giá trị: statement_schedule.
overdue_after_days	integer	Có	Quá số ngày này kể từ lúc đến hạn mà chưa có sao kê: trạng thái overdue ("Quá hạn nhắc").
sftp	SftpConfig | null	Có	Chỉ có với source=sftp. Mật khẩu/khoá không bao giờ trả về.
sftp.host	string	Có	—
sftp.host_key_sha256	string | null	Có	Khoá máy chủ đã ghim. null ở lịch tạo trước khi có ghim khoá: cổng ngân hàng không chạy lịch đó cho tới khi bạn nhập dấu vân tay.
sftp.path	string	Có	Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ /out/camt053/*.xml.
sftp.port	integer	Có	—
sftp.username	string	Có	—
source	string	Có	Giá trị: email_attachment, manual_upload, sftp.
status	string	Có	Giá trị: never, ok, failed, overdue.
updated_at	Timestamp	Có	—

UpdateStatementSchedule

Trường	Kiểu	Bắt buộc	Mô tả
alias_id	EmailAliasId | null	Không	—
auto_commit	boolean	Không	—
cron	string	Không	Lịch cron năm trường theo giờ Việt Nam (phút giờ ngày tháng thứ), ví dụ 0 9 1 * * = 9 giờ sáng ngày 1 hằng tháng.
enabled	boolean	Không	—
format	string	Không	Giá trị: auto, xlsx, csv, mt940, camt053.
overdue_after_days	integer	Không	—
sftp	object	Không	—
sftp.host	string	Có	—
sftp.host_key_sha256	string	Không	Bỏ trống để giữ khoá máy chủ đã ghim; bắt buộc khi đổi máy chủ hoặc cổng.
sftp.path	string	Có	Thư mục hoặc mẫu tên tệp trên máy chủ SFTP, ví dụ /out/camt053/*.xml.
sftp.port	integer	Không	—
sftp.secret	string	Không	Bỏ trống để giữ khoá cũ.
sftp.username	string	Có	—

StatementAccepted

Trường	Kiểu	Bắt buộc	Mô tả
job	Job	Có	—
job.created_at	Timestamp	Có	—
job.error	JobError	Không	—
job.finished_at	Timestamp | null	Có	—
job.id	JobId	Có	—
job.kind	JobKind	Có	—
job.object	string	Có	Giá trị: job.
job.progress	JobProgress	Có	—
job.result	map<string, any>	Không	Kết quả khi succeeded (cấu trúc tuỳ kind).
job.state	JobState	Có	Giá trị: queued, running, succeeded, failed, cancelled.
statement	StatementRef	Có	—
statement.id	StatementImportId	Có	—
statement.state	StatementImportState	Có	Giá trị: created, validating, preview_ready, committing, completed, completed_with_errors, failed, cancelled, halted_balance_mismatch.

StatementImportList

Trường	Kiểu	Bắt buộc	Mô tả
data	StatementImportSummary[]	Có	—
data[].bank_account_id	AccountId	Có	—
data[].commit_job_id	JobId | null	Có	—
data[].company_id	OrgId	Có	—
data[].counts	ImportCounts	Có	—
data[].created_at	Timestamp	Có	—
data[].created_by	string | null	Có	—
data[].error	object | null	Có	Có khi state=failed (ví dụ MISSING_COLUMN, TOO_MANY_ROWS).
data[].file	object	Có	Tệp đã tải lên.
data[].finished_at	Timestamp | null	Có	—
data[].id	StatementImportId	Có	—
data[].mapping_id	StatementMappingId | null	Có	—
data[].object	string	Có	Giá trị: statement.
data[].period	object | null	Có	Kỳ sao kê (giờ Việt Nam).
data[].preview_job_id	JobId | null	Có	—
data[].schedule_id	StatementScheduleId | null	Có	—
data[].source	StatementSource	Có	Giá trị: upload, email_attachment, sftp, schedule_run.
data[].started_at	Timestamp | null	Có	—
data[].state	StatementImportState	Có	Giá trị: created, validating, preview_ready, committing, completed, completed_with_errors, failed, cancelled, halted_balance_mismatch.
data[].total_rows	integer | null	Có	—
data[].updated_at	Timestamp	Có	—
data[].upgraded	integer	Có	Số giao dịch tạm tính đã nâng xác thực.
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.

StatementImport

Trường	Kiểu	Bắt buộc	Mô tả
bank_account_id	AccountId	Có	—
commit_job_id	JobId | null	Có	—
company_id	OrgId	Có	—
counts	ImportCounts	Có	—
counts.error	integer	Có	Dòng lỗi, không nhập.
counts.merged	integer	Có	Khớp giao dịch realtime sẵn có (nâng xác thực tại chỗ).
counts.new	integer	Có	Giao dịch mới tạo (đã xác thực).
counts.processed	integer	Có	new + merged + skipped đã ghi.
counts.skipped	integer	Có	Trùng, bỏ qua.
created_at	Timestamp	Có	—
created_by	string | null	Có	—
error	object | null	Có	Có khi state=failed (ví dụ MISSING_COLUMN, TOO_MANY_ROWS).
error.code	string	Có	—
error.detail	string | null	Có	—
file	object	Có	Tệp đã tải lên.
file.bank_code	string | null	Có	—
file.bytes	integer | null	Có	—
file.format	StatementFormat | null	Có	Giá trị: xlsx, xls, csv, mt940, camt053.
file.layout_id	string | null	Có	—
file.name	string | null	Có	—
file.sha256	string | null	Có	SHA-256 (hex) của tệp gốc.
finished_at	Timestamp | null	Có	—
id	StatementImportId	Có	—
mapping_id	StatementMappingId | null	Có	—
object	string	Có	Giá trị: statement.
period	object | null	Có	Kỳ sao kê (giờ Việt Nam).
period.from	Date	Có	—
period.to	Date	Có	—
preview	StatementPreview | null	Có	Có từ preview_ready (và khi halted_balance_mismatch).
preview.balance_check	StatementBalanceCheck	Có	—
preview.columns	StatementColumns | null	Có	null với MT940/CAMT (không có cột).
preview.counts	StatementPreviewCounts	Có	—
preview_job_id	JobId | null	Có	—
result	StatementResult | null	Có	Có khi đã nhập xong.
result.anchors	object[]	Có	—
result.promoted	integer	Có	Số giao dịch tạm tính đã được nâng lên xác thực.
result.unmatched_count	integer	Có	—
result.unmatched_provisional	TxId[]	Có	Giao dịch tạm tính trong kỳ mà sao kê không có ("Không có trong sao kê"), tối đa 200.
schedule_id	StatementScheduleId | null	Có	—
source	StatementSource	Có	Giá trị: upload, email_attachment, sftp, schedule_run.
started_at	Timestamp | null	Có	—
state	StatementImportState	Có	Giá trị: created, validating, preview_ready, committing, completed, completed_with_errors, failed, cancelled, halted_balance_mismatch.
total_rows	integer | null	Có	—
updated_at	Timestamp	Có	—
upgraded	integer	Có	Số giao dịch tạm tính đã nâng xác thực.

StatementRowsPage

Trường	Kiểu	Bắt buộc	Mô tả
data	StatementPreviewRow[]	Có	—
data[].amount	Vnd	Có	—
data[].balance_after	Vnd | null	Có	—
data[].bank_ref	string | null	Có	—
data[].counterparty_name	string | null	Có	—
data[].date	Date	Có	—
data[].description	string	Có	—
data[].direction	string	Có	Giá trị: in, out.
data[].error	string | null	Có	—
data[].row_no	integer	Có	Số dòng trong tệp gốc (đếm từ 1).
data[].status	string	Có	Giá trị: new, merged, skipped, error, locked.
data[].time	string | null	Có	HH:mm hoặc HH:mm:ss khi tệp có giờ.
data[].tx_id	string | null	Có	Giao dịch khớp (khi status=merged).
data[].upgrade	boolean	Có	true: khớp giao dịch tạm tính và sẽ nâng xác thực ("Khớp & nâng xác thực").
object	string	Có	Giá trị: statement_rows.
page	integer	Có	—
page_size	integer	Có	—
total_pages	integer	Có	—
total_rows	integer	Có	—

StatementImportSummary

Trường	Kiểu	Bắt buộc	Mô tả
bank_account_id	AccountId	Có	—
commit_job_id	JobId | null	Có	—
company_id	OrgId	Có	—
counts	ImportCounts	Có	—
counts.error	integer	Có	Dòng lỗi, không nhập.
counts.merged	integer	Có	Khớp giao dịch realtime sẵn có (nâng xác thực tại chỗ).
counts.new	integer	Có	Giao dịch mới tạo (đã xác thực).
counts.processed	integer	Có	new + merged + skipped đã ghi.
counts.skipped	integer	Có	Trùng, bỏ qua.
created_at	Timestamp	Có	—
created_by	string | null	Có	—
error	object | null	Có	Có khi state=failed (ví dụ MISSING_COLUMN, TOO_MANY_ROWS).
error.code	string	Có	—
error.detail	string | null	Có	—
file	object	Có	Tệp đã tải lên.
file.bank_code	string | null	Có	—
file.bytes	integer | null	Có	—
file.format	StatementFormat | null	Có	Giá trị: xlsx, xls, csv, mt940, camt053.
file.layout_id	string | null	Có	—
file.name	string | null	Có	—
file.sha256	string | null	Có	SHA-256 (hex) của tệp gốc.
finished_at	Timestamp | null	Có	—
id	StatementImportId	Có	—
mapping_id	StatementMappingId | null	Có	—
object	string	Có	Giá trị: statement.
period	object | null	Có	Kỳ sao kê (giờ Việt Nam).
period.from	Date	Có	—
period.to	Date	Có	—
preview_job_id	JobId | null	Có	—
schedule_id	StatementScheduleId | null	Có	—
source	StatementSource	Có	Giá trị: upload, email_attachment, sftp, schedule_run.
started_at	Timestamp | null	Có	—
state	StatementImportState	Có	Giá trị: created, validating, preview_ready, committing, completed, completed_with_errors, failed, cancelled, halted_balance_mismatch.
total_rows	integer | null	Có	—
updated_at	Timestamp	Có	—
upgraded	integer	Có	Số giao dịch tạm tính đã nâng xác thực.

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

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.