URD: Thuế & Hóa đơn

Module	CORE-10	Phiên bản	v0.5
Trạng thái	In-progress	Ngày	2026-06-04

Tài liệu nghiệp vụ. URD này là danh sách tính năng của Thuế & Hóa đơn - mỗi tính năng dưới đây là một Khu vực chức năng (<AREA>). Cùng <AREA> đó là khóa cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

1. Mục đích

Định nghĩa các yêu cầu hướng người dùng cho việc giữ tuân thủ thuế khi bán hàng. Module ghi nhận định danh thuế của merchant, áp đúng quy tắc thuế lên sản phẩm, và biến một thanh toán đã hoàn tất thành hóa đơn điện tử hợp pháp của Việt Nam có thể giao cho người mua và nộp lên cơ quan thuế - kèm điều chỉnh, hủy, và khách tự yêu cầu hóa đơn trên đường đi.

2. Phạm vi

Bao gồm	Loại trừ
Định danh thuế người bán (mã số thuế / MST, tên, địa chỉ)	Sổ đăng ký mã số thuế chính thức (cơ quan thuế sở hữu)
Mẫu quy tắc nhóm thuế áp lên sản phẩm	Tính thuế suất tại thời điểm bán (engine định giá)
Dữ liệu tham chiếu hành chính VN (tỉnh, phường, đơn vị)	Render PDF của hóa đơn (phía nhà cung cấp)
Hồ sơ hóa đơn merchant + thông tin xác thực nhà cung cấp đã mã hóa	Thu thanh toán (module Payment)
Vòng đời phát hành hóa đơn (vào hàng đợi → đã phát hành / thất bại / đã hủy)	Vòng đời đơn hàng (module Đơn hàng)
Tích hợp nhà cung cấp: VNPAY / VNIS qua iiapi + T-VAN	Đa nhà cung cấp ngoài bộ iiapi/T-VAN hiện tại
Nộp lên cơ quan thuế (CQT) và theo dõi trạng thái	Tự động hóa kê khai / nộp thuế
Điều chỉnh, thay thế, hủy hóa đơn	Đối soát liên-merchant
Yêu cầu hóa đơn + khách tự yêu cầu (QR)
Định tuyến kênh + chia sẻ hồ sơ cho nhiều chi nhánh
Dấu vết kiểm toán bất biến cho mọi sự kiện hóa đơn

3. Định nghĩa

Thuật ngữ	Định nghĩa
Định danh thuế (MST)	Mã số đăng ký thuế, tên doanh nghiệp, và địa chỉ của người bán được in làm người bán trên mọi hóa đơn
Nhóm thuế	Một mẫu quy tắc tái dùng quyết định thuế nào áp lên sản phẩm nào
Hồ sơ hóa đơn	Thiết lập hóa đơn của một merchant liên kết định danh thuế với một nhà cung cấp
Nhà cung cấp	Cổng hóa đơn điện tử (hiện tại VNPAY / VNIS qua iiapi) phát hành hóa đơn hợp pháp
Cơ quan thuế (CQT)	Cơ quan thuế Việt Nam, tiếp cận qua mạng T-VAN để nộp và xác thực
Phát hành	Hành động biến một đơn hàng thành hóa đơn điện tử hợp pháp có đánh số qua một nhà cung cấp
Yêu cầu của người mua	Người mua tự lấy hóa đơn của mình bằng cách quét QR trên biên lai trước một thời hạn
Dấu vết kiểm toán	Bản ghi bất biến của mọi thay đổi trạng thái mà một hóa đơn trải qua

4. Mô hình khái niệm

Chỉ mang tính khái niệm - schema đầy đủ nằm trong mô hình miền nhà phát triển của taxation và invoice.

5. Danh mục tính năng

Danh sách tính năng của module này. Mỗi dòng là một tính năng (một Khu vực chức năng). Chi tiết ở §6. Phản chiếu trong danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
TAX	Định danh thuế	P1	Built	High
GRP	Nhóm thuế	P1	Built	High
CFG	Cấu hình hóa đơn	P1	Built	High
INV	Vòng đời hóa đơn	P1	Built	High
REQ	Yêu cầu hóa đơn & Khách tự yêu cầu	P1	Built	High
MOD	Chế độ phát hành	P1	Built	High
DCL	Kê khai thuế (HKD 1-3 tỷ)	P2	Planned	High
ISS	Trải nghiệm xuất hóa đơn	P2	Planned	High

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Một mục con cho mỗi tính năng, theo thứ tự danh mục. Mỗi tính năng giữ mô tả, yêu cầu, và tiêu chí chấp nhận cùng nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

