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	Production
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

typescript

// 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: 'VIETTEL',
            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

bash

# 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=VIETTEL
APP_ENV_IIAPI_IS_PRODUCTION=false

Kiến trúc

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

🧩

NxIIAPIComponent

Thành phần tích hợp hóa đơn điện tử

🔗

Custom Bindings

🏭IIAPIClientProvider→Factory client

📚IIAPIClientRegistry→Registry đa client

⚙️

Dịch vụ (15)

📄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

🌐

Controllers (15)

REST API endpoints tương ứng với từng dịch vụ

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

Tạo Hóa đơn GTGT

typescript

import { inject } from '@venizia/ignis';
import { VATInvoiceService } from '@nx/iiapi';

class InvoiceController {
  constructor(
    @inject({ key: 'services.VATInvoiceService' })
    private vatInvoiceService: VATInvoiceService,
  ) {}

  async createInvoice() {
    const invoice = await this.vatInvoiceService.create({
      // Thông tin người bán
      seller: {
        taxCode: '0123456789',
        name: 'Tên Công ty Của Bạn',
        address: '123 Đường phố, Quận, Thành phố',
      },

      // Thông tin người mua
      buyer: {
        taxCode: '9876543210',
        name: 'Công ty Khách hàng',
        address: '456 Đại lộ, Quận, Thành phố',
      },

      // Chi tiết hóa đơn
      invoiceDate: new Date(),
      currencyCode: 'VND',
      exchangeRate: 1,

      // Các mặt hàng
      items: [
        {
          itemName: 'Sản phẩm A',
          unitName: 'Cái',
          quantity: 10,
          unitPrice: 100000,
          amount: 1000000,
          vatRate: 10,
          vatAmount: 100000,
        },
      ],

      // Tổng cộng
      totalAmount: 1000000,
      totalVatAmount: 100000,
      totalPayment: 1100000,
    });

    return invoice;
  }
}

Tạo Hóa đơn POS

typescript

// Tạo nhanh hóa đơn POS
const posInvoice = await this.posSaleInvoiceService.create({
  // Các trường bắt buộc tối thiểu
  invoiceDate: new Date(),
  items: [
    {
      itemName: 'Cà phê',
      quantity: 2,
      unitPrice: 50000,
      amount: 100000,
    },
  ],
  totalAmount: 100000,
  paymentMethod: 'CASH',
});

Gửi Hóa đơn đến T-VAN

typescript

// Gửi hóa đơn nháp
const result = await this.invoiceManagementService.submit({
  invoiceId: 'inv-uuid-123',
  clientName: 'default', // Client T-VAN nào sẽ được sử dụng
});

// Kết quả chứa hóa đơn đã ký với:
// - Số hóa đơn (tự động gán)
// - Chữ ký số
// - Tham chiếu T-VAN

Xử lý Webhook

typescript

// T-VAN gửi cập nhật trạng thái qua webhook
app.post('/api/iiapi/webhook', async (c) => {
  const webhookData = await c.req.json();

  await this.webhookService.process({
    provider: webhookData.provider,
    event: webhookData.event,
    invoiceId: webhookData.invoiceId,
    status: webhookData.status,
    data: webhookData.data,
  });

  return c.json({ received: true });
});

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:

typescript

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

Sử dụng Client Cụ thể

typescript

// 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

Mã lỗi	Mô tả	Giải pháp
`IIAPI_001`	Định dạng mã số thuế không hợp lệ	Kiểm tra mã số thuế (10 hoặc 13 chữ số)
`IIAPI_002`	Thiếu các trường bắt buộc	Xem lại các trường bắt buộc
`IIAPI_003`	Kết nối T-VAN thất bại	Kiểm tra thông tin API
`IIAPI_004`	Hóa đơn đã được gửi	Không thể sửa hóa đơn đã gửi
`IIAPI_005`	CQT từ chối	Kiểm tra lý do từ chối, sửa dữ liệu

Chiến lược Thử lại

typescript

// Tích hợp sẵn thử lại cho các lỗi tạm thời
const result = await this.invoiceManagementService.submit({
  invoiceId: 'inv-uuid-123',
  options: {
    maxRetries: 3,
    retryDelay: 1000,
  },
});

Tuân thủ Thuế Việt Nam

Yêu cầu Nghị định 123/2020

Yêu cầu	IIAPI Hỗ trợ
Gửi hóa đơn thời gian thực	Có, thông qua T-VAN
Chữ ký số	Có, T-VAN ký
Định dạng số hóa đơn	Tự động tạo
Lưu trữ dữ liệu 10 năm	Trách nhiệm của bạn
Kết nối CQT	Thông qua các nhà cung cấp T-VAN

Cập nhật Nghị định 70/2025 (Hiệu lực từ tháng 1 năm 2026)

Yêu cầu Mới	IIAPI Hỗ trợ
Hóa đơn điện tử ngay lập tức khi bán	Các loại hóa đơn POS
Mã số thuế trên mỗi giao dịch	Trường bắt buộc
Kết nối CQT thời gian thực	Thông qua T-VAN

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

Client Guide

Nhà cung cấp

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

Tích hợp IIAPI ​

Tổng quan ​

Tính năng Chính ​

Bắt đầu Nhanh ​

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

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

Kiến trúc ​

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

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

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

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

Tham khảo API ​

Tạo Hóa đơn GTGT ​

Tạo Hóa đơn POS ​

Gửi Hóa đơn đến T-VAN ​

Xử lý Webhook ​

Cấu hình Đa Client ​

Sử dụng Client Cụ thể ​

Xử lý Lỗi ​

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

Chiến lược Thử lại ​

Tuân thủ Thuế Việt Nam ​

Yêu cầu Nghị định 123/2020 ​

Cập nhật Nghị định 70/2025 (Hiệu lực từ tháng 1 năm 2026) ​

Liên quan ​

Tích hợp IIAPI

Tổng quan

Tính năng Chính

Bắt đầu Nhanh

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

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

Kiến trúc

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

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

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

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

Tham khảo API

Tạo Hóa đơn GTGT

Tạo Hóa đơn POS

Gửi Hóa đơn đến T-VAN

Xử lý Webhook

Cấu hình Đa Client

Sử dụng Client Cụ thể

Xử lý Lỗi

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

Chiến lược Thử lại

Tuân thủ Thuế Việt Nam

Yêu cầu Nghị định 123/2020

Cập nhật Nghị định 70/2025 (Hiệu lực từ tháng 1 năm 2026)

Liên quan