Settlement sàn thương mại điện tử và sổ nghĩa vụ đa bên

~9 phút đọc

Sắp ra mắt

Tính năng này chưa có trong sản phẩm. Trang mô tả hướng đi dự kiến và có thể thay đổi trước khi phát hành.

Khi kinh doanh trên các sàn thương mại điện tử (Shopee, TikTok Shop, Lazada), tiền sàn chuyển về tài khoản ngân hàng của bạn là khoản gộp (N:1) sau khi cấn trừ nhiều tầng chi phí: phí cố định, phí dịch vụ, phí xử lý thanh toán, voucher shop, trợ giá vận chuyển, thuế khấu trừ và phí xử lý đơn hoàn. Sau đó, doanh nghiệp còn phải thực hiện phân bổ nghĩa vụ cho các bên: hãng ký gửi, đại lý bán sỉ hoặc cộng tác viên (CTV).

Màn hình Settlement sàn (/settlement) giải quyết bài toán đối soát và ghi sổ nghĩa vụ đó, hoàn toàn theo hình thái dữ liệu thuần túy (data-only).

Kiến trúc dòng dữ liệu Settlement

flowchart LR
  XL[Statement sàn Excel/API] --> P[Payout sàn]
  TX[Giao dịch NH đã xác thực] --> M{Bộ so khớp L1-L4}
  P --> M
  M -- Khớp 0 ₫ --> ALLOC[Gạch nợ chờ duyệt]
  M -- Lệch --> VAR[Chênh lệch và AI giải thích]
  ORD[Đơn hàng sàn] --> RULE[Quy tắc chia có phiên bản]
  RULE --> OBL[Sổ nghĩa vụ: Phải thu / Phải trả]
  ALLOC --> OBL
  OBL --> AG[Báo cáo tuổi nợ và Bảng kê đối soát HMAC]

5 Panel chính trên giao diện

Màn hình /settlement được thiết kế theo wireframe chuẩn của Dòng Tiền Pro với 5 panel độc lập:

1. Đối tác & hãng (`partners`)

Quản lý 4 nhóm đối tác chính:

Sàn TMĐT (marketplace): Shopee, TikTok Shop, Lazada gắn với từng gian hàng và tài khoản nhận payout.
Người bán / Đại lý (agent): Đối tác mua sỉ, áp dụng công nợ (ví dụ: công nợ 30 ngày) gắn với hoá đơn trên hoadon.pro.
Hãng ký gửi (brand_consignor): Hãng cung cấp hàng hoá, phân chia doanh thu theo tỷ lệ (ví dụ: 70/30, 75/25).
Cộng tác viên (ctv_group): Nhóm cá nhân nhận hoa hồng theo mã CTV (ví dụ: 6% giá bán trước voucher).

Bảo mật dữ liệu cá nhân (PII): Thông tin CCCD, mã số thuế cá nhân và số tài khoản của thành viên CTV được mã hoá ở cấp cơ sở dữ liệu (AES-256-GCM). Giao diện mặc định che dạng •••last4. Chỉ người dùng có quyền account.reveal mới có thể bấm Hiện đầy đủ, và hành động này được ghi lại trong nhật ký kiểm toán hệ thống. Đối tác CTV có khoản thanh toán vượt 2.000.000 ₫/tháng sẽ được gắn cờ cảnh báo khấu trừ thuế TNCN.

2. Sổ nghĩa vụ (`ledger`)

Theo dõi chi tiết các khoản Phải thu và Phải trả:

Mỗi nghĩa vụ mang mã chuẩn OB-YYMM-NNNN (với YYMM là tháng phát sinh nghĩa vụ).
Trạng thái nghĩa vụ: not_due (Chưa đến hạn), awaiting_payout (Chờ payout), partially_settled (Một phần), settled (Tất toán), variance (Chênh lệch), overdue (Quá hạn).
Mỗi nghĩa vụ có Nội dung chuyển khoản gợi ý mang mã nhận diện duy nhất DTP (ví dụ: DTP8X2N4K TT KY GUI T09 SANG VIET) để đối tác ghi vào nội dung chuyển tiền, giúp hệ thống tự động nhận dạng và đề xuất gạch nợ.
Hỗ trợ gạch nợ một phần, gộp nhiều nghĩa vụ hoặc trả thừa (overpay_handling).

3. Đối soát payout sàn (`payouts`)

Đối chiếu từng khoản tiền sàn báo sẽ chuyển (statement) với giao dịch thực tế vào tài khoản ngân hàng:

5 trạng thái payout:
- matched: Khớp tuyệt đối 0 ₫ chênh lệch và giao dịch ngân hàng đã xác thực.
- variance: Có chênh lệch vượt ngưỡng dung sai (allowable_drift).
- awaiting_payout: Đã có statement nhưng tiền chưa về tài khoản ngân hàng.
- provisional: Khoản tiền mới ghi nhận qua nguồn SMS hoặc email, chưa có sao kê hoặc Open API xác thực (không cho phép gạch nợ).
- orphan_credit: Tiền sàn đã chuyển vào ngân hàng nhưng chưa có statement tương ứng (cho phép chọn statement để gán kèm lý do audit).

4. Quy tắc chia (`rules`)

Quy tắc phân chia doanh thu cho hãng hoặc CTV:

Cơ sở tính (basis): net_after_platform_fee (Giá bán sau phí sàn), gross (Giá bán gốc), gross_profit (Lợi nhuận gộp), pre_voucher (Giá trước voucher), list_price_discount (Chiết khấu giá niêm yết).
Tỷ lệ (pct_bp): Tính theo đơn vị basis point (ví dụ: 7.000 bp = 70%). Quy tắc làm tròn: làm tròn xuống từng đơn floor(amount · bp / 10000), phần dư thuộc về công ty giữ tiền.
Thời điểm kích hoạt (trigger): on_delivered (khi giao hàng thành công), on_payout (khi payout sàn khớp), after_return_window_7d (hết hạn đổi trả 7 ngày), monthly_close (cuối tháng), day_5_next_month (ngày 5 tháng sau), invoice_net_30 (30 ngày từ ngày xuất HĐ).
Phiên bản & Maker-Checker: Quy tắc có hiệu lực theo ngày (effective_from), không áp dụng ngược cho nghĩa vụ đã phát sinh. Phiên bản mới chờ duyệt thì phiên bản cũ vẫn tính toán bình thường.

5. Báo cáo & Lịch tự động (`reports`)

4 mẫu báo cáo: Công nợ theo đối tác, Đối soát payout theo kỳ, Bảng kê gửi hãng, Phí sàn thực trả so với biểu phí công bố.
Bảng kê gửi hãng có mã băm HMAC: Mỗi bảng kê đính kèm mã băm statement_hash = HMAC-SHA256(key, statement_id || partner_id || net || item_count) và dòng chữ "Số liệu đối soát, không phải chứng từ thanh toán".
Phân tích tuổi nợ: Chưa đến hạn, Quá hạn 1–30 ngày, Quá hạn trên 30 ngày.
Tiền sắp về 7 ngày: Ước tính dòng tiền về ngân hàng để cung cấp dữ liệu cho dự báo dòng tiền.

4 Tab Drawer chi tiết

Hệ thống tích hợp 4 loại tab drawer chuẩn với phím tắt và khả năng mở song song:

partner: Xem thông tin đối tác, tổng quan công nợ, danh sách nghĩa vụ, danh sách CTV và form tạo/sửa đối tác có kiểm tra mã số thuế tự động qua masothue.pro.
obligation: Xem chi tiết cấu thành nghĩa vụ, tiến độ gạch nợ, danh sách giao dịch ngân hàng đã gạch, nội dung CK gợi ý và nhật ký append-only.
payout: Xem bảng kê đối soát chi tiết, nguồn statement, giao dịch ngân hàng khớp, giải thích chênh lệch (quy tắc tất định + AI), danh sách đơn hàng và form import statement.
split-rule: Xem quy tắc chia, máy tính minh hoạ đơn hàng mẫu 1.250.000 ₫, lịch sử phiên bản và form tạo phiên bản mới có maker-checker.

Quy trình khớp payout 4 mức (L1–L4)

Mức 1 (L1): Mã statement nằm trong nội dung chuyển khoản của ngân hàng.
Mức 2 (L2): Số tiền chuyển khoản trùng khớp tuyệt đối với số tiền thực nhận trên statement, đúng tài khoản đích và thời gian giao dịch trong khoảng [ngày dự kiến, +48 giờ].
Mức 3 (L3): Chênh lệch nhỏ hơn hoặc bằng dung sai cho phép (allowable_drift, mặc định 0 ₫, có thể cấu hình bằng phí chuyển liên ngân hàng 2.200 ₫ – 5.500 ₫). Trạng thái chuyển thành variance kèm bút toán trừ phí ngân hàng.
Mức 4 (L4): Không khớp; đưa vào hàng đợi rà soát thủ công.

