URD: Thuế & Hóa đơn

Module	CORE-10	Phiên bản	v0.4
Trạng thái	In-progress	Ngày	2026-05-30

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. Yêu cầu chức năng

Một bảng cho mỗi khu vực chức năng. Mã <AREA> khớp với ID của test case. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

5.1 Định danh thuế (TAX)

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

5.2 Nhóm thuế (GRP)

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

5.3 Cấu hình hóa đơn (CFG)

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

5.4 Vòng đời hóa đơn (INV)

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

5.5 Yêu cầu hóa đơn & Yêu cầu của người mua (REQ)

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

5.6 Chế độ phát hành (MOD)

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

6. Tiêu chí 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-02: 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

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-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ỏ

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	Di trú	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