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ả
Dịch vụ	TVanService.getTaxInfo()
Nguồn Dữ liệu	CQT (Cơ quan Thuế)
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 Đơn lẻ

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

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

{
  "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": "Bán lẻ",
  "phoneNumber": "028-1234-5678"
}

Trạng thái Doanh nghiệp

Trạng thái	Mô tả	Có thể Xuất Hóa đơn
ACTIVE	Hoạt động bình thường	Có
SUSPENDED	Tạm ngừng hoạt động	Không
CLOSED	Đã giải thể	Không
PENDING	Đang chờ đăng ký	Không

Tra cứu Hàng loạt

Truy vấn nhiều doanh nghiệp cùng lúc:

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

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

# Tra cứu hàng loạt
POST /api/t-van/tax-info/batch
Content-Type: application/json

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

Xử lý Lỗi

Mã lỗi	Mô tả	Giải pháp
TVAN_001	Định dạng không hợp lệ	Mã số thuế phải có 10 hoặc 13 chữ số
TVAN_002	Không tìm thấy	Mã số thuế chưa được đăng ký
TVAN_003	Quá hạn	Thử lại hoặc kiểm tra mạng

Liên quan

• Xác thực Hóa đơn
• Tài liệu tham khảo API
• Tổng quan T-VAN