IIAPI Integration

IIAPI (Invoice Integration API) is an electronic invoice integration component that connects your application with T-VAN (Tax Value Added Network) providers for Vietnam tax compliance.

Overview

Attribute	Value
Package	@nx/iiapi
Status	Active
Purpose	E-Invoice management for Vietnam tax compliance
Providers	Multiple T-VAN providers supported

Key Features

• Multi-provider support - Connect to various T-VAN providers
• Full invoice lifecycle - Create, update, delete, and manage invoices
• Multiple invoice types - VAT, POS, Sale, Ticket, Receipt invoices
• Webhook support - Receive invoice status updates
• Tax authority compliance - Ready for CQT (Vietnam Tax Authority) requirements

Quick Start

1. Configure your application

// application.ts
import { NxIIAPIComponent, IIAPIBindingKeys, IIIAPIOptions } from '@nx/iiapi';

class MyApplication extends BaseApplication {
  preConfigure() {
    // Configure IIAPI clients
    this.bind<IIIAPIOptions>({ key: IIAPIBindingKeys.IIAPI_CLIENT_OPTIONS })
      .toValue({
        enableControllers: true,
        clients: [
          {
            name: 'default',
            provider: 'VNPAY',
            apiKey: process.env.IIAPI_API_KEY,
            secretKey: process.env.IIAPI_SECRET_KEY,
            taxCode: process.env.COMPANY_TAX_CODE,
            isProduction: process.env.NODE_ENV === 'production',
          },
        ],
      });

    // Load IIAPI component
    this.component(NxIIAPIComponent);
  }
}

2. Set environment variables

# IIAPI Configuration
APP_ENV_IIAPI_API_KEY=your-api-key
APP_ENV_IIAPI_SECRET_KEY=your-secret-key
APP_ENV_IIAPI_TAX_CODE=0123456789
APP_ENV_IIAPI_PROVIDER=VNPAY
APP_ENV_IIAPI_IS_PRODUCTION=false

Architecture

Component Structure

NxIIAPIComponent registers the invoice services below; each service is exposed by a matching REST controller.

Service	Purpose
VATInvoiceService	VAT invoice operations
POSVATInvoiceService	POS VAT invoices
POSSaleInvoiceService	POS sale invoices
TicketVATInvoiceService	Ticket VAT invoices
SaleInvoiceService	Sale invoices
ReceiptService	Receipt management
InternalDeliveryService	Internal delivery notes
InvoiceManagementService	Invoice lifecycle
InvoiceUpdateService	Invoice updates
InvoiceDeleteService	Invoice deletion
InvoiceTypeService	Invoice type management
WebhookService	Webhook handling
OtpService	OTP verification
PitCertificateService	Digital certificate
NotificationErrorService	Error notifications

Invoice Types

📄VAT Invoice

Full tax invoiceB2B transactionsTax deductible

🧾Sale Invoice

No buyer info requiredB2C retailSimplified format

🎫Ticket Invoice

Transport/Event ticketsSpecial formatRegulated layout

🏪POS VAT Invoice

POS generatedReal-time submissionAuto-submit to T-VAN

🛒POS Sale Invoice

POS retailQuick checkoutSimplified format

📋Receipt

Non-tax receiptInternal useReference only

Invoice Lifecycle

Status Definitions

Status	Description	Actions Available
DRAFT	Invoice created, not submitted	Edit, Delete, Submit
PENDING	Submitted to T-VAN, awaiting signature	Cancel
SIGNED	Digitally signed by T-VAN	Send to CQT
SENT	Sent to Tax Authority	Wait for response
ACCEPTED	CQT accepted the invoice	Adjust, Replace
REJECTED	CQT rejected the invoice	Correct, Resubmit
CANCELLED	Invoice cancelled	-

API Reference

Endpoint request/response examples (create, submit, cancel, list, webhook) live in the dedicated IIAPI API Reference.

Multi-Client Configuration

IIAPI supports multiple T-VAN clients for different business scenarios:

this.bind<IIIAPIOptions>({ key: IIAPIBindingKeys.IIAPI_CLIENT_OPTIONS })
  .toValue({
    enableControllers: true,
    clients: [
      // Primary T-VAN provider
      {
        name: 'primary',
        provider: 'VNPAY',
        taxCode: '0123456789',
        apiKey: process.env.VNPAY_API_KEY,
        isDefault: true,
      },
      // Backup T-VAN provider
      {
        name: 'backup',
        provider: 'VNPAY',
        taxCode: '0123456789',
        apiKey: process.env.VNPAY_BACKUP_API_KEY,
      },
      // Different company
      {
        name: 'subsidiary',
        provider: 'VNPAY',
        taxCode: '9876543210',
        apiKey: process.env.SUBSIDIARY_API_KEY,
      },
    ],
  });

Using Specific Client

// Use default client
const invoice = await this.vatInvoiceService.create(data);

// Use specific client
const invoice = await this.vatInvoiceService.create(data, {
  clientName: 'subsidiary',
});

Error Handling

Common Errors

BANA does not define its own e-invoice error catalogue - errors are surfaced from the VNPAY viiAPI provider response (HTTP status + provider error payload). Inspect the provider response and the service logs.

Calling Invoice Management

InvoiceManagementService exposes cancelInvoice, getInvoiceDetail, getTaxCodeInfo, and getInvoicePdf. Each takes the request data plus an optional clientName to select a registered client:

// Look up an invoice's detail through a specific client
const detail = await this.invoiceManagementService.getInvoiceDetail(
  { taxCode: '0123456789', requestId: 'req-123' },
  'vnpay-client',
);

Vietnam Tax Compliance

Vietnam e-invoice compliance under Decree 123/2020 and Decree 70/2025 is documented in Vietnam Tax Compliance.

Related

• Tax & Invoice Module - Business requirements
• T-VAN Integration - Direct CQT connection
• MQ-Pay Integration - Payment processing