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ệuLấy mẫu hoá đơn
GET/v1/invoices/templates

Lấ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.

MarkdownOpenAPI

#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ộ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).

#Param

Nằm trên query string.

yearintegerBắt buộc

Nă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
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ộc

Giá 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ộc

Luôn là invoice_template.

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ụ C26TAA. Xem mục Ký hiệu.

yearintegerBắt buộc

Năm của mẫu, trùng năm đã gửi trên query.

has_tax_authority_codebooleanBắt buộc

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

Ký tự loại hoá đơn, ký tự thứ tư của serial. Một trong T, D, L, M, N, B, G, H.

200 OK
{
  "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
THoá đơn doanh nghiệp đăng ký với cơ quan thuế.
DBán tài sản công, hàng dự trữ quốc gia hoặc hoá đơn đặc thù.
LHoá đơn cấp theo từng lần phát sinh.
MHoá đơn khởi tạo từ máy tính tiền.
NPhiếu xuất kho kiêm vận chuyển nội bộ.
BPhiếu xuất kho hàng gửi bán đại lý.
GTem, vé, thẻ dạng hoá đơn giá trị gia tăng.
HTem, 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ọ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.

422 validation_error—Tuỳ chọn

Thiếu year hoặc year không phải năm dương lịch 4 chữ số.

Trước đóLấy tokenTiếp theoDanh sách mẫu đã đăng ký
Trang này có hữu ích không?
Cập nhật lần cuối: 09/11/2026

Trên trang này

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