TAX - Định danh thuế Built

Feature ID: tax/TAX · Phase: P1 · PRDs: - · Dev: @nx/taxation

Làm gì cho người dùng: chủ đăng ký mã số thuế (MST), tên doanh nghiệp, và địa chỉ của merchant để in làm người bán trên mọi hóa đơn đã phát hành, kèm tra cứu tỉnh/phường VN khi nhập địa chỉ.

Yêu cầu

ID	P	Yêu cầu
URD-TAX-001	M	Đăng ký định danh thuế người bán (MST, tên doanh nghiệp, địa chỉ) dùng trên hóa đơn đã phát hành
URD-TAX-002	M	Tra cứu tỉnh, phường, và đơn vị hành chính Việt Nam khi nhập địa chỉ
URD-TAX-003	S	Mã số thuế được xác thực đúng định dạng Việt Nam trước khi được chấp nhận

Chấp nhận

AC-TAX-01: Đăng ký định danh thuế người bán

Cho	Khi	Thì
Một merchant nhập thông tin thuế	Định danh thuế người bán (MST, tên, địa chỉ) được lưu	Nó được dùng làm người bán trên hóa đơn đã phát hành

GRP - Nhóm thuế Built

Feature ID: tax/GRP · Phase: P1 · PRDs: - · Dev: @nx/taxation

Làm gì cho người dùng: chủ định nghĩa mẫu nhóm thuế tái dùng tự động áp đúng thuế lên các sản phẩm khớp, và điều hòa thuế đó mỗi khi một sản phẩm thay đổi.

Yêu cầu

ID	P	Yêu cầu
URD-GRP-001	M	Định nghĩa một mẫu quy tắc nhóm thuế phân loại thuế nào áp lên sản phẩm nào
URD-GRP-002	M	Áp một nhóm thuế cấp đúng thuế lên các sản phẩm khớp của nó
URD-GRP-003	M	Thay đổi hoặc gỡ một sản phẩm điều hòa thuế đã áp của nó tự động
URD-GRP-004	S	Một nhóm thuế chỉ dùng được khi tương thích với phương pháp thuế của merchant

Chấp nhận

AC-GRP-01: Cấp thuế cho nhóm thuế

Cho	Khi	Thì
Một nhóm thuế khớp một sản phẩm	Sản phẩm được tạo hoặc cập nhật	Đúng thuế được áp lên sản phẩm đó
Một sản phẩm bị gỡ	Thay đổi được xử lý	Thuế đã áp của nó được điều hòa / gỡ bỏ

CFG - Cấu hình hóa đơn Built

Feature ID: tax/CFG · Phase: P1 · PRDs: - · Dev: @nx/invoice

Làm gì cho người dùng: chủ thiết lập việc xuất hóa đơn của merchant - kết nối một nhà cung cấp với thông tin xác thực mã hóa, cấu hình số/danh mục/chính sách theo từng loại hóa đơn, định tuyến từng kênh bán tới một cấu hình, và chia sẻ hồ sơ cho nhiều chi nhánh.

Yêu cầu

ID	P	Yêu cầu
URD-CFG-001	M	Tạo một hồ sơ hóa đơn merchant liên kết với định danh thuế người bán
URD-CFG-002	M	Kết nối một nhà cung cấp (VNPAY / VNIS qua iiapi) với thông tin xác thực lưu mã hóa
URD-CFG-003	M	Cấu hình theo từng loại hóa đơn: số, danh mục, phương pháp thuế, và chính sách phát hành
URD-CFG-004	M	Định tuyến từng kênh bán tới cấu hình nhà cung cấp phát hành hóa đơn của nó
URD-CFG-005	M	Cấu hình chính sách thử lại (số lần tối đa + lịch trễ) cho phát hành thất bại
URD-CFG-006	S	Chia sẻ một hồ sơ hóa đơn cho nhiều chi nhánh (riêng tư / mọi chi nhánh / whitelist)
URD-CFG-007	S	Wizard onboarding có hướng dẫn để thiết lập nhà cung cấp từng bước

Chấp nhận

AC-CFG-01: Kết nối một nhà cung cấp

Cho	Khi	Thì
Một hồ sơ hóa đơn liên kết với định danh thuế người bán	Một nhà cung cấp được kết nối kèm thông tin xác thực	Thông tin xác thực được lưu mã hóa và hồ sơ có thể phát hành hóa đơn
Một kênh bán	Nó được định tuyến tới một cấu hình nhà cung cấp	Cấu hình đó phát hành hóa đơn của kênh

