PRD: Tích hợp nhà cung cấp hóa đơn điện tử (iiapi / T-VAN)
| Module | Thuế & Hóa đơn (CORE-10) | PRD ID | PRD-INV-002 |
| Status | Shipped | Owner | Tax & Invoice squad |
| Date | 2026-04-13 | Version | v1.0 |
| Packages | @nx/invoice · @nx/iiapi · @nx/t-van · @nx/core | URD | CFG · INV |
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 / VNIS qua iiapi) một lần duy nhất, với credential 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. Một seam provider duy nhất xử lý cả tra cứu thông tin thuế người bán lẫn phát hành hóa đơn, 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, KICKO tra cứu thông tin thuế người bán qua tích hợp T-VAN trực tiếp và chưa có package 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 credential 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 package invoice riêng và iiapi provider client, kết nối provider theo từng merchant, đồng thời chuyển việc tra cứu thông tin thuế từ T-VAN sang iiapi để một seam provider duy nhất xử lý cả tra cứu thông tin thuế lẫn phát hành hóa đơn. Đâ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 HKD/SME mà KICKO hướng tới.
2. Goals & Non-Goals
Goals
- Dựng package invoice và iiapi provider client; kết nối provider theo từng merchant qua
merchantId/ link kết nối. - Lưu credential của provider mã hóa và bắt buộc
clientNametườ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 / policy) và định tuyến các sale channel tới một provider config, 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 queue Kafka + BullMQ, ghi nhận số hóa đơn và mã cơ quan thuế (CQT).
- Xử lý webhook đến từ provider (với công tắc webhook theo từng config) để cập nhật trạng thái hóa đơn.
- Chuyển việc tra cứu thông tin thuế từ T-VAN sang iiapi như một seam provider duy nhất.
Non-Goals
- Nhiều nhà cung cấp hóa đơn ngoài bộ iiapi / T-VAN hiện tại.
- Kết xuất PDF của hóa đơn (do phía provider 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 retry policy; các lỗi đi vào audit trail, không bao giờ bị bỏ rơi âm thầm |
| An toàn credential | 100% credential của provider đượ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ừ provider đồ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 provider, cấu hình phát hành theo loại hóa đơn, định tuyến channel, hoàn tất onboarding |
| Manager | Theo dõi trạng thái phát hành và audit trail; retry / đ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 payment success để tự động đưa việc phát hành vào queue |
Core scenarios: owner kết nối một iiapi provider với credential mã hóa và clientName tường minh → cấu hình serial/category/policy theo từng loại hóa đơn và định tuyến mỗi sale channel → một thanh toán thành công → hóa đơn được đưa vào queue qua Kafka/BullMQ, đượ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 cùng seam iiapi.
5. User Stories
- Là một owner, tôi muốn kết nối một provider hóa đơn điện tử theo từng merchant với credential mã hóa và một client name 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 sale channel, để 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 queue 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 retry theo policy 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 seam provider duy nhất tra cứu thông tin thuế người bán và phát hành hóa đơn, để tôi cấu hình một kết nối thay vì hai tích hợp.
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 provider (VNPAY / VNIS qua iiapi) theo từng merchant qua merchantId / link, với credential lưu mã hóa và clientName 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à policy phát hành | URD-CFG-003 |
| FR-4 | Định tuyến mỗi sale channel tới provider config sẽ phát hành hóa đơn của nó | URD-CFG-004 |
| FR-5 | Cấu hình retry policy (số lần retry 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 chi nhánh; wizard onboarding có hướng dẫn cho việc thiết lập provider | URD-CFG-006..007 |
| FR-7 | Tự động đưa một hóa đơn vào queue để phát hành khi thanh toán thành công, qua Kafka + BullMQ | URD-INV-001 |
| FR-8 | Phát hành hóa đơn qua provider 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 | Retry một lần phát hành thất bại theo policy đã cấu hình; nộp hóa đơn đã phát hành lên cơ quan thuế (CQT qua T-VAN) 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ừ provider (công tắc webhook theo từng config) để 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 credential | Credential của provider đượ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 provider và các config được scope theo từng merchant (x-merchant-id); thay đổi credential 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 queue Kafka + BullMQ với retry policy cấu hình được; lỗi được ghi nhận, không bị bỏ rơi |
| Idempotent | Xử lý webhook và queue 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ữ ({ en, vi }) |
8. UX & Flows
Màn hình chính (trong apps/client): quản lý kết nối provider iiapi-configs, trình chỉnh sửa serial/category/policy theo từng loại hóa đơn, định tuyến channel, và luồng onboarding hóa đơn có hướng dẫn.
9. Data & Domain
| Entity | Vai trò |
|---|---|
MerchantInvoiceProfile | Thiết lập hóa đơn của merchant, liên kết với định danh thuế người bán |
InvoiceProvider | Provider đã kết nối (iiapi) theo từng merchant - vault credential mã hóa, clientName |
InvoiceProviderConfig | Serial / category / policy và thiết lập retry theo từng loại hóa đơn |
InvoiceConfigMapping | Định tuyến một sale channel tới provider config phát hành hóa đơn của nó |
Invoice | Hóa đơn điện tử đã phát hành - số, mã CQT, trạng thái |
InvoiceAuditTracing | 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 MST, tên, và địa chỉ của merchant.
- Payment (
payment.success) - một thanh toán thành công là thứ đưa việc phát hành vào queue. - iiapi provider gateway (
@nx/iiapi) - phát hành hóa đơn hợp pháp và gửi webhook. - T-VAN tax-authority network (
@nx/t-van) - nộp CQT, kiểm định, và seam thông tin thuế đang được chuyển sang iiapi. - Kafka + BullMQ - phương tiện queue giữa payment success và việc phát hành.
Assumptions
- Merchant đã đăng ký một định danh thuế người bán (MST).
- Merchant nắm credential hợp lệ của provider và một
clientNamecho kết nối. - Một sale channel được định tuyến tới một provider config đang hoạt động trước khi phát hành.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Provider từ chối hoặc timeout khi phát hành | Retry policy (số lần tối đa + delay) theo từng config; lỗi được ghi vào audit trail |
| Phát hành trùng khi queue / webhook gửi lại | Xử lý queue và webhook idempotent; trạng thái theo dõi theo từng hóa đơn |
| Rò rỉ credential | Credential lưu mã hóa; thay đổi do owner kiểm soát |
| Chỉ một bộ provider (iiapi / T-VAN) | Chấp nhận cho đợt này; đa provider là Non-Goal, hoãn sang P2 |
| Hồi quy khi migration thông tin thuế T-VAN → iiapi | Seam duy nhất được kiểm định với việc sync thông tin thuế hiện có trước khi cutover |
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 provider |
| Migration | Việc tra cứu thông tin thuế chuyển từ T-VAN sang iiapi (một seam provider duy nhất) |
| Launch criteria | Kết nối provider (credential mã hóa + clientName) → cấu hình serial/policy theo từng loại → payment success đưa vào queue + 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 iiapi |
| Monitoring | Tỷ lệ phát hành thành công/thất bại, độ sâu retry, độ trễ đồng bộ webhook, tồn đọng queue |
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 queue 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).
Credential của provider được lưu ở đâu? Mã hóa khi lưu trữ, scope theo từng merchant, với một clientName tường minh - không có client mặc định ngầm định.
Điều gì xảy ra nếu provider từ chối một lần phát hành? Nó được retry theo policy đã 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.
Vì sao chuyển thông tin thuế từ T-VAN sang iiapi? Để một seam provider duy nhất xử lý cả tra cứu thông tin thuế người bán lẫn phát hành hóa đơn - một kết nối để cấu hình thay vì hai tích hợp.
Tôi có thể dùng provider khác ngoài VNPAY / VNIS không? Không trong đợt này - các provider khác ngoài bộ iiapi / T-VAN 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 - tổng quan + traceability
- Developer: @nx/invoice · domain model · iiapi · t-van