Tích hợp IIAPI

IIAPI (Invoice Integration API) là một thành phần tích hợp hóa đơn điện tử kết nối ứng dụng của bạn với các nhà cung cấp T-VAN (Mạng giá trị gia tăng về thuế) để tuân thủ thuế tại Việt Nam.

Tổng quan

Thuộc tính	Giá trị
Gói	@nx/iiapi
Trạng thái	Active
Mục đích	Quản lý hóa đơn điện tử tuân thủ thuế Việt Nam
Nhà cung cấp	Hỗ trợ nhiều nhà cung cấp T-VAN

Tính năng Chính

• Hỗ trợ đa nhà cung cấp - Kết nối với nhiều nhà cung cấp T-VAN khác nhau
• Vòng đời hóa đơn đầy đủ - Tạo, cập nhật, xóa và quản lý hóa đơn
• Nhiều loại hóa đơn - Hóa đơn GTGT, POS, Bán hàng, Vé, Biên lai
• Hỗ trợ Webhook - Nhận cập nhật trạng thái hóa đơn
• Tuân thủ cơ quan thuế - Sẵn sàng cho các yêu cầu của CQT (Tổng cục Thuế)

Bắt đầu Nhanh

1. Cấu hình ứng dụng của bạn

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

class MyApplication extends BaseApplication {
  preConfigure() {
    // Cấu hình các client IIAPI
    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',
          },
        ],
      });

    // Tải thành phần IIAPI
    this.component(NxIIAPIComponent);
  }
}

2. Thiết lập biến môi trường

# Cấu hình IIAPI
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

Kiến trúc

Cấu trúc Thành phần

NxIIAPIComponent đăng ký các dịch vụ hóa đơn bên dưới; mỗi dịch vụ được expose qua một REST controller tương ứng.

Dịch vụ	Mục đích
VATInvoiceService	Thao tác hóa đơn GTGT
POSVATInvoiceService	Hóa đơn GTGT POS
POSSaleInvoiceService	Hóa đơn bán hàng POS
TicketVATInvoiceService	Hóa đơn GTGT vé
SaleInvoiceService	Hóa đơn bán hàng
ReceiptService	Quản lý biên lai
InternalDeliveryService	Phiếu xuất kho nội bộ
InvoiceManagementService	Vòng đời hóa đơn
InvoiceUpdateService	Cập nhật hóa đơn
InvoiceDeleteService	Xóa hóa đơn
InvoiceTypeService	Quản lý loại hóa đơn
WebhookService	Xử lý webhook
OtpService	Xác minh OTP
PitCertificateService	Chứng từ khấu trừ thuế TNCN
NotificationErrorService	Thông báo lỗi

Các loại Hóa đơn

📄Hóa đơn GTGT

Hóa đơn thuế đầy đủGiao dịch B2BĐược khấu trừ thuế

🧾Hóa đơn Bán hàng

Không cần thông tin người muaBán lẻ B2CĐịnh dạng đơn giản

🎫Vé

Vé vận tải/Sự kiệnĐịnh dạng đặc biệtBố cục theo quy định

🏪Hóa đơn GTGT POS

Tạo từ máy POSGửi thời gian thựcTự động gửi đến T-VAN

🛒Hóa đơn Bán hàng POS

Bán lẻ POSThanh toán nhanhĐịnh dạng đơn giản

📋Biên lai

Biên lai phi thuếSử dụng nội bộChỉ để tham khảo

Vòng đời Hóa đơn

Định nghĩa Trạng thái

Trạng thái	Mô tả	Hành động Có sẵn
DRAFT	Hóa đơn đã tạo, chưa gửi	Sửa, Xóa, Gửi
PENDING	Đã gửi đến T-VAN, đang chờ ký	Hủy
SIGNED	Đã được ký số bởi T-VAN	Gửi đến CQT
SENT	Đã gửi đến Cơ quan Thuế	Chờ phản hồi
ACCEPTED	CQT đã chấp nhận hóa đơn	Điều chỉnh, Thay thế
REJECTED	CQT đã từ chối hóa đơn	Sửa, Gửi lại
CANCELLED	Hóa đơn đã hủy	-

Tham khảo API

Ví dụ request/response của các endpoint (tạo, gửi, hủy, liệt kê, webhook) nằm trong tài liệu riêng Tài liệu tham khảo API IIAPI.

Cấu hình Đa Client

IIAPI hỗ trợ nhiều client T-VAN cho các kịch bản kinh doanh khác nhau:

this.bind<IIIAPIOptions>({ key: IIAPIBindingKeys.IIAPI_CLIENT_OPTIONS })
  .toValue({
    enableControllers: true,
    clients: [
      // Nhà cung cấp T-VAN chính
      {
        name: 'primary',
        provider: 'VNPAY',
        taxCode: '0123456789',
        apiKey: process.env.VNPAY_API_KEY,
        isDefault: true,
      },
      // Nhà cung cấp T-VAN dự phòng
      {
        name: 'backup',
        provider: 'VNPAY',
        taxCode: '0123456789',
        apiKey: process.env.VNPAY_BACKUP_API_KEY,
      },
      // Công ty khác
      {
        name: 'subsidiary',
        provider: 'VNPAY',
        taxCode: '9876543210',
        apiKey: process.env.SUBSIDIARY_API_KEY,
      },
    ],
  });

Sử dụng Client Cụ thể

// Sử dụng client mặc định
const invoice = await this.vatInvoiceService.create(data);

// Sử dụng client cụ thể
const invoice = await this.vatInvoiceService.create(data, {
  clientName: 'subsidiary',
});

Xử lý Lỗi

Các Lỗi Thường gặp

BANA không tự định nghĩa danh mục lỗi hóa đơn điện tử - lỗi được trả về từ response của provider VNPAY viiAPI (HTTP status + payload lỗi). Kiểm tra response provider và log service.

Gọi Quản lý Hóa đơn

InvoiceManagementService cung cấp cancelInvoice, getInvoiceDetail, getTaxCodeInfo, và getInvoicePdf. Mỗi hàm nhận dữ liệu yêu cầu cùng clientName tùy chọn để chọn client đã đăng ký:

// Tra cứu chi tiết hóa đơn thông qua một client cụ thể
const detail = await this.invoiceManagementService.getInvoiceDetail(
  { taxCode: '0123456789', requestId: 'req-123' },
  'vnpay-client',
);

Tuân thủ Thuế Việt Nam

Tuân thủ hóa đơn điện tử Việt Nam theo Nghị định 123/2020 và Nghị định 70/2025 được mô tả trong Tuân thủ Thuế Việt Nam.

Liên quan

• Module Thuế & Hóa đơn - Yêu cầu nghiệp vụ
• Tích hợp T-VAN - Kết nối CQT trực tiếp
• Tích hợp MQ-Pay - Xử lý thanh toán