INV - Vòng đời hóa đơn Built

Feature ID: tax/INV · Phase: P1 · PRDs: PRD-INV-001 · PRD-INV-003 · Dev: @nx/invoice

Làm gì cho người dùng: một thanh toán đã hoàn tất đưa vào hàng đợi và phát hành hóa đơn điện tử hợp pháp qua nhà cung cấp, thu số của nó và mã cơ quan thuế, thử lại khi thất bại, nộp lên cơ quan thuế, và ghi mọi sự kiện vào dấu vết kiểm toán bất biến - kèm điều chỉnh, thay thế, và hủy.

Yêu cầu

ID	P	Yêu cầu
URD-INV-001	M	Đưa một hóa đơn vào hàng đợi phát hành tự động khi thanh toán thành công
URD-INV-002	M	Phát hành hóa đơn qua nhà cung cấp và thu số của nó + mã cơ quan thuế
URD-INV-003	M	Theo dõi trạng thái hóa đơn (pending → processing → success / failed / cancelled)
URD-INV-004	M	Thử lại một phát hành thất bại theo chính sách đã cấu hình
URD-INV-005	M	Nộp hóa đơn đã phát hành lên cơ quan thuế (CQT qua T-VAN) khi bật, và theo dõi trạng thái
URD-INV-006	M	Ghi một mục dấu vết kiểm toán bất biến cho mọi sự kiện hóa đơn
URD-INV-007	M	Điều chỉnh một hóa đơn đã phát hành (bản sửa liên kết tới bản gốc)
URD-INV-008	M	Thay thế hoặc hủy một hóa đơn đã phát hành kèm lý do
URD-INV-009	S	Xử lý webhook đầu vào của nhà cung cấp với xác thực chữ ký để cập nhật trạng thái
URD-INV-010	M	Chỉ một hóa đơn đã phát hành (SUCCESS) mới được điều chỉnh hoặc hủy; bản sửa luôn liên kết ngược về bản gốc (PRD-INV-003)
URD-INV-011	M	Một điều chỉnh tạo một hóa đơn sửa mới (nguồn adjustment) liên kết tới bản gốc và được xử lý bất đồng bộ qua hàng đợi phát hành, được giành dưới một khóa lạc quan để một job thử lại phát hành nó nhiều nhất một lần
URD-INV-012	M	Bản sửa mang dòng hàng, mô tả, và tổng riêng của nó, và được phát hành qua nhà cung cấp tham chiếu lần phát hành gốc
URD-INV-013	M	Điều chỉnh được hỗ trợ cho các loại hóa đơn VAT, POS-VAT, và ticket-VAT; một loại không hỗ trợ bị từ chối
URD-INV-014	M	Hủy đánh dấu hóa đơn là đã hủy kèm lý do bắt buộc; với một hóa đơn đã phát hành còn gọi hủy phía nhà cung cấp
URD-INV-015	M	Hủy là lũy đẳng (hủy lại là no-op) và bị chặn khi hóa đơn đang được xử lý
URD-INV-016	S	Mọi điều chỉnh và hủy ghi một mục kiểm toán bất biến và thông báo cho các client đang kết nối thời gian thực

Chấp nhận

AC-INV-01: Phát hành khi thanh toán

Cho	Khi	Thì
Một thanh toán thành công cho một đơn	Sự kiện thanh toán-thành-công được nhận	Một hóa đơn được đưa vào hàng đợi phát hành
Nhà cung cấp chấp nhận	Phát hành hoàn tất	Số hóa đơn + mã cơ quan thuế được ghi nhận; trạng thái là success
Nhà cung cấp từ chối	Phát hành thất bại	Một lần thử lại được lên lịch theo chính sách
Vượt số lần thử tối đa	Lần thử cuối thất bại	Trạng thái là failed; thất bại được ghi vào dấu vết kiểm toán

AC-INV-03: Nộp lên cơ quan thuế

Cho	Khi	Thì
Nộp lên cơ quan thuế được bật	Một hóa đơn được phát hành	Hóa đơn được nộp lên CQT qua T-VAN
CQT chấp nhận	Phản hồi trả về	Trạng thái hóa đơn được cập nhật thành đã chấp nhận
CQT từ chối	Phản hồi trả về	Trạng thái ghi nhận lý do từ chối

AC-INV-04: Điều chỉnh một hóa đơn đã phát hành

