Nhập lô giao dịch (NDJSON)

~3 phút đọc

Khi hệ thống của bạn đã có sẵn lịch sử giao dịch (xuất từ phần mềm kế toán, từ một nguồn dữ liệu cũ, hay từ kho dữ liệu riêng), bạn đẩy lịch sử đó vào Dòng Tiền Pro bằng một lời gọi duy nhất tới POST /v1/import/batches. Mỗi lô nhập như một tác vụ: bạn nhận 202 cùng mã tác vụ, rồi đọc kết quả ở GET /v1/jobs/{id}.

Thân yêu cầu

Thân là NDJSON với Content-Type: application/x-ndjson: mỗi dòng một đối tượng JSON, một giao dịch. Tối đa 5.000 dòng và 5 MB mỗi lô; lịch sử dài hơn thì chia thành nhiều lô.

Mỗi dòng có các trường sau.

occurred_at: thời điểm giao dịch, RFC 3339 ở UTC (bắt buộc).
direction: in (tiền vào) hoặc out (tiền ra) (bắt buộc).
amount: số tiền VND nguyên, dương (bắt buộc).
Tài khoản: đúng một trong hai cách. Hoặc bank_account_id (acc_…), hoặc cặp account_number cùng bank_code.
external_id: mã giao dịch ở hệ thống của bạn, để đối chiếu lại (tuỳ chọn, tối đa 128 ký tự).
balance_after: số dư sau giao dịch (tuỳ chọn).
description, bank_ref, counterparty_name: nội dung, mã tham chiếu ngân hàng và tên đối tác (tuỳ chọn).

Dòng không biết trường nào ngoài danh sách này bị từ chối; hệ thống không bỏ qua trường lạ một cách im lặng.

Ví dụ hai dòng:

{"bank_account_id":"acc_0f5k2m9q4h7t3n8r6v1w0x5yz0","occurred_at":"2026-09-01T03:15:00Z","direction":"in","amount":1500000,"external_id":"HT-001"}
{"account_number":"0012345621","bank_code":"ACB","occurred_at":"2026-09-01T04:02:00Z","direction":"out","amount":320000,"description":"Thanh toán nhà cung cấp"}

Kiểm tra cả lô trước, rồi mới nhập

Cả lô được kiểm tra trước khi ghi bất cứ thứ gì. Chỉ cần một dòng sai là cả lô bị từ chối bằng 422 kèm số dòng lỗi, và không có giao dịch nào vào sổ. Sửa dòng đó rồi gửi lại lô, không cần dọn gì.

Lô hợp lệ nhập như một tác vụ duy nhất, không có bước xem trước. Giao dịch nhập ở mức Đã xác thực theo nguồn nhập; đó là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.

Idempotency-Key bắt buộc

Route này yêu cầu Idempotency-Key. Gửi lại cùng khoá cùng lô trả lại đúng tác vụ của lần đầu, nên có thể thử lại an toàn khi mạng đứt. Quy tắc chung nằm ở Idempotency.

Việc chống trùng không chỉ dựa vào khoá. Giao dịch nhập đi qua cùng bộ gộp trùng với kênh trực tiếp, nên một giao dịch đã có từ tin báo ngân hàng hoặc sao kê không bị đếm đôi; nó được gộp và, nếu đang là tạm tính, nâng lên đã xác thực.

Hạn mức

Giao dịch nhập không tính vào hạn mức giao dịch của gói; quy tắc đầy đủ ở khái niệm cơ bản.

Các lỗi thường gặp

HTTP	Mã lỗi	Thử lại	Ý nghĩa
400	`idempotency_key_required`	không	Thiếu header Idempotency-Key
422	`idempotency_key_reused`	không	Idempotency-Key đã dùng cho yêu cầu khác
409	`idempotency_in_flight`	có	Yêu cầu cùng Idempotency-Key đang xử lý
422	`validation_failed`	không	Dữ liệu không hợp lệ
413	`payload_too_large`	không	Nội dung quá lớn