/v1/invoices/templatesLấy mẫu hoá đơn
Danh sách mẫu số và ký hiệu hoá đơn đã đăng ký theo năm, để chọn template_id khi tạo hoá đơn.
Giới thiệu
API trả các mẫu hoá đơn doanh nghiệp đã đăng ký và còn dùng trong một năm. Khi tạo hoá đơn, gửi id của mẫu vào template_id.
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. Endpoint không trừ hạn mức phát hành.
Muốn xem sổ mẫu kèm số lượng đã dùng, tạo / duyệt / xoá mẫu trên trang quản lý, dùng các API trong nhóm mẫu hoá đơn ngay sau mục này. Các API đó giữ cùng cách gọi (token + api_key + app_id); hệ thống tự dùng tài khoản trang quản lý đã gắn với ứng dụng, không gửi username hay password trang quản lý trong request.
Endpoint
Gửi GET kèm năm 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ó mẫu nào trong năm đó 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).
Param
Nằm trên query string.
yearintegerBắt buộcNăm dương lịch của mẫu đã đăng ký, 4 chữ số. Ví dụ 2026.
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?year=2026" \
-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ộcGiá trị gửi vào template_id khi tạo hoá đơn. Ghép ký hiệu mẫu số và ký hiệu hoá đơn, ví dụ 1C26TAA.
objectstringBắt buộcLuôn là invoice_template.
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ụ C26TAA. Xem mục Ký hiệu.
yearintegerBắt buộcNăm của mẫu, trùng năm đã gửi trên query.
has_tax_authority_codebooleanBắt buộctrue khi ký tự đầu của serial là C (có mã cơ quan thuế).
false khi là K (không mã).
invoice_typestringBắt buộcKý tự loại hoá đơn, ký tự thứ tư của serial. Một trong T, D, L, M, N, B, G, H.
{
"object": "list",
"data": [
{
"id": "1C26TAA",
"object": "invoice_template",
"form": "1",
"serial": "C26TAA",
"year": 2026,
"has_tax_authority_code": true,
"invoice_type": "T"
}
]
}Ký hiệu
serial gồm 6 ký tự. Ký tự đầu là C (có mã cơ quan thuế) hoặc K (không mã). Hai số tiếp theo là hai số cuối của năm lập. Ký tự thứ tư là loại hoá đơn. Hai ký tự cuối do người bán tự đặt để phân biệt các mẫu cùng loại; nếu không cần phân biệt thì thường là YY.
| Ký tự | Loại hoá đơn |
|---|---|
| T | Hoá đơn doanh nghiệp đăng ký với cơ quan thuế. |
| D | Bán tài sản công, hàng dự trữ quốc gia hoặc hoá đơn đặc thù. |
| L | Hoá đơn cấp theo từng lần phát sinh. |
| M | Hoá đơn khởi tạo từ máy tính tiền. |
| N | Phiếu xuất kho kiêm vận chuyển nội bộ. |
| B | Phiếu xuất kho hàng gửi bán đại lý. |
| G | Tem, vé, thẻ dạng hoá đơn giá trị gia tăng. |
| H | Tem, vé, thẻ dạng hoá đơn bán hàng. |
Mã lỗi
Các trường hợp thường gặp khi lấy mẫu:
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.
422 validation_error—Tuỳ chọnThiếu year hoặc year không phải năm dương lịch 4 chữ số.