T-VAN API Reference

Complete API reference for T-VAN integration.

Base URL

Production: https://api.your-domain.com/api/t-van
Development: http://localhost:3000/api/t-van

Tax Info Endpoints

Get Tax Information

GET /tax-info/:taxCode

Response:
{
  "taxCode": "0123456789",
  "companyName": "CÔNG TY TNHH ABC",
  "address": "123 Nguyễn Huệ, Quận 1",
  "representative": "Nguyễn Văn A",
  "status": "ACTIVE",
  "registrationDate": "2020-01-15"
}

Batch Lookup

POST /tax-info/batch
Content-Type: application/json

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

Response:
{
  "results": [
    { "taxCode": "0123456789", "found": true, "status": "ACTIVE", ... },
    { "taxCode": "9876543210", "found": false }
  ]
}

Invoice Endpoints

Validate Invoice

POST /invoice/validate
Content-Type: application/json

{
  "invoiceNumber": "AA/24E0001234",
  "sellerTaxCode": "0123456789",
  "invoiceDate": "2024-01-15"
}

Response:
{
  "isValid": true,
  "status": "VALID",
  "invoiceNumber": "AA/24E0001234",
  "totalAmount": 1100000
}

Error Responses

{
  "error": {
    "code": "TVAN_002",
    "message": "Tax code not found"
  }
}

Error Codes

Code	Description
TVAN_001	Invalid tax code format
TVAN_002	Tax code not found
TVAN_003	Connection timeout
TVAN_004	Provider error
TVAN_005	Rate limit exceeded

Multi-Client Usage

Specify client in request headers:

GET /tax-info/0123456789
X-TVAN-Client: backup

Or in query parameter:

GET /tax-info/0123456789?client=backup

Related

• Tax Lookup
• Invoice Validation
• Compliance