/v1/invoices/templates/registeredDanh sách mẫu đã đăng ký
Danh sách mẫu số và ký hiệu hoá đơn đã tạo trên trang quản lý, kèm số lượng đã dùng và còn lại của từng mẫu.
Giới thiệu
API trả các mẫu hoá đơn doanh nghiệp đã tạo trên trang quản lý, gồm mẫu số, ký hiệu, số lượng đã cấp, đã dùng và còn lại. Dùng để đối chiếu hạn mức từng mẫu hoặc lấy id mẫu chưa duyệt trước khi xoá / duyệt số lượng.
Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.
Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.
Khác với API Lấy mẫu hoá đơn theo năm: endpoint đó dùng khi chọn template_id lúc tạo hoá đơn; endpoint này đọc sổ mẫu đã đăng ký kèm số lượng.
Endpoint
Gửi GET không có query. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.
Chưa có mẫu nào vẫn trả 200 với 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).
Ví dụ
Request mẫu trên sandbox. Token lấy từ mục Lấy token.
curl https://sandbox.api.hddt.dev/v1/invoices/templates/registered \
-H "Authorization: Bearer $HDDT_TOKEN" \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID"Phản hồi
Khi token còn hiệu lực, API trả 200 OK.
idstringBắt buộcĐịnh danh mẫu đã đăng ký trên trang quản lý. Dùng khi duyệt số lượng hoặc xoá mẫu chưa duyệt.
objectstringBắt buộcLuôn là invoice_template_registration.
template_idstringBắt buộcGhép mẫu số và ký hiệu, ví dụ 1C26TTV. Có thể dùng tương ứng template_id khi tạo hoá đơn.
formstringBắt buộcKý hiệu mẫu số hoá đơn, ví dụ 1.
serialstringBắt buộcKý hiệu hoá đơn, 6 ký tự, ví dụ C26TTV.
yearintegerBắt buộcNăm suy từ hai số trong serial.
quantityintegerBắt buộcSố lượng hoá đơn đã cấp cho mẫu.
usedintegerBắt buộcSố lượng đã dùng.
remainingintegerBắt buộcSố lượng còn lại.
invoice_category_namestringTuỳ chọnTên loại hoá đơn, ví dụ Hóa đơn giá trị gia tăng.
publishedbooleanBắt buộctrue khi mẫu đã được duyệt.
false khi mẫu còn chưa duyệt.
{
"object": "list",
"data": [
{
"id": "13362",
"object": "invoice_template_registration",
"template_id": "1C26TDV",
"form": "1",
"serial": "C26TDV",
"year": 2026,
"quantity": 10,
"used": 0,
"remaining": 10,
"invoice_category_name": "Hóa đơn giá trị gia tăng",
"published": true
}
]
}Mã lỗi
Các trường hợp thường gặp:
401 unauthorized—Tuỳ chọnThiếu token hoặc header api_key, token sai hoặc 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. Gọi lại API Lấy token nếu token hết hạn.
502 bad_gateway—Tuỳ chọnỨng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.