# Danh sách mẫu đã đăng ký > Chỉ dùng endpoint, field, mã lỗi và ví dụ trong trang này. Không thêm API chưa được mô tả ở đây. `GET /v1/invoices/templates/registered` 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. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `api_key` | string | có | API key của ứng dụng. | | `app_id` | string | 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: ```bash 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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | 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. | | `object` | string | có | Luôn là invoice_template_registration. | | `template_id` | string | có | Ghé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. | | `form` | string | có | Ký hiệu mẫu số hoá đơn, ví dụ 1. | | `serial` | string | có | Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TTV. | | `year` | integer | có | Năm suy từ hai số trong serial. | | `quantity` | integer | có | Số lượng hoá đơn đã cấp cho mẫu. | | `used` | integer | có | Số lượng đã dùng. | | `remaining` | integer | có | Số lượng còn lại. | | `invoice_category_name` | string | không | Tên loại hoá đơn, ví dụ Hóa đơn giá trị gia tăng. | | `published` | boolean | có | true khi mẫu đã được duyệt.
false khi mẫu còn chưa duyệt. | 200 OK: ```json { "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: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiế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` | — | không | Ứ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 đó. | Trang HTML: /docs/invoices/templates/registered Cập nhật: 04/11/2026