TVAN

Gửi thông điệp hóa đơn điện tử tới hệ thống TVAN để xử lý và chuyển tiếp tới cơ quan thuế.

Tài liệu về API

Chi tiết TVAN yêu cầu, phản hồi và code mẫu

Xem chi tiết TVAN API

Bắt đầu

Tìm hiểu về các thông tin để triển khai và cách thức hoạt động.

Bắt đầu

AI Agent

Cài skill để AI coding agent tích hợp Cas chính xác theo codebase của bạn

Tích hợp với AI Agent

Các bước tích hợp TVAN

Dưới đây là các bước để tích hợp TVAN vào sản phẩm của bạn.

1. Tạo một phân quyền /grant/token với scopes có giá trị là invoice.

• taxDeclaration (tuỳ chọn): thông tin tờ khai đăng ký sử dụng hoá đơn điện tử, dùng để tự động điền sẵn tờ khai X-Invoice trên Cas ID khi người dùng đăng ký. Xem chi tiết

2. Mở giao diện Cas Link bằng grantToken được trả về ở bước trên và lựa chọn dịch vụ X-Invoice. Xem chi tiết

3. Sau khi người dùng hoàn tất xác thực, phía giao diện của bạn sẽ nhận được một publicToken, dùng publicToken này để lấy accessToken cho phân quyền.

4. Bây giờ bạn đã có thể gọi API gửi thông điệp.

Thông tin tờ khai đăng ký (taxDeclaration)

taxDeclaration là trường tuỳ chọn khi tạo phân quyền, áp dụng cho dịch vụ X-Invoice. Nếu hệ thống của bạn đã có sẵn thông tin đăng ký sử dụng hoá đơn điện tử của khách hàng, hãy truyền vào để Cas ID tự động điền sẵn tờ khai đăng ký (mẫu 01/ĐKTĐ-HĐĐT), người dùng không cần nhập lại.

Trường	Kiểu	Mô tả
email	string	Email liên hệ
registrationType	number	Hình thức tờ khai: 1 - Đăng ký mới, 2 - Thay đổi thông tin
invoiceType	string[]	Hình thức hóa đơn: WITH_TAX_AUTHORITY_CODE - Có mã của cơ quan thuế, FROM_POS - Hóa đơn khởi tạo từ Máy tính tiền
invoiceUsageType	string[]	Loại hóa đơn sử dụng: VAT - Hóa đơn giá trị gia tăng, SALE - Hóa đơn bán hàng

ghi chú

Trường nào không truyền, Cas ID sẽ dùng giá trị mặc định hoặc để trống cho người dùng tự nhập.

Gọi API

Tạo phân quyền cho TVAN

CURL

curl --location 'https://sandbox.bankhub.dev/grant/token' \
--header 'X-BankHub-Api-Version: 2023-01-01' \
--header 'x-client-id: <CLIENT_ID_HERE>' \
--header 'x-secret-key: <SECRET_KEY_HERE>' \
--header 'Content-Type: application/json' \
--data '{
    "scopes": "invoice",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
    "fiServiceId": "6d325840-00d7-11f1-af82-fa163e5398eb",
    "taxDeclaration": {
        "email": "nguyenvana@gmail.com",
        "registrationType": 1,
        "invoiceType": ["WITH_TAX_AUTHORITY_CODE"],
        "invoiceUsageType": ["VAT"]
    }
}'

Javascript (Axios)

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "invoice",
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
   "fiServiceId": "6d325840-00d7-11f1-af82-fa163e5398eb",
   "taxDeclaration": {
     "email": "nguyenvana@gmail.com",
     "registrationType": 1,
     "invoiceType": ["WITH_TAX_AUTHORITY_CODE"],
     "invoiceUsageType": ["VAT"]
   }
 });

 const config = {
   method: 'post',
   maxBodyLength: Infinity,
   url: 'https://sandbox.bankhub.dev/grant/token',
   headers: { 
     'X-BankHub-Api-Version': '2023-01-01', 
     'x-client-id': '<CLIENT_ID_HERE>', 
     'x-secret-key': '<SECRET_KEY_HERE>', 
     'Content-Type': 'application/json',
   },
   data: data
 };

 axios.request(config)
 .then((response) => {
   console.log(JSON.stringify(response.data));
 })
 .catch((error) => {
   console.log(error);
 });

thông tin

Xem chi tiết API, tại đây

Lấy accessToken từ publicToken

CURL

  curl --location 'https://sandbox.bankhub.dev/grant/exchange' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
      "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  }'

Javascript (Axios)

  const axios = require('axios');
  const data = JSON.stringify({
    "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  });

  const config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/grant/exchange',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>', 
      'Content-Type': 'application/json'
    },
    data: data
  };

  axios.request(config)
    .then((response) => {
      console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
      console.log(error);
    });

thông tin

Xem chi tiết API, tại đây

API gửi thông điệp hóa đơn điện tử tới hệ thống TVAN để xử lý và chuyển tiếp tới cơ quan thuế.

CURL

  curl --location 'https://sandbox.bankhub.dev/tvan/send' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'Authorization: <ACCESS_TOKEN_HERE>' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>'
  --data-raw '{
    "xmlData": [
      {
        "xml": "<HDon></HDon>"
      }
    ],
    "xmlCount": 1,
    "messageTypeCode": 206
  }'

Javascript (Axios)

  const axios = require('axios');
  let data = JSON.stringify({
    "xmlData": [
      {
        "xml": "<HDon></HDon>"
      }
    ],
    "xmlCount": 1,
    "messageTypeCode": 206
  });

  let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/tvan/send',
    headers: { 
      'Content-Type': 'application/json', 
      'Accept': 'application/json', 
      'x-client-id': '<x-client-id>', 
      'x-secret-key': '<x-client-id>', 
      'Authorization': '<x-client-id>'
    },
    data : data
  };

  axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

thông tin

Xem chi tiết API, tại đây