Tài liệu tham khảo API T-VAN

Tài liệu tham khảo API đầy đủ cho tích hợp T-VAN. Các endpoint được gắn dưới đường dẫn controller /t-van.

URL Cơ sở

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

Endpoint Thông tin Thuế

Tra cứu Thông tin Thuế

Chia lô được tích hợp trong yêu cầu - truyền tối đa 10 mã số thuế trong mảng taxCodes.

POST /tax-information?provider=vnpay
Content-Type: application/json

{
  "type": "00003_TAX_CODE",
  "taxCodes": ["0100231226-999", "0100240615", "0100256887"]
}

Phản hồi:
{
  "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
    }
  ]
}

Tham số truy vấn: provider (tùy chọn, ví dụ vnpay), fetchAll (tùy chọn, tự động chia lô mảng vượt giới hạn nhà cung cấp), continueOnError (tùy chọn, bỏ qua lô lỗi khi bật fetchAll).

Các loại tra cứu thông tin thuế (trường type): 00001_CITIZEN_IDENTITY_CARD, 00003_TAX_CODE, 00130_IDENTITY_CARD_TAX_PAYER, 00132_PERSONAL_TAX_CODE.

Endpoint Thông điệp Hóa đơn

Tra cứu Thông điệp Hóa đơn

Liệt kê và phân trang các thông điệp xử lý hóa đơn điện tử của nhà cung cấp. Mọi bộ lọc được truyền dưới dạng tham số truy vấn.

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

Phản hồi:
{
  "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
}

Thêm fetchAll=true để gộp mọi trang vào một mảng messages duy nhất.

Phản hồi 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). Yêu cầu có mảng taxCodes rỗng bị từ chối trước khi đến nhà cung cấp:

{
  "error": {
    "message": "Tax codes array cannot be empty"
  }
}

Hãy kiểm tra payload response của nhà cung cấp và log service đối với các lỗi phía nhà cung cấp.

Chọn Nhà cung cấp

Chọn client đã đăng ký bằng tham số truy vấn provider tùy chọn:

POST /tax-information?provider=vnpay
GET  /invoices?provider=vnpay

Khi bỏ trống, client mặc định được dùng. Không có header chọn client và cũng không có tham số client.

Liên quan

• Tra cứu Thuế
• Tra cứu Thông điệp Hóa đơn
• Tuân thủ