Tax & Invoice Phase A In-progress
Keeps the merchant legally compliant when they sell: it records the seller's tax identity, applies the right tax rules to products, and turns a completed payment into a legal Vietnamese electronic invoice that can be sent to the buyer and the tax authority. Used by owners (who set up tax and invoicing), cashiers (who issue invoices at the counter), and buyers (who self-claim their own invoice).
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-10 |
| Tier | Core |
| Status | In-progress |
| Phase | P1 (e-invoicing + tax-authority submission) |
| Priority | HIGH |
| Primary users | Owner / Manager (setup), Cashier (issue), Buyer (self-claim) |
Two services, one business module. Applying tax to products and issuing the invoice are two halves of the same compliance story. The Taxation service owns tax-group rules and pushes the right tax onto each product; the Invoice service issues the legal e-invoice through a provider and the tax authority. Tax-authority connectivity runs through two integration adapters — iiapi (provider gateway) and t-van (tax-authority network). See §5 Backend Packages.
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Seller tax identity (tax code / MST, business name, address) | Authoritative tax-code registry (issued by the tax authority) |
| Tax-group rule templates applied onto products | Tax-rate calculation at sale time (owned by the Products / pricing engine) |
| Vietnamese administrative reference data (provinces, wards, units) | PDF rendering of the invoice (produced provider-side) |
| Merchant invoice profile + provider credentials (encrypted) | Payment capture (owned by Payment) |
| Invoice issuance (VAT, sale, POS, ticket, internal-delivery) | Order lifecycle (owned by Orders) |
| Provider integration: VNPAY / VNIS via iiapi + T-VAN | Multi-provider beyond the current iiapi/T-VAN set |
| Tax-authority (CQT) submission and status tracking | Tax declaration / filing automation |
| Invoice adjustment, replacement, and cancellation | Cross-merchant settlement |
| Buyer self-service claim (QR + token + deadline) | |
| Immutable audit trail for every invoice event |
3. Capabilities
| Capability | What the user can do | Status |
|---|---|---|
| Seller tax identity | Owner registers the merchant's tax code (MST), name, and address used as the invoice seller | Built |
| Tax-group rules | Owner defines tax-group templates that auto-apply the correct tax onto matching products | Built |
| VN reference data | Province / ward / administrative-unit lookups when entering addresses | Built |
| Invoice profile & provider | Owner connects a VNPAY / VNIS provider with encrypted credentials and serial/issuance policy | Built |
| Channel routing | Owner maps each sale channel / principal to the provider config that should issue its invoices | Built |
| Profile sharing | Owner shares one invoice profile across branches (private / all-branches / whitelist) | Built |
| Onboarding wizard | Guided step-by-step provider setup | Built |
| Auto issuance on payment | A completed payment automatically queues and issues the invoice | Built |
| Manual / scheduled issuance | Cashier issues on demand, or the system issues in scheduled batches | Built |
| Tax-authority submission | Issued invoices are sent to the tax authority (CQT) via T-VAN, with status tracked | Built |
| Adjust / replace / cancel | Owner corrects, replaces, or cancels an issued invoice with a reason | Built |
| Buyer self-service claim | Buyer scans a receipt QR and submits their own info before a deadline to get the invoice | Built |
| Audit trail | Every invoice event (created, issued, retried, submitted, accepted/rejected) is recorded | Built |
| Multiple providers beyond iiapi/T-VAN | Onboard providers outside the current set | Planned |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Products | Tax-group rules are provisioned onto products; product changes reconcile the applied tax |
| Commerce | The merchant's tax identity (MST) is entered in commerce and flows into the invoice as the seller |
| Orders | The sale order supplies the line items and totals that fill the invoice |
| Payment | A successful payment is what triggers automatic invoice issuance |
5. Backend Packages
This module is powered by two services and two integration adapters. Implementation detail lives in the developer docs — this section only maps the module to them.
| Package | Role | Developer docs |
|---|---|---|
@nx/taxation | Tax-group rule templates, provisioning tax onto products, VN reference data | taxation |
@nx/invoice | E-invoice issuance, providers/profiles, claims, adjustment/cancellation, audit trail | invoice |
@nx/iiapi | Provider gateway adapter (VNPAY / VNIS) for invoice lifecycle and webhooks | iiapi |
@nx/t-van | Tax-authority (CQT) network adapter for submission, validation, and tax lookup | t-van |
6. Key User Flows
Issue an invoice on payment
Buyer self-service claim
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner | Register tax identity, define tax groups, connect providers, configure issuance, adjust/cancel invoices | — |
| Manager | View invoices and audit trail, issue and adjust invoices | Change provider credentials (owner-gated) |
| Cashier | Issue an invoice after payment, collect buyer info | Manage tax groups or provider credentials |
| Buyer | Self-claim their own invoice via QR | Access any other merchant or buyer data |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Seller tax identity, tax-group rules + provisioning, invoice profile/provider, channel routing, auto/manual/scheduled issuance, tax-authority submission, adjust/replace/cancel, buyer self-service claim, audit trail |
| P2 | Additional providers beyond the current iiapi/T-VAN set; richer invoice delivery options |
| P3 | Tax declaration / filing assistance |
Status note. Issuance runs against the current provider set — VNPAY / VNIS via iiapi plus T-VAN for tax-authority connectivity. Tax-group rules and product provisioning are handled by taxation. Some operational identity details for the invoice service are still being reconciled before production (see the developer invoice operations page).