PRD: Tích hợp nhà cung cấp hóa đơn điện tử
| Module | Thuế & Hóa đơn | PRD ID | PRD-INV-002 |
| Trạng thái | Sẵn sàng dev | FEAT | INV |
| Epic | — | Plane | BANA-1521 |
| Ngày | 2026-04-13 | Phiên bản | v1.0 |
| Gói | @nx/invoice | URD | INV |
| Surface | Client · Chủ/QL | ||
| Phụ trách | Phát Nguyễn | ||
TL;DR
Cho phép merchant kết nối một nhà cung cấp hóa đơn điện tử hợp pháp của Việt Nam (VNPAY) một lần duy nhất, với thông tin xác thực lưu trữ mã hóa, rồi tự động phát hành hóa đơn điện tử có số ngay khi một thanh toán thành công. Việc phát hành hóa đơn chạy qua nhà cung cấp hóa đơn điện tử, còn tra cứu thông tin thuế người bán được giải quyết qua một kết nối truyền nhận cơ quan thuế (T-VAN) riêng biệt, nên mỗi giao dịch bán hoàn tất đều có thể trở thành hóa đơn tuân thủ - được ghi nhận kèm mã cơ quan thuế và theo dõi xuyên suốt - mà không cần giấy tờ thủ công.
1. Context & Problem
Merchant bán hàng tại Việt Nam phải phát hành hóa đơn điện tử hợp pháp và nộp lên cơ quan thuế. Trước đợt phát triển này, BANA tra cứu thông tin thuế người bán qua một lượt tra cứu T-VAN trực tiếp và chưa có năng lực hóa đơn hạng nhất, nên không có cách kết nối nhà cung cấp hóa đơn điện tử theo từng merchant, lưu thông tin xác thực an toàn, hay biến một thanh toán đã hoàn tất thành hóa đơn đã phát hành với trạng thái có thể audit.
Đợt này dựng nên năng lực hóa đơn riêng và cổng nhà cung cấp hóa đơn điện tử, kết nối nhà cung cấp theo từng merchant. Tra cứu thông tin thuế người bán vẫn tiếp tục chạy qua kết nối T-VAN riêng - việc gom nó về sau seam nhà cung cấp phát hành đã được đưa vào phạm vi nhưng chưa được triển khai trong đợt này. Đây là nền tảng cho hóa đơn điện tử hợp pháp - một yêu cầu pháp lý bắt buộc đối với phân khúc hộ kinh doanh / SME mà BANA hướng tới.
2. Goals & Non-Goals
Goals
- Dựng năng lực hóa đơn và cổng nhà cung cấp hóa đơn điện tử; kết nối nhà cung cấp theo từng merchant.
- Lưu thông tin xác thực của nhà cung cấp mã hóa và bắt buộc một tên client tường minh (không có client mặc định ngầm định).
- Cấu hình phát hành theo từng loại hóa đơn (serial / category / chính sách phát hành) và định tuyến các kênh bán tới một cấu hình nhà cung cấp, kèm luồng onboarding có hướng dẫn.
- Điều khiển vòng đời phát hành từ một thanh toán thành công qua hàng đợi phát hành theo sự kiện, ghi nhận số hóa đơn và mã cơ quan thuế (CQT).
- Xử lý webhook đến từ nhà cung cấp (với công tắc webhook theo từng cấu hình) để cập nhật trạng thái hóa đơn.
- Giữ tra cứu thông tin thuế người bán trên kết nối T-VAN riêng, tách biệt với nhà cung cấp phát hành hóa đơn điện tử (việc gom về một seam được hoãn lại).
Non-Goals
- Nhiều nhà cung cấp hóa đơn ngoài bộ nhà cung cấp hiện tại.
- Kết xuất PDF của hóa đơn (do phía nhà cung cấp tạo ra).
- Tính thuế suất tại thời điểm bán (do pricing engine sở hữu).
- Tự động hóa kê khai / nộp thuế.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Độ phủ phát hành | Tỷ lệ thanh toán thành công tạo ra hóa đơn đã phát hành theo đúng chế độ đã cấu hình |
| Độ tin cậy phát hành | Tỷ lệ phát hành thành công sau chính sách thử lại; các lỗi đi vào audit trail, không bao giờ bị bỏ rơi âm thầm |
| An toàn thông tin xác thực | 100% thông tin xác thực của nhà cung cấp được lưu mã hóa; không có plaintext khi lưu trữ |
| Ghi nhận mã cơ quan thuế | Tỷ lệ hóa đơn đã phát hành ghi nhận được số hóa đơn + mã CQT |
| Độ mới của webhook | Webhook từ nhà cung cấp đồng bộ trạng thái hóa đơn mà không cần can thiệp thủ công |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Owner | Kết nối nhà cung cấp, cấu hình phát hành theo loại hóa đơn, định tuyến kênh, hoàn tất onboarding |
| Manager | Theo dõi trạng thái phát hành và audit trail; thử lại / điều chỉnh khi được phép |
| Cashier | Kích hoạt export thủ công cho hóa đơn của một đơn hàng tại quầy |
| System (payment) | Phát ra thanh toán thành công để tự động đưa việc phát hành vào hàng đợi |
Core scenarios: owner kết nối một nhà cung cấp với thông tin xác thực mã hóa và tên client tường minh → cấu hình serial / category / policy theo từng loại hóa đơn và định tuyến mỗi kênh bán → một thanh toán thành công → hóa đơn được đưa vào hàng đợi, được phát hành, và số hóa đơn + mã CQT được ghi nhận → webhook đến đồng bộ trạng thái; việc tra cứu thông tin thuế chạy qua kết nối T-VAN riêng.
5. User Stories
- Là một owner, tôi muốn kết nối một nhà cung cấp hóa đơn điện tử theo từng merchant với thông tin xác thực mã hóa và một tên client tường minh, để việc phát hành vừa an toàn vừa rõ ràng.
- Là một owner, tôi muốn một luồng onboarding có hướng dẫn để cấu hình serial / category / policy theo từng loại hóa đơn và định tuyến các kênh bán, để thiết lập đúng mà không cần kiến thức thuế sâu.
- Là một owner, tôi muốn một thanh toán đã hoàn tất tự động đưa hóa đơn vào hàng đợi và phát hành, để có hóa đơn tuân thủ mà không cần thao tác thủ công.
- Là một manager, tôi muốn các lỗi phát hành được thử lại theo chính sách và hiển thị trong audit trail, để không có gì bị mất âm thầm.
- Là một cashier, tôi muốn export thủ công hóa đơn của một đơn hàng tại quầy, để phát hành theo yêu cầu khi cần.
- Là một owner, tôi muốn một kết nối nhà cung cấp điều khiển việc phát hành còn tra cứu thông tin thuế người bán chạy trên kết nối T-VAN riêng, để mỗi tích hợp được cấu hình rõ ràng.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Tạo một merchant invoice profile liên kết với định danh thuế người bán | URD-CFG-001 |
| FR-2 | Kết nối một nhà cung cấp (VNPAY) theo từng merchant, với thông tin xác thực lưu mã hóa và một tên client tường minh bắt buộc | URD-CFG-002 |
| FR-3 | Cấu hình theo từng loại hóa đơn: serial, category, phương pháp thuế, và chính sách phát hành | URD-CFG-003 |
| FR-4 | Định tuyến mỗi kênh bán tới cấu hình nhà cung cấp sẽ phát hành hóa đơn của nó | URD-CFG-004 |
| FR-5 | Cấu hình chính sách thử lại (số lần thử lại tối đa + lịch delay) cho việc phát hành thất bại | URD-CFG-005 |
| FR-6 | Chia sẻ một invoice profile giữa các merchant; wizard onboarding có hướng dẫn cho việc thiết lập nhà cung cấp | URD-CFG-006..007 |
| FR-7 | Tự động đưa một hóa đơn vào hàng đợi để phát hành khi thanh toán thành công, qua hàng đợi phát hành theo sự kiện | URD-INV-001 |
| FR-8 | Phát hành hóa đơn qua nhà cung cấp và ghi nhận số hóa đơn + mã cơ quan thuế (CQT); theo dõi trạng thái (pending → processing → success / failed / cancelled) | URD-INV-002..003 |
| FR-9 | Thử lại một lần phát hành thất bại theo chính sách đã cấu hình; nộp hóa đơn đã phát hành lên cơ quan thuế (CQT) khi được bật | URD-INV-004..005 |
| FR-10 | Ghi một bản ghi audit-trail không thể thay đổi cho mỗi sự kiện hóa đơn | URD-INV-006 |
| FR-11 | Điều chỉnh, thay thế, hoặc hủy một hóa đơn đã phát hành kèm lý do | URD-INV-007..008 |
| FR-12 | Xử lý webhook đến từ nhà cung cấp (công tắc webhook theo từng cấu hình) để cập nhật trạng thái hóa đơn | URD-INV-009 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Thuế & Hóa đơn. PRD này tham chiếu tới chúng thay vì lặp lại.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Bảo mật thông tin xác thực | Thông tin xác thực của nhà cung cấp được lưu mã hóa khi lưu trữ; không có secret dạng plaintext |
| Toàn vẹn dữ liệu | Audit trail hóa đơn chỉ ghi thêm; thay đổi trạng thái được ghi nhận, không bao giờ ghi đè |
| Tenancy & authz | Kết nối nhà cung cấp và các cấu hình được giới hạn trong merchant của chính người dùng; thay đổi thông tin xác thực do owner kiểm soát |
| Khả năng phục hồi | Việc phát hành được điều khiển qua hàng đợi phát hành theo sự kiện với chính sách thử lại cấu hình được; lỗi được ghi nhận, không bị bỏ rơi |
| Idempotent | Xử lý webhook và hàng đợi chịu được việc gửi lại mà không phát hành trùng |
| i18n | Nhãn / trạng thái hiển thị cho người dùng là song ngữ (Tiếng Anh / Tiếng Việt) |
8. UX & Flows
Màn hình chính (ứng dụng quản lý): quản lý kết nối nhà cung cấp, trình chỉnh sửa serial / category / policy theo từng loại hóa đơn, định tuyến kênh, và luồng onboarding hóa đơn có hướng dẫn.
9. Data & Domain
| Entity | Vai trò |
|---|---|
| Merchant invoice profile | Thiết lập hóa đơn của merchant, liên kết với định danh thuế người bán |
| Kết nối nhà cung cấp hóa đơn | Nhà cung cấp đã kết nối theo từng merchant - vault thông tin xác thực mã hóa và tên client |
| Cấu hình phát hành nhà cung cấp | Serial / category / policy và thiết lập thử lại theo từng loại hóa đơn |
| Định tuyến kênh | Định tuyến một kênh bán tới cấu hình nhà cung cấp phát hành hóa đơn của nó |
| Hóa đơn | Hóa đơn điện tử đã phát hành - số, mã CQT, trạng thái |
| Audit trail hóa đơn | Trail sự kiện không thể thay đổi cho mỗi thay đổi trạng thái hóa đơn |
Chỉ là mô hình khái niệm - schema và bất biến đầy đủ nằm trong invoice domain model.
10. Dependencies & Assumptions
Depends on
- Định danh thuế người bán (URD-TAX) - invoice profile liên kết với mã số thuế (MST), tên, và địa chỉ của merchant.
- Payment - một thanh toán thành công là thứ đưa việc phát hành vào hàng đợi.
- Cổng nhà cung cấp hóa đơn điện tử - phát hành hóa đơn hợp pháp và gửi webhook.
- Mạng truyền nhận cơ quan thuế (T-VAN) - tra cứu thông tin thuế người bán và truy vấn thông điệp hóa đơn (chỉ truy vấn; không nộp).
- Hàng đợi phát hành theo sự kiện - phương tiện truyền giữa thanh toán thành công và việc phát hành.
Assumptions
- Merchant đã đăng ký một định danh thuế người bán (MST).
- Merchant nắm thông tin xác thực hợp lệ của nhà cung cấp và một tên client cho kết nối.
- Một kênh bán được định tuyến tới một cấu hình nhà cung cấp đang hoạt động trước khi phát hành.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Nhà cung cấp từ chối hoặc timeout khi phát hành | Chính sách thử lại (số lần tối đa + delay) theo từng cấu hình; lỗi được ghi vào audit trail |
| Phát hành trùng khi hàng đợi / webhook gửi lại | Xử lý hàng đợi và webhook idempotent; trạng thái theo dõi theo từng hóa đơn |
| Rò rỉ thông tin xác thực | Thông tin xác thực lưu mã hóa; thay đổi do owner kiểm soát |
| Chỉ một bộ nhà cung cấp | Chấp nhận cho đợt này; VNPAY là nhà cung cấp duy nhất được kết nối, đa nhà cung cấp (kể cả VNIS) là Non-Goal, hoãn sang P2 |
| Gom seam thông tin thuế | Hoãn lại - thông tin thuế người bán vẫn được giải quyết qua kết nối T-VAN riêng; việc gom nó về sau nhà cung cấp phát hành là một đợt sau |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 (nền tảng) - xem URD feature catalog cho CFG và INV |
| Rollout | Tất cả merchant; bật theo từng merchant khi kết nối nhà cung cấp |
| Migration | Không - việc tra cứu thông tin thuế người bán không đổi, vẫn được giải quyết qua kết nối T-VAN (không gom trong đợt này) |
| Launch criteria | Kết nối nhà cung cấp (thông tin xác thực mã hóa + tên client) → cấu hình serial / policy theo từng loại → thanh toán thành công đưa vào hàng đợi + phát hành một hóa đơn có số + mã CQT → webhook đồng bộ trạng thái; tra cứu thông tin thuế được kiểm định trên kết nối T-VAN |
| Monitoring | Tỷ lệ phát hành thành công/thất bại, độ sâu thử lại, độ trễ đồng bộ webhook, tồn đọng hàng đợi |
13. FAQ
Phát hành hóa đơn có cần thao tác thủ công không? Không - mặc định một thanh toán thành công tự động đưa hóa đơn vào hàng đợi và phát hành. Export thủ công tại quầy và phát hành theo lô có lịch là các chế độ bổ sung (URD-MOD).
Thông tin xác thực của nhà cung cấp được lưu ở đâu? Mã hóa khi lưu trữ, giới hạn trong merchant của chính người dùng, với một tên client tường minh - không có client mặc định ngầm định.
Điều gì xảy ra nếu nhà cung cấp từ chối một lần phát hành? Nó được thử lại theo chính sách đã cấu hình (số lần tối đa + delay). Nếu vẫn thất bại, trạng thái là failed và lỗi được ghi vào audit trail.
Tra cứu thông tin thuế người bán đã được gom về nhà cung cấp phát hành chưa? Chưa, trong đợt này thì chưa. Việc phát hành hóa đơn chạy qua nhà cung cấp hóa đơn điện tử, còn tra cứu thông tin thuế người bán vẫn được giải quyết qua kết nối T-VAN riêng. Việc gom cả hai về một seam được dự kiến cho một đợt sau.
Tôi có thể dùng nhà cung cấp khác ngoài VNPAY không? Không trong đợt này - VNPAY là nhà cung cấp duy nhất được kết nối; các nhà cung cấp khác (kể cả VNIS) là Non-Goal, dự kiến cho P2.
References
- URD: Thuế & Hóa đơn - Invoice Lifecycle (INV) · Invoice Configuration (CFG)
- Builds on: Tax Identity (TAX) · Issuance Modes (MOD)
- Module: Thuế & Hóa đơn - URD
- Developer: @nx/invoice · domain model · iiapi · t-van