Tài liệu API hddt.dev
hddt.dev cung cấp REST API để phát hành, quản lý và tra cứu hoá đơn điện tử theo Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC. Mọi request và phản hồi đều dùng JSON.
Bản cho AI, chỉ gồm API đã có trang tài liệu: llms.txt · llms-full.txt · openapi.json
Base URL
Mọi endpoint đều có tiền tố phiên bản. Dùng môi trường sandbox để thử nghiệm — hoá đơn tạo trên sandbox không được gửi tới cơ quan thuế.
https://api.hddt.dev/v1https://sandbox.api.hddt.dev/v1Xác thực
Tạo API key trong trang quản trị. API ứng dụng và Lấy token gửi key trong header api_key. Các API hoá đơn, sau khi lấy token, gửi token trong Authorization và API key trong header api_key. Tra cứuMST vẫn dùng Authorization: Bearer với API key. Key sandbox có tiền tố hddt_test_, key Live có tiền tố hddt_live_.
curl https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-H "api_key: $HDDT_API_KEY"Giữ bí mật API key
Request đầu tiên
/v1/invoicesVí dụ dưới đây phát hành một hoá đơn trên Sandbox. Header Authorization mang token từ API Lấy token. Header api_key và app_id mang API key và App ID của cùng ứng dụng, cùng môi trường với token.
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 '{
"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
}'Body
invoice_typeintegerBắt buộcTính chất hoá đơn. 0 là hoá đơn mới.
template_idstringTuỳ chọnMã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA.
currencystringBắt buộcMã tiền tệ ISO 4217. VND là Việt Nam đồng.
exchange_ratenumberBắt buộcTỷ giá. Với VND gửi 1.
subtotalnumberBắt buộcTổng tiền trước thuế.
trade_discountnumberBắt buộcTổng chiết khấu thương mại. Gửi 0 nếu không có.
other_deductionnumberBắt buộcTổng giảm trừ khác. Gửi 0 nếu không có.
tax_totalnumberBắt buộcTổng tiền thuế.
totalnumberBắt buộcTổng tiền thanh toán.
itemsarrayBắt buộcDòng hàng. Mỗi dòng bắt buộc có item_type, line_number, name, quantity, unit_price, amount_before_discount, discount_rate, discount_amount, amount, vat_rate, tax_amount, line_total.
Phản hồi
Khi thành công, success là true. data chứa mã hoá đơn, số hoá đơn và mã tra cứu. Danh sách đủ trường bắt buộc nằm ở trang Tạo hoá đơn.
{
"success": true,
"data": {
"invoice_code": "inv_8f2a1c9d",
"number": 125,
"lookup_code": "ABC123"
},
"error_code": "",
"message": "Thành công"
}Mẹo
Idempotency-Key để tránh phát hành trùng hoá đơn khi request bị retry do lỗi mạng.Mã lỗi
hddt.dev dùng mã trạng thái HTTP chuẩn. Phần thân lỗi luôn có error.code và error.message.
| HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 400 | bad_request | Request sai định dạng hoặc thiếu tham số bắt buộc. |
| 401 | unauthorized | API key hoặc token không hợp lệ. API hoá đơn còn từ chối khi thiếu header api_key hoặc key không cùng ứng dụng với token. |
| 404 | not_found | Không tìm thấy tài nguyên được yêu cầu. |
| 409 | conflict | Trùng Idempotency-Key với request khác nội dung. |
| 422 | validation_error | Dữ liệu không hợp lệ theo quy định của CQT. |
| 429 | rate_limited | Vượt giới hạn số request cho phép. |