Bắt đầu nhanh
Tạo ứng dụng, lấy token sandbox và phát hành một hoá đơn thử. Hoá đơn sandbox không gửi tới cơ quan thuế.
Giới thiệu
Làm trên Sandbox trước. Host là https://sandbox.api.hddt.dev. API key có tiền tố hddt_test_. Hoá đơn tạo ở đây không được gửi cơ quan thuế.
Ba giá trị đi cùng nhau trên mọi API hoá đơn: API key, App ID và token. Token lấy từ API Lấy token, hết hạn sau khoảng 1 giờ.
Chuẩn bị
Đăng nhập, tạo một ứng dụng. Ứng dụng mới mở ở Sandbox và đã có API key sandbox. Mở tab Kết nối & bảo mật, chọn Sandbox, rồi sao chép Base URL, App ID và API key.
Lấy token chỉ cần gửi App ID trên header cùng API key. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng. Đội hỗ trợ gắn tài khoản trên trang quản trị. Chưa có tài khoản thì API Lấy token trả 401.
Chỉ gọi từ server
Lấy token
Gửi POST /v1/invoices/token. Header api_key và app_id phải cùng một ứng dụng. Không có body. Không gửi username hay password.
curl -X POST https://sandbox.api.hddt.dev/v1/invoices/token \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID"Giữ token
Lấy mẫu
Gửi GET /v1/invoices/templates với năm trên query. Header Authorization mang token vừa lấy. Gửi kèm api_key và app_id. Lấy id của một mẫu để điền template_id lúc tạo hoá đơn. Chưa có mẫu trong năm đó thì data là mảng rỗng. Tạo mẫu bằng API Tạo mẫu hoá đơn.
curl "https://sandbox.api.hddt.dev/v1/invoices/templates?year=2026" \
-H "Authorization: Bearer $HDDT_TOKEN" \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID"Tạo hoá đơn
Gửi POST /v1/invoices. issue_mode bằng 1 là tạo và phát hành. invoice_type bằng 0 là hoá đơn mới. currency gửi VND thì exchange_rate là 1. Đủ trường bắt buộc của dòng hàng nằm ở trang Tạo hoá đơn.
Khi thành công, success là true. data.id là UUID của hoá đơn, data.number là số hoá đơn, data.lookup_code là mã tra cứu.
curl -X POST https://sandbox.api.hddt.dev/v1/invoices \
-H "Authorization: Bearer $HDDT_TOKEN" \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c1d6c3e-2f4b-4a8e" \
-d '{
"issue_mode": 1,
"invoice_type": 0,
"template_id": "1C26TAA",
"currency": "VND",
"exchange_rate": 1,
"items": [
{
"item_type": 1,
"line_number": 1,
"name": "Gói phần mềm",
"quantity": 1,
"unit_price": 5000000,
"amount_before_discount": 5000000,
"discount_rate": 0,
"discount_amount": 0,
"amount": 5000000,
"vat_rate": 10,
"tax_amount": 500000,
"line_total": 5500000
}
],
"subtotal": 5000000,
"trade_discount": 0,
"other_deduction": 0,
"tax_total": 500000,
"total": 5500000
}'Sandbox không ra cơ quan thuế
Tiếp theo
Đọc Xác thực để chọn đúng header cho từng API. Đọc Môi trường sandbox trước khi gọi Live. Danh sách đủ trường nằm ở trang Tạo hoá đơn. Muốn nhận kết quả sau khi phát hành, thêm webhook rồi xem trang Nhận và kiểm tra.