Tra cứu Thông tin Thuế

Truy vấn chi tiết đăng ký kinh doanh trực tiếp từ Cơ quan Thuế Việt Nam (CQT) thông qua các nhà cung cấp T-VAN.

Tổng quan

Tính năng	Mô tả
Service	TVanService.queryTaxInformation()
Nguồn Dữ liệu	CQT (Cơ quan Thuế) qua nhà cung cấp T-VAN
Trường hợp Sử dụng	Xác minh mã số thuế khách hàng/nhà cung cấp

Trường hợp Sử dụng

• Xác minh mã số thuế khách hàng trước khi xuất hóa đơn GTGT
• Kiểm tra tính hợp pháp của nhà cung cấp
• Xác thực trạng thái đăng ký kinh doanh
• Xác minh trước hóa đơn

Tra cứu Thông tin Thuế

queryTaxInformation nhận một mảng taxCodes (tối đa 10 mã mỗi yêu cầu) - chia lô được tích hợp sẵn, nên một lần gọi xử lý được một hoặc nhiều mã số thuế.

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;
  }
}

Cấu trúc Phản hồi

{
  "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
    }
  ]
}

Các Loại Tra cứu

Trường type chọn chế độ tra cứu:

Loại Tra cứu	Mô tả
00001_CITIZEN_IDENTITY_CARD	Tra cứu theo căn cước công dân
00003_TAX_CODE	Tra cứu theo mã số thuế
00130_IDENTITY_CARD_TAX_PAYER	Tra cứu người nộp thuế theo CMND/CCCD
00132_PERSONAL_TAX_CODE	Tra cứu theo mã số thuế cá nhân

Trường status là mã do nhà cung cấp định nghĩa (ví dụ 00); BANA giữ nguyên giá trị này.

Chia lô & Lấy Toàn bộ

Một yêu cầu nhận tối đa 10 mã số thuế. Với mảng lớn hơn, bật fetchAll để service chia mảng thành các lô theo kích thước nhà cung cấp và gộp kết quả; thêm continueOnError để giữ lại kết quả từng phần khi một lô lỗi:

const response = await this.tvanService.queryTaxInformation({
  provider: 'vnpay',
  params: { type: TVanTaxInfoQueryTypes.TAX_CODE, taxCodes: manyTaxCodes },
  options: { fetchAll: true, continueOnError: true },
});

Chiến lược Caching

Thông tin thuế không thay đổi thường xuyên - hãy cache nó:

const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 giờ

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"]
}

Trả về { "result": [ ...TaxInfo ] }.

Xử lý Lỗi

T-VAN không tự định nghĩa danh mục lỗi. Lỗi được trả về từ response của nhà cung cấp (HTTP status + payload lỗi). Mảng taxCodes rỗng bị từ chối với thông báo Tax codes array cannot be empty trước khi đến nhà cung cấp.

Liên quan

• Tra cứu Thông điệp Hóa đơn
• Tài liệu tham khảo API
• Tổng quan T-VAN