hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuDanh sách mẫu đã đăng ký
GET/v1/invoices/templates/registered

Danh 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.

MarkdownOpenAPI

#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ộc

Bearer token lấy từ API Lấy token.

api_keystringBắt buộc

API 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
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ộc

Luôn là invoice_template_registration.

template_idstringBắt buộ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.

formstringBắt buộc

Ký hiệu mẫu số hoá đơn, ví dụ 1.

serialstringBắt buộc

Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TTV.

yearintegerBắt buộc

Năm suy từ hai số trong serial.

quantityintegerBắt buộc

Số lượng hoá đơn đã cấp cho mẫu.

usedintegerBắt buộc

Số lượng đã dùng.

remainingintegerBắt buộc

Số lượng còn lại.

invoice_category_namestringTuỳ chọn

Tên loại hoá đơn, ví dụ Hóa đơn giá trị gia tăng.

publishedbooleanBắt buộc

true khi mẫu đã được duyệt.

false khi mẫu còn chưa duyệt.

200 OK
{
  "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ọn

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—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 đó.

Trước đóLấy mẫu hoá đơnTiếp theoHạn mức hoá đơn
Trang này có hữu ích không?
Cập nhật lần cuối: 04/11/2026

Trên trang này

  • Giới thiệu
  • Endpoint
  • Header
  • Ví dụ
  • Phản hồi
  • Mã lỗi
Đăng nhậpBắt đầu ngay