Thuế & Hóa đơn Phase A In-progress
Giữ cho merchant tuân thủ pháp luật khi bán hàng: ghi nhận định danh thuế của người bán, á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ể gửi cho người mua và cơ quan thuế. Được dùng bởi chủ doanh nghiệp (thiết lập thuế và hóa đơn), thu ngân (phát hành hóa đơn tại quầy), và người mua (tự yêu cầu hóa đơn của mình).
1. Định danh
| Thuộc tính | Giá trị |
|---|---|
| Module ID | CORE-10 |
| Tier | Core |
| Trạng thái | In-progress |
| Phase | P1 (hóa đơn điện tử + nộp lên cơ quan thuế) |
| Ưu tiên | HIGH |
| Người dùng chính | Chủ / Quản lý (thiết lập), Thu ngân (phát hành), Người mua (tự yêu cầu) |
Hai dịch vụ, một module nghiệp vụ. Áp thuế lên sản phẩm và phát hành hóa đơn là hai nửa của cùng một câu chuyện tuân thủ. Dịch vụ Taxation sở hữu quy tắc nhóm thuế và đẩy đúng thuế lên từng sản phẩm; dịch vụ Invoice phát hành hóa đơn điện tử hợp pháp qua một nhà cung cấp và cơ quan thuế. Kết nối tới cơ quan thuế chạy qua hai adapter tích hợp — iiapi (cổng nhà cung cấp) và t-van (mạng cơ quan thuế). Xem §5 Backend Packages.
2. Mục đích & Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Định danh thuế người bán (mã số thuế / MST, tên doanh nghiệp, địa chỉ) | Sổ đăng ký mã số thuế chính thức (do cơ quan thuế cấp) |
| 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 (do engine Sản phẩm / định giá sở hữu) |
| Dữ liệu tham chiếu hành chính Việt Nam (tỉnh, phường, đơn vị) | Render PDF của hóa đơn (do nhà cung cấp tạo) |
| Hồ sơ hóa đơn merchant + thông tin xác thực nhà cung cấp (mã hóa) | Thu thanh toán (do Payment sở hữu) |
| Phát hành hóa đơn (VAT, bán hàng, POS, vé, vận chuyển nội bộ) | Vòng đời đơn hàng (do Đơn hàng sở hữu) |
| 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ế, và hủy hóa đơn | Đối soát liên-merchant |
| Khách tự yêu cầu hóa đơn (QR + token + thời hạn) | |
| Dấu vết kiểm toán bất biến cho mọi sự kiện hóa đơn |
3. Năng lực
| Năng lực | Người dùng có thể làm gì | Trạng thái |
|---|---|---|
| Định danh thuế người bán | Chủ đăng ký mã số thuế (MST), tên, và địa chỉ của merchant dùng làm người bán trên hóa đơn | Built |
| Quy tắc nhóm thuế | Chủ định nghĩa mẫu nhóm thuế tự động áp đúng thuế lên sản phẩm khớp | Built |
| Dữ liệu tham chiếu VN | Tra cứu tỉnh / phường / đơn vị hành chính khi nhập địa chỉ | Built |
| Hồ sơ hóa đơn & nhà cung cấp | Chủ kết nối một nhà cung cấp VNPAY / VNIS với thông tin xác thực mã hóa và chính sách số/phát hành | Built |
| Định tuyến kênh | Chủ ánh xạ từng kênh bán / principal tới cấu hình nhà cung cấp phát hành hóa đơn của nó | Built |
| Chia sẻ hồ sơ | Chủ chia sẻ một hồ sơ hóa đơn cho nhiều chi nhánh (riêng tư / mọi chi nhánh / whitelist) | Built |
| Wizard onboarding | Thiết lập nhà cung cấp từng bước có hướng dẫn | Built |
| Tự phát hành khi thanh toán | Một thanh toán hoàn tất tự động đưa vào hàng đợi và phát hành hóa đơn | Built |
| Phát hành thủ công / theo lịch | Thu ngân phát hành theo yêu cầu, hoặc hệ thống phát hành theo lô đã lên lịch | Built |
| Nộp lên cơ quan thuế | Hóa đơn đã phát hành được gửi tới cơ quan thuế (CQT) qua T-VAN, có theo dõi trạng thái | Built |
| Điều chỉnh / thay thế / hủy | Chủ sửa, thay thế, hoặc hủy một hóa đơn đã phát hành kèm lý do | Built |
| Khách tự yêu cầu hóa đơn | Người mua quét QR trên biên lai và gửi thông tin của mình trước thời hạn để nhận hóa đơn | Built |
| Dấu vết kiểm toán | Mọi sự kiện hóa đơn (tạo, phát hành, thử lại, nộp, chấp nhận/từ chối) đều được ghi nhận | Built |
| Nhiều nhà cung cấp ngoài iiapi/T-VAN | Onboard các nhà cung cấp ngoài bộ hiện tại | Planned |
4. Phụ thuộc Module
| Phụ thuộc vào | Vì sao |
|---|---|
| Sản phẩm | Quy tắc nhóm thuế được cấp lên sản phẩm; thay đổi sản phẩm điều hòa lại thuế đã áp |
| Commerce | Định danh thuế (MST) của merchant được nhập tại commerce và chảy vào hóa đơn dưới vai người bán |
| Đơn hàng | Đơn hàng cung cấp các dòng và tổng để điền vào hóa đơn |
| Payment | Một thanh toán thành công là thứ kích hoạt phát hành hóa đơn tự động |
5. Backend Packages
Module này được cấp nguồn bởi hai dịch vụ và hai adapter tích hợp. Chi tiết triển khai nằm trong tài liệu nhà phát triển — phần này chỉ ánh xạ module sang chúng.
| Package | Vai trò | Tài liệu nhà phát triển |
|---|---|---|
@nx/taxation | Mẫu quy tắc nhóm thuế, cấp thuế lên sản phẩm, dữ liệu tham chiếu VN | taxation |
@nx/invoice | Phát hành hóa đơn điện tử, nhà cung cấp/hồ sơ, yêu cầu, điều chỉnh/hủy, dấu vết kiểm toán | invoice |
@nx/iiapi | Adapter cổng nhà cung cấp (VNPAY / VNIS) cho vòng đời hóa đơn và webhook | iiapi |
@nx/t-van | Adapter mạng cơ quan thuế (CQT) cho nộp, xác thực, và tra cứu thuế | t-van |
6. Luồng người dùng chính
Phát hành hóa đơn khi thanh toán
Khách tự yêu cầu hóa đơn
7. Vai trò & Quyền hạn
| Vai trò | Có thể | Không thể |
|---|---|---|
| Owner | Đăng ký định danh thuế, định nghĩa nhóm thuế, kết nối nhà cung cấp, cấu hình phát hành, điều chỉnh/hủy hóa đơn | — |
| Manager | Xem hóa đơn và dấu vết kiểm toán, phát hành và điều chỉnh hóa đơn | Đổi thông tin xác thực nhà cung cấp (do owner kiểm soát) |
| Thu ngân | Phát hành hóa đơn sau thanh toán, thu thông tin người mua | Quản lý nhóm thuế hoặc thông tin xác thực nhà cung cấp |
| Người mua | Tự yêu cầu hóa đơn của mình qua QR | Truy cập dữ liệu của merchant hoặc người mua khác |
8. Trạng thái & Lộ trình
| Phase | Năng lực |
|---|---|
| P1 | Định danh thuế người bán, quy tắc nhóm thuế + cấp thuế, hồ sơ/nhà cung cấp hóa đơn, định tuyến kênh, phát hành tự động/thủ công/theo lịch, nộp lên cơ quan thuế, điều chỉnh/thay thế/hủy, khách tự yêu cầu hóa đơn, dấu vết kiểm toán |
| P2 | Thêm nhà cung cấp ngoài bộ iiapi/T-VAN hiện tại; tùy chọn giao hóa đơn phong phú hơn |
| P3 | Hỗ trợ kê khai / nộp thuế |
Ghi chú trạng thái. Phát hành chạy trên bộ nhà cung cấp hiện tại — VNPAY / VNIS qua iiapi cộng T-VAN cho kết nối cơ quan thuế. Quy tắc nhóm thuế và cấp thuế cho sản phẩm do taxation xử lý. Một số chi tiết định danh vận hành cho dịch vụ hóa đơn vẫn đang được điều hòa trước khi lên production (xem trang nhà phát triển vận hành invoice).