/v1/invoicesDanh sách hoá đơn
Lấy danh sách chi tiết hoá đơn theo bộ lọc. Tên trường là tiếng Anh, cùng key với API Tạo hoá đơn.
Giới thiệu
API trả danh sách chi tiết hoá đơn đã tạo trong ứng dụng. Mỗi phần tử trong data dùng cùng tên trường với body của API Tạo hoá đơn, kèm invoice_code (UUID, cùng data.id lúc tạo), number, lookup_code và status.
Bắt buộc gửi template_id. Các bộ lọc còn lại tuỳ chọn. Khi gửi cả issued_from và issued_to, khoảng tìm kiếm tối đa 10 ngày, tính cả hai đầu mút. Endpoint không trừ hạn mức phát hành.
Thử trên host sandbox.api.hddt.dev với token, API key tiền tố hddt_test_ và App ID. Dữ liệu Live trên api.hddt.dev với token và API key Live.
Endpoint
Gửi GET với bộ lọc trên query string. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.
Không có hoá đơn khớp bộ lọc vẫn trả success true và data là mảng rỗng.
Header
Token, API key và App ID phải cùng ứng dụng, cùng môi trường.
AuthorizationstringBắt buộcBearer token lấy từ API Lấy token.
api_keystringBắt buộcAPI key của ứng dụng.
app_idstringBắt buộcĐịnh danh ứng dụng (UUID). Sao chép App ID trên trang chi tiết ứng dụng (tab Kết nối & bảo mật).
Param
Nằm trên query string. Ngày lập dùng định dạng yyyy-MM-dd. Khi gửi cả issued_from và issued_to, khoảng tìm kiếm tối đa 10 ngày, tính cả ngày bắt đầu và ngày kết thúc.
template_idstringBắt buộcMã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA. Gồm ký hiệu mẫu số và ký hiệu hoá đơn.
issued_fromstring (date)Tuỳ chọnNgày lập bắt đầu, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_to thì khoảng tối đa 10 ngày.
issued_tostring (date)Tuỳ chọnNgày lập kết thúc, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_from thì khoảng tối đa 10 ngày.
numberintegerTuỳ chọnSố hoá đơn. Tối đa 8 chữ số.
invoice_codestringTuỳ chọnUUID của hoá đơn, cùng data.id trả về khi tạo.
invoice_kindintegerTuỳ chọnLoại hoá đơn cần lấy.
-1 tất cả, gồm hoá đơn nháp
0 tất cả, không gồm hoá đơn nháp
1 nháp
2 hoá đơn mới
3 hoá đơn xoá bỏ
4 hoá đơn thay thế
5 hoá đơn bị thay thế
6 hoá đơn điều chỉnh tăng
7 hoá đơn điều chỉnh giảm
8 hoá đơn điều chỉnh thông tin
9 hoá đơn điều chỉnh tăng và giảm
10 hoá đơn bị điều chỉnh
Tối đa 2 chữ số.
statusintegerTuỳ chọnTrạng thái hoá đơn.
-1 tất cả, gồm hoá đơn nháp
0 tất cả, không gồm hoá đơn nháp
1 nháp
2 lỗi ký
3 chưa gửi cơ quan thuế
4 đã cấp mã hoặc đã tiếp nhận
5 cơ quan thuế chưa phản hồi
6 không đủ điều kiện cấp mã hoặc tiếp nhận
Tối đa 2 chữ số.
customerstringTuỳ chọnTìm theo thông tin khách hàng. Khớp một trong buyer.name, buyer.tax_code, buyer.contact_name, reference. Tối đa 200 ký tự.
Ví dụ
Lấy hoá đơn của mẫu 1C26TAA lập từ 01/04 đến 10/04/2026, trạng thái đã cấp mã hoặc đã tiếp nhận. Khoảng ngày không quá 10 ngày.
curl "https://sandbox.api.hddt.dev/v1/invoices?template_id=1C26TAA&issued_from=2026-04-01&issued_to=2026-04-10&status=4" \
-H "Authorization: Bearer $HDDT_TOKEN" \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID"Phản hồi
Khi gọi được, success là true. data là mảng hoá đơn. Trường từ issue_mode trở xuống nằm trong từng phần tử và dùng cùng key với API Tạo hoá đơn.
successbooleanBắt buộctrue khi lấy được danh sách, false khi thất bại.
dataarrayBắt buộcDanh sách hoá đơn. Mảng rỗng khi không có hoá đơn khớp bộ lọc.
error_codestringBắt buộcTrống khi thành công. Khi thất bại là mã lỗi nghiệp vụ.
messagestringBắt buộcThông báo thành công hoặc thất bại.
invoice_codestringBắt buộcUUID của hoá đơn. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh.
numberintegerTuỳ chọnSố hoá đơn. Tối đa 8 chữ số.
lookup_codestringTuỳ chọnMã tra cứu. Tối đa 100 ký tự.
statusintegerBắt buộcTrạng thái hoá đơn.
1 nháp
2 lỗi ký
3 chưa gửi cơ quan thuế
4 đã cấp mã hoặc đã tiếp nhận
5 cơ quan thuế chưa phản hồi
6 không đủ điều kiện cấp mã hoặc tiếp nhận
issue_modeintegerTuỳ chọnCách tạo.
0 lưu nháp
1 tạo và phát hành
Tối đa 10 chữ số.
invoice_typeintegerBắt buộcTính chất hoá đơn.
0 hoá đơn mới
1 thay thế
2 điều chỉnh tăng
3 điều chỉnh giảm
4 điều chỉnh thông tin
5 điều chỉnh tăng và giảm
Tối đa 5 chữ số.
template_idstringTuỳ chọnMã mẫu, ví dụ 1C26TAA.
issued_atstring (date-time)Tuỳ chọnNgày lập hoá đơn.
currencystringBắt buộcMã tiền tệ ISO 4217.
VND Việt Nam đồng
USD đô la Mỹ
CAD đô la Canada
Hệ thống tự map sang mã của từng nhà cung cấp khi gọi nền tảng.
exchange_ratenumberBắt buộcTỷ giá. Với VND là 1. Tối đa 7 chữ số, 2 chữ số thập phân.
payment_methodstringTuỳ chọnHình thức thanh toán.
referencestringTuỳ chọnMã tham chiếu của hoá đơn trên hệ thống của bạn. Tối đa 20 ký tự.
notestringTuỳ chọnGhi chú. Tối đa 255 ký tự.
related_invoice_idstringTuỳ chọnUUID của hoá đơn gốc, lấy từ id của hoá đơn đó, khi invoice_type là thay thế hoặc điều chỉnh.
seller_store_codestringTuỳ chọnMã cửa hàng, điểm bán. Xem mục Người bán. Tối đa 50 ký tự.
seller_store_namestringTuỳ chọnTên cửa hàng, điểm bán. Xem mục Người bán. Tối đa 400 ký tự.
buyerobjectTuỳ chọnNgười mua. Xem mục Người mua.
itemsarrayBắt buộcDanh sách hàng hoá, dịch vụ. Xem mục Dòng hàng.
feesarrayTuỳ chọnDanh sách phí, lệ phí. Xem mục Loại phí.
subtotalnumberBắt buộcTổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân.
trade_discountnumberBắt buộcTổng tiền chiết khấu thương mại. Tối đa 21 chữ số, 6 chữ số thập phân.
other_deductionnumberBắt buộcTổng giảm trừ khác. Tối đa 21 chữ số, 6 chữ số thập phân.
tax_totalnumberBắt buộcTổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân.
totalnumberBắt buộcTổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân.
total_in_wordsstringTuỳ chọnTổng tiền thanh toán bằng chữ. Tối đa 255 ký tự.
{
"success": true,
"data": [
{
"invoice_code": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"number": 125,
"lookup_code": "7B164DE808",
"status": 4,
"issue_mode": 1,
"invoice_type": 0,
"template_id": "1C26TAA",
"issued_at": "2026-04-11T06:46:41.850Z",
"currency": "VND",
"exchange_rate": 1,
"payment_method": "TM/CK",
"reference": "DH-1001",
"seller_store_code": "CH01",
"seller_store_name": "Cửa hàng Quận 1",
"buyer": {
"name": "Công ty TNHH ABC",
"tax_code": "0312345678",
"address": "123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh",
"email": "[email protected]"
},
"items": [
{
"item_type": 1,
"line_number": 1,
"name": "Gói phần mềm",
"unit": "Gói",
"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,
"total_in_words": "Năm triệu năm trăm nghìn đồng"
}
],
"error_code": "",
"message": "Thành công"
}Người bán
Tên, mã số thuế và địa chỉ người bán lấy từ tài khoản đã đăng nhập. Đơn vị có nhiều điểm bán nhận lại mã cửa hàng và tên cửa hàng đã gửi lúc tạo hoá đơn. Hai trường có mặt khi hoá đơn có thông tin điểm bán.
seller_store_codestringTuỳ chọnMã cửa hàng, điểm bán. Tối đa 50 ký tự.
seller_store_namestringTuỳ chọnTên cửa hàng, điểm bán. Tối đa 400 ký tự.
Người mua
Các trường trong buyer. Có mặt khi hoá đơn có thông tin người mua.
namestringTuỳ chọnTên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự.
tax_codestringTuỳ chọnMã số thuế người mua. Tối đa 14 ký tự.
addressstringTuỳ chọnĐịa chỉ. Tối đa 400 ký tự.
codestringTuỳ chọnMã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự.
phonestringTuỳ chọnSố điện thoại. Tối đa 20 ký tự.
emailstringTuỳ chọnEmail. Tối đa 50 ký tự.
contact_namestringTuỳ chọnHọ và tên người mua hàng. Tối đa 100 ký tự.
bank_accountstringTuỳ chọnSố tài khoản ngân hàng.
bank_namestringTuỳ chọnTên ngân hàng.
citizen_idstringTuỳ chọnSố định danh cá nhân (CCCD). Tối đa 12 ký tự.
budget_unit_codestringTuỳ chọnMã đơn vị quan hệ ngân sách. Tối đa 7 ký tự.
passportstringTuỳ chọnSố hộ chiếu hoặc giấy tờ nhập xuất cảnh. Tối đa 20 ký tự.
Dòng hàng
Mỗi phần tử của items là một dòng hàng hoá hoặc dịch vụ.
item_typeintegerBắt buộcTính chất dòng.
1 hàng hoá, dịch vụ
2 khuyến mãi
3 chiết khấu
4 ghi chú
line_numberintegerBắt buộcSố thứ tự dòng. Tối đa 4 chữ số.
codestringTuỳ chọnMã hàng hoá, dịch vụ. Tối đa 50 ký tự.
namestringBắt buộcTên hàng hoá, dịch vụ. Tối đa 500 ký tự.
unitstringTuỳ chọnĐơn vị tính. Tối đa 50 ký tự.
quantitynumberBắt buộcSố lượng. Tối đa 21 chữ số, 6 chữ số thập phân.
unit_pricenumberBắt buộcĐơn giá. Tối đa 21 chữ số, 6 chữ số thập phân.
amount_before_discountnumberBắt buộcThành tiền trước thuế, trước chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân.
discount_ratenumberBắt buộcTỷ lệ chiết khấu, đơn vị phần trăm. Tối đa 6 chữ số, 4 chữ số thập phân.
discount_amountnumberBắt buộcSố tiền chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân.
amountnumberBắt buộcThành tiền trước thuế, sau chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân.
vat_ratenumberBắt buộcThuế suất.
-2 không kê khai, không nộp thuế
-1 không chịu thuế
0 0%
5 5%
8 8%
10 10%
3.5 thuế suất khác
tax_amountnumberBắt buộcTiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân.
line_totalnumberBắt buộcTiền sau thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân.
Loại phí
Mỗi phần tử của fees là một loại phí.
namestringTuỳ chọnTên loại phí. Tối đa 100 ký tự.
amountnumberTuỳ chọnTiền phí. Tối đa 21 chữ số, 6 chữ số thập phân.
Mã lỗi
Khi không lấy được danh sách, success là false, error_code và message mô tả lỗi nghiệp vụ. Lỗi xác thực và định dạng của hddt.dev vẫn trả mã HTTP kèm error.code và error.message. Ngoài các mã dưới đây, xem thêm trang Mã lỗi.
400 bad_request—Tuỳ chọnRequest sai định dạng.
401 unauthorized—Tuỳ chọnThiếu token hoặc header api_key, token hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token.
422 validation_error—Tuỳ chọnThiếu template_id, template_id không đúng ký hiệu mẫu số và ký hiệu hoá đơn, ngày không đúng yyyy-MM-dd, hoặc invoice_kind, status ngoài danh mục.
429 rate_limited—Tuỳ chọnVượt giới hạn số request cho phép.