Cho	Khi	Thì
Một hóa đơn đã phát hành (SUCCESS)	Một điều chỉnh được yêu cầu với một mô tả và các dòng điều chỉnh	Một hóa đơn sửa liên kết được tạo (PENDING) và đưa vào hàng đợi
Điều chỉnh trong hàng đợi được xử lý	Worker phát hành nó qua nhà cung cấp tham chiếu bản gốc	Trạng thái của nó thành SUCCESS, một mục kiểm toán được ghi, và client cập nhật trực tiếp
Bản gốc không ở trạng thái SUCCESS	Một điều chỉnh được yêu cầu	Bị từ chối - chỉ hóa đơn đã phát hành mới được điều chỉnh

AC-INV-05: Hủy một hóa đơn

Cho	Khi	Thì
Một hóa đơn đã phát hành (SUCCESS)	Hủy được yêu cầu kèm lý do	Hủy phía nhà cung cấp được gọi, hóa đơn được đánh dấu đã hủy, và lý do + một mục kiểm toán được ghi
Một hóa đơn đang được xử lý	Hủy được yêu cầu	Bị từ chối cho tới khi xử lý hoàn tất
Một hóa đơn đã hủy	Hủy được yêu cầu lại	Yêu cầu là no-op (lũy đẳng)

REQ - Yêu cầu hóa đơn & Khách tự yêu cầu Built

Feature ID: tax/REQ · Phase: P1 · PRDs: - · Dev: @nx/invoice

Làm gì cho người dùng: thu ngân thu thông tin người mua và phát hành hóa đơn trực tiếp, hoặc người mua tự phục vụ qua QR biên lai với token yêu cầu và thời hạn; hóa đơn và link yêu cầu được giao qua QR, email, hoặc SMS.

Yêu cầu

ID	P	Yêu cầu
URD-REQ-001	M	Thu thông tin người mua (tên, mã số thuế, địa chỉ, email) cho một hóa đơn
URD-REQ-002	M	Luồng trực tiếp: thu ngân thu thông tin người mua và phát hành hóa đơn
URD-REQ-003	S	Khách tự phục vụ: QR biên lai với token yêu cầu và thời hạn
URD-REQ-004	S	Vòng đời yêu cầu: pending → claimed / expired
URD-REQ-005	S	Giao hóa đơn / link yêu cầu qua QR biên lai, email, hoặc SMS

Chấp nhận

AC-REQ-01: Khách tự yêu cầu hóa đơn

Cho	Khi	Thì
Một biên lai với QR yêu cầu hợp lệ	Người mua mở link trước thời hạn	Người mua có thể gửi thông tin của mình
Người mua gửi thông tin	Gửi thành công	Hóa đơn được phát hành với thông tin người mua
Thời hạn đã qua	Người mua mở link	Yêu cầu đã hết hạn và không hóa đơn nào được phát hành

MOD - Chế độ phát hành Built

Feature ID: tax/MOD · Phase: P1 · PRDs: - · Dev: @nx/invoice

Làm gì cho người dùng: hóa đơn có thể được phát hành thời gian thực khi thanh toán, thủ công bởi thu ngân tại quầy, theo lô đã lên lịch, hoặc do người mua tự yêu cầu qua QR.

Yêu cầu

ID	P	Yêu cầu
URD-MOD-001	M	Thời gian thực: phát hành ngay khi thanh toán
URD-MOD-002	S	Thủ công: thu ngân khởi tạo phát hành tại quầy
URD-MOD-003	S	Theo lịch: phát hành theo lô bởi một job đã lên lịch
URD-MOD-004	S	Khách tự phục vụ: người mua yêu cầu và phát hành qua QR

Chấp nhận

AC-MOD-01: Phát hành thời gian thực

Cho	Khi	Thì
Chế độ thời gian thực được cấu hình	Một thanh toán thành công	Hóa đơn được phát hành ngay

DCL - Kê khai Thuế (HKD 1-3 tỷ) Planned

Mã tính năng: tax/DCL · Phase: P2 (T7-T8) · PRDs: PRD-DCL-001 · Dev: @nx/ledger · @nx/taxation

Mang lại gì cho người dùng: hộ kinh doanh dải 1-3 tỷ giữ sổ thuế và nộp thuế ngay trong KICKO - sổ S2a từ doanh thu thật, TNCN theo thuế suất ngành, tờ khai 01/CNKD chuẩn, nộp qua T-VAN - không cần kế toán.

Yêu cầu

