Tax Information Lookup

Query business registration details directly from Vietnam's Tax Authority (CQT) via T-VAN providers.

Overview

Feature	Description
Service	TVanService.getTaxInfo()
Data Source	CQT (Tax Authority)
Use Case	Verify customer/supplier tax codes

Use Cases

• Verify customer tax code before issuing VAT invoice
• Check supplier legitimacy
• Validate business registration status
• Pre-invoice verification

Single Lookup

import { inject } from '@venizia/ignis';
import { TVanService } from '@nx-3rd/t-van';

class TaxController {
  constructor(
    @inject({ key: 'services.TVanService' })
    private tvanService: TVanService,
  ) {}

  async lookupTaxInfo(taxCode: string) {
    const result = await this.tvanService.getTaxInfo({
      taxCode: taxCode,
    });

    return {
      taxCode: result.taxCode,
      companyName: result.companyName,
      address: result.address,
      representative: result.representative,
      status: result.status,
      registrationDate: result.registrationDate,
    };
  }
}

Response Structure

{
  "taxCode": "0123456789",
  "companyName": "CÔNG TY TNHH ABC",
  "address": "123 Nguyễn Huệ, Quận 1, TP.HCM",
  "representative": "Nguyễn Văn A",
  "status": "ACTIVE",
  "registrationDate": "2020-01-15",
  "businessType": "Retail",
  "phoneNumber": "028-1234-5678"
}

Business Status

Status	Description	Can Issue Invoice
ACTIVE	Operating normally	Yes
SUSPENDED	Temporarily suspended	No
CLOSED	Permanently closed	No
PENDING	Registration pending	No

Batch Lookup

Query multiple businesses at once:

async batchLookup(taxCodes: string[]) {
  const results = await this.tvanService.batchGetTaxInfo({
    taxCodes: taxCodes,
  });

  return results.map(r => ({
    taxCode: r.taxCode,
    companyName: r.companyName,
    status: r.status,
    found: r.found,
  }));
}

Caching Strategy

Tax info doesn't change frequently - cache it:

const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours

async getTaxInfoCached(taxCode: string) {
  const cached = await this.cache.get(`tax:${taxCode}`);
  if (cached) return cached;

  const info = await this.tvanService.getTaxInfo({ taxCode });
  await this.cache.set(`tax:${taxCode}`, info, CACHE_TTL);

  return info;
}

REST API

GET /api/t-van/tax-info/:taxCode

# Batch lookup
POST /api/t-van/tax-info/batch
Content-Type: application/json

{
  "taxCodes": ["0123456789", "9876543210"]
}

Error Handling

Error Code	Description	Solution
TVAN_001	Invalid format	Tax code must be 10 or 13 digits
TVAN_002	Not found	Tax code not registered
TVAN_003	Timeout	Retry or check network

Related

• Invoice Validation
• API Reference
• T-VAN Overview