Tax Information Lookup
Query business registration details directly from Vietnam's Tax Authority (CQT) via T-VAN providers.
Overview
| Feature | Description |
|---|---|
| Service | TVanService.queryTaxInformation() |
| Data Source | CQT (Tax Authority) via T-VAN provider |
| 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
Query Tax Information
queryTaxInformation takes a taxCodes array (max 10 per provider request) - batching is built in, so a single call handles one or many tax codes.
import { inject } from '@venizia/ignis';
import { TVanService, TVanTaxInfoQueryTypes } from '@nx/t-van';
class TaxController {
constructor(
@inject({ key: 'services.TVanService' })
private tvanService: TVanService,
) {}
async lookupTaxInfo(taxCodes: string[]) {
const response = await this.tvanService.queryTaxInformation({
provider: 'vnpay',
params: {
type: TVanTaxInfoQueryTypes.TAX_CODE,
taxCodes,
},
options: { fetchAll: true, continueOnError: true },
});
return response.data;
}
}Response Structure
{
"data": [
{
"taxCode": "0102182292",
"fullName": "Tên doanh nghiệp",
"type": "0100",
"status": "00",
"issuedDate": "2020-01-01T00:00:00",
"department": "...",
"managingTaxAuthority": "...",
"chapterLevel": "...",
"chapter": "555",
"updatedDate": "2024-01-01T00:00:00",
"addressLine": "Địa chỉ doanh nghiệp",
"cityCode": "01TTT",
"districtCode": "006HH",
"wardsCode": "1010937",
"fullAddress": "Địa chỉ chi tiết của doanh nghiệp",
"reason": null
}
]
}Query Types
The type field selects the lookup mode:
| Query Type | Description |
|---|---|
00001_CITIZEN_IDENTITY_CARD | Lookup by citizen identity card |
00003_TAX_CODE | Lookup by tax code |
00130_IDENTITY_CARD_TAX_PAYER | Lookup tax payer by identity card |
00132_PERSONAL_TAX_CODE | Lookup by personal tax code |
The status field is a provider-defined code (e.g. 00); BANA passes it through unchanged.
Batching & Fetch All
A single request accepts up to 10 tax codes. For larger arrays, enable fetchAll so the service splits the array into provider-sized batches and aggregates the results; add continueOnError to keep partial results when a batch fails:
const response = await this.tvanService.queryTaxInformation({
provider: 'vnpay',
params: { type: TVanTaxInfoQueryTypes.TAX_CODE, taxCodes: manyTaxCodes },
options: { fetchAll: true, continueOnError: true },
});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 { data } = await this.tvanService.queryTaxInformation({
provider: 'vnpay',
params: { type: TVanTaxInfoQueryTypes.TAX_CODE, taxCodes: [taxCode] },
});
await this.cache.set(`tax:${taxCode}`, data[0], CACHE_TTL);
return data[0];
}REST API
POST /t-van/tax-information?provider=vnpay
Content-Type: application/json
{
"type": "00003_TAX_CODE",
"taxCodes": ["0123456789", "9876543210"]
}Returns { "result": [ ...TaxInfo ] }.
Error Handling
T-VAN does not define its own error catalogue. Failures are surfaced from the provider response (HTTP status + provider error payload). An empty taxCodes array is rejected with Tax codes array cannot be empty before reaching the provider.