ID	P	Yêu cầu
URD-DCL-001	M	Sổ S2a phản ánh doanh thu thật của merchant theo nhóm thuế
URD-DCL-002	M	Thuế suất xác định theo ngành của merchant (mapping cấu hình được)
URD-DCL-003	M	TNCN tính từ doanh thu theo thuế suất áp dụng
URD-DCL-004	M	Tờ khai 01/CNKD sinh được (PDF/XML) cho một kỳ
URD-DCL-005	M	Tờ khai nộp qua T-VAN, theo dõi trạng thái đến khi CQT xác nhận
URD-DCL-006	M	Màn hình client: xem sổ → preview 01/CNKD → nộp
URD-DCL-007	S	Lưu lịch sử nộp theo kỳ

Nghiệm thu

AC-DCL-01: Trọn một kỳ thuế

Given	When	Then
Merchant 1-3 tỷ với một tháng doanh thu	Xem S2a, preview và nộp 01/CNKD	T-VAN nhận; trạng thái tới "đã xác nhận"; hồ sơ lưu theo kỳ

ISS - Trải nghiệm Xuất Hóa đơn Planned

Mã tính năng: tax/ISS · Phase: P2 (T7) · PRDs: PRD-ISS-001 · Dev: @nx/invoice

Mang lại gì cho người dùng: merchant thực sự xuất hóa đơn điện tử trong vận hành hằng ngày - một thao tác tại POS lúc thanh toán, một nơi xem và quản lý mọi hóa đơn, sửa sai bằng hóa đơn điều chỉnh/thay thế, và HĐ VAT công ty mang MST người mua. (Vòng đời backend và tích hợp nhà cung cấp đã xây - increment này đưa chúng đến tay người dùng.)

Yêu cầu

ID	P	Yêu cầu
URD-ISS-001	M	Thu ngân xuất HĐĐT ngay tại POS lúc thanh toán (MTT) - một thao tác
URD-ISS-002	M	Màn hóa đơn: danh sách + chi tiết kèm trạng thái nhà cung cấp và mã CQT
URD-ISS-003	M	Xuất được hóa đơn điều chỉnh và thay thế cho hóa đơn đã phát hành
URD-ISS-004	M	HĐ VAT công ty mang MST + tên công ty người mua
URD-ISS-005	M	Xuất lỗi phải nhìn thấy được và thử lại được
URD-ISS-006	S	Hóa đơn đã xuất in/chia sẻ được cho khách (link/PDF)
URD-ISS-007	S	Kết nối nhà cung cấp (VNPAY) kiểm chứng được e2e từ màn cấu hình

Nghiệm thu

AC-ISS-01: Xuất trong luồng thật

Given	When	Then
Một đơn đã thanh toán tại POS	Thu ngân xuất hóa đơn	Hóa đơn phát hành với số + mã CQT, hiện trong danh sách
Người mua là KH doanh nghiệp có MST	Hóa đơn được xuất	Mang MST và tên công ty người mua
Nhà cung cấp lỗi	Chạy xuất hóa đơn	Lỗi nhìn thấy được và thử lại được, không phải tạo lại đơn

7. Ràng buộc & Phi mục tiêu

Ràng buộc

ID	Ràng buộc
C-01	Một hồ sơ hóa đơn hoạt động cho mỗi merchant
C-02	Một ánh xạ cấu hình hoạt động cho mỗi kênh bán
C-03	Thông tin xác thực nhà cung cấp được lưu mã hóa
C-04	Dấu vết kiểm toán hóa đơn là bất biến
C-05	Một token yêu cầu là duy nhất và gắn với một yêu cầu hóa đơn duy nhất
C-06	Mọi bản ghi dùng xóa-mềm; không có gì bị xóa vật lý

Phi mục tiêu

• Nhiều nhà cung cấp hóa đơn ngoài bộ iiapi / T-VAN hiện tại
• Render PDF của hóa đơn (do nhà cung cấp tạo)
• Tính thuế suất tại thời điểm bán (do engine định giá sở hữu)
• Tự động hóa kê khai / nộp thuế

8. Lịch sử phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do - Product Owner	User story ban đầu	v0.1
2026-02-27	QE	Đánh giá cấp code, điều chỉnh yêu cầu	v0.2
2026-04-16	P. Do - Product Owner	Mô hình VNPAY IIAPI + T-VAN + khách-yêu-cầu	v0.3
2026-05-30	Migration	Tái cấu trúc theo quy ước tài liệu module; mã AREA căn lại theo build taxation + invoice	v0.4
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine)	v0.5