T-VAN API Reference
Complete API reference for T-VAN integration. Endpoints are mounted under the /t-van controller path.
Base URL
Production: https://api.your-domain.com/t-van
Development: http://localhost:3000/t-vanTax Information Endpoint
Query Tax Information
Batching is built into the request - pass up to 10 tax codes in the taxCodes array.
POST /tax-information?provider=vnpay
Content-Type: application/json
{
"type": "00003_TAX_CODE",
"taxCodes": ["0100231226-999", "0100240615", "0100256887"]
}
Response:
{
"result": [
{
"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 parameters: provider (optional, e.g. vnpay), fetchAll (optional, auto-batch arrays over the provider limit), continueOnError (optional, tolerate failed batches when fetchAll is on).
Tax info query types (the type field): 00001_CITIZEN_IDENTITY_CARD, 00003_TAX_CODE, 00130_IDENTITY_CARD_TAX_PAYER, 00132_PERSONAL_TAX_CODE.
Invoice Messages Endpoint
Query Invoice Messages
Lists and paginates the provider's e-invoice processing messages. All filters are passed as query parameters.
GET /invoices?provider=vnpay&messageTypeCode=200&messageCode=V0102182292A68308EFF92148B0A26&taxPayerTaxCode=1801545696-999&invoiceNumberSymbol=1&invoiceSymbol=C22THC&invoiceNumber=13&invoiceIssuerTaxCode=0101352495&fromDate=2022-04-25T14:00:00&toDate=2022-04-26T14:00:00&page=0&size=10
Response:
{
"messages": [
{
"id": 3,
"invoiceNumberSymbol": "1",
"invoiceSymbol": "C22TPP",
"messageTypeCode": 200,
"messageCode": "V03123038035DE0AA1AC6C34EBAA03F54BD026AA35B",
"responseMessageCode": "V03123038035DE0AA1AC6C34EBAA03F54BD026AA35B",
"invoiceIssuerTaxCode": "0101352495",
"invoiceNumber": 262,
"taxPayerTaxCode": "0102182292-998",
"taxDepartmentCode": "-1",
"invoiceCreatedAt": "2024-01-01T00:00:00",
"status": 5,
"information": "Nhận thông tin lỗi từ tổng cục thuế",
"reason": "02-CTS không phải do nhà CA cung cấp",
"createdAt": "2024-01-01T00:00:00"
}
],
"currentPage": 0,
"pageSize": 10,
"totalPages": 5,
"totalItems": 50
}Add fetchAll=true to auto-aggregate every page into a single messages array.
Error Responses
T-VAN does not define its own error catalogue. Failures are surfaced from the provider response (HTTP status + provider error payload). A request with an empty taxCodes array is rejected before reaching the provider:
{
"error": {
"message": "Tax codes array cannot be empty"
}
}Inspect the provider response payload and the service logs for provider-side failures.
Provider Selection
Select a registered client with the optional provider query parameter:
POST /tax-information?provider=vnpay
GET /invoices?provider=vnpayWhen omitted, the default client is used. There is no client-selection header or client parameter.