Giải thích chênh lệch: Tất định trước, AI gợi ý sau

Khi payout bị lệch:

Hệ thống chạy các quy tắc tất định trước: tổng phí xử lý đơn hoàn, voucher phát sinh, trợ giá vận chuyển bổ sung, thuế khấu trừ hoặc phí chuyển ngân hàng.
Nếu các quy tắc tất định chưa giải thích hết 100% chênh lệch, hệ thống gọi tác vụ AI reconcile_suggest (dữ liệu gửi đi đã được che STK/thông tin nhạy cảm) để đưa ra nguyên nhân nghi ngờ kèm tỷ lệ tin cậy (ví dụ: Nghi ngờ phí đơn hoàn #577812 bị trừ trước kỳ · 82%).
AI chỉ đóng vai trò gợi ý, người dùng bấm Ghi nhận chênh lệch để gửi yêu cầu phê duyệt tạo nghĩa vụ phải thu bù từ sàn qua maker-checker.

Quy tắc chia chồng lấn

Khi lưu quy tắc hoặc phiên bản mới, hệ thống so điều kiện (hãng, SKU theo tiền tố, sàn, cửa hàng, mã CTV) với các quy tắc đang hiệu lực cùng loại và trả lint_warnings:

shadowing: hai quy tắc cùng khớp một đơn nhưng khác mức ưu tiên hoặc ngày hiệu lực; quy tắc ưu tiên/ngày hiệu lực muộn hơn thắng. Chỉ là cảnh báo, vẫn lưu và duyệt được.
ambiguous: cùng ưu tiên và cùng ngày hiệu lực nên không xác định được quy tắc nào thắng. Vẫn lưu nháp, nhưng duyệt bị từ chối (409 conflict) cho tới khi đổi điều kiện, ưu tiên hoặc ngày hiệu lực.

Báo cáo PDF và Excel

Ba báo cáo (tuổi nợ phải thu/phải trả, đối soát payout, bảng kê đối tác) và báo cáo đối chiếu phí sàn xuất được cả Excel và PDF (GET /v1/settlement/reports/{kind}?format=xlsx|pdf, hoặc nút Excel / PDF trên tab Báo cáo). PDF là A4 ngang, tiêu đề bảng lặp lại ở mỗi trang, nhúng phông chữ nên hiển thị đúng tiếng Việt, và cùng số liệu với bản Excel (cùng một bảng nguồn). Tệp lưu bất biến, chỉ tải được khi đã đăng nhập hoặc có khoá API quyền settlement.read, và hết hạn sau 7 ngày.

Chính sách Gạch nợ & Maker-Checker (D41)

Nguyên tắc Maker ≠ Checker: Người tạo đề xuất gạch nợ không được phép tự duyệt đề xuất của chính mình.
Ngoại lệ D41 (Tổ chức 1 người duyệt): Đối với tổ chức chỉ có 1 người duyệt và đã bật cờ self_approval:
- Cho phép chính chủ tự duyệt gạch nợ khi và chỉ khi: khoản khớp đúng 100% (chênh lệch 0 ₫), nguồn giao dịch đã xác thực và giá trị dưới ngưỡng an toàn (mặc định 20.000.000 ₫).
- Hành động được ghi nhận kiểm toán rõ ràng: approval.self_approved.
- Các trường hợp: trên ngưỡng, trả thừa, đối tác mới hoặc quy tắc chia mới bắt buộc phải có người thứ hai phê duyệt. Khi tổ chức thêm người duyệt thứ hai, chế độ tự duyệt sẽ tự động vô hiệu hoá.

Phím tắt bàn phím

n: Mở form tạo mới theo ngữ cảnh tab hiện tại (thêm đối tác ở tab Đối tác, tạo quy tắc ở tab Quy tắc, import statement ở tab Payouts/Ledger).
r: Tải lại dữ liệu trang.
/: Di chuyển tiêu điểm vào ô tìm kiếm.
j / k: Di chuyển lên / xuống giữa các dòng trong bảng.
o hoặc Enter: Mở tab drawer chi tiết của dòng được chọn.
e: Xuất báo cáo tổng hợp.
1 – 5: Chuyển nhanh giữa 5 tab: Đối tác & hãng (1), Sổ nghĩa vụ (2), Đối soát payout (3), Quy tắc chia (4), Báo cáo (5).