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ệuTạo mẫu hoá đơn
POST/v1/invoices/templates

Tạo mẫu hoá đơn

Tạo mẫu số–ký hiệu mới. Gửi ký hiệu mẫu, năm lập, loại hoá đơn thường hoặc máy tính tiền, và hai ký tự cuối do người bán tự đặt. Bỏ trống ô có mã thì hiểu là có mã cơ quan thuế.

MarkdownOpenAPI

#Giới thiệu

API tạo một mẫu hoá đơn mới trên trang quản lý. Gửi ký hiệu mẫu, năm lập, chọn hoá đơn điện tử bình thường hoặc hoá đơn máy tính tiền, và hai ký tự cuối để phân biệt mẫu. Có mã cơ quan thuế hay không là tuỳ chọn; bỏ trống thì là có mã. Hệ thống ghép ký hiệu và tự chọn thiết kế mẫu.

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.

Sau khi tạo, mẫu thường chưa duyệt. Dùng Duyệt số lượng hoá đơn để cấp số lượng, hoặc Xoá mẫu chưa duyệt nếu tạo nhầm.

#Endpoint

Gửi POST với body JSON. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.

Path trùng với GET Lấy mẫu hoá đơn theo năm; method POST dùng để tạo mẫu mới.

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

Content-TypestringBắt buộc

application/json.

#Body

Gửi form, year, cash_register và suffix. has_tax_authority_code bỏ trống thì hoá đơn có mã cơ quan thuế. API ghép serial 6 ký tự: ký tự 1 là C hoặc K, ký tự 2–3 là hai số cuối của year, ký tự 4 là T hoặc M, ký tự 5–6 là suffix.

formstringBắt buộc

Ký hiệu mẫu số.

1 Hoá đơn giá trị gia tăng

2 Hoá đơn bán hàng

has_tax_authority_codebooleanTuỳ chọn

Hoá đơn có mã của cơ quan thuế hay không. Bỏ trống thì là có mã.

true khi có mã. Ký tự 1 của serial là C.

false khi không có mã. Ký tự 1 của serial là K.

yearintegerBắt buộc

Năm lập hoá đơn, 4 chữ số. Hai số cuối thành ký tự 2–3 của serial. Năm 2026 ghi thành 26.

cash_registerstringBắt buộc

Cách lập hoá đơn.

0 Hoá đơn điện tử bình thường. Ký tự 4 của serial là T

1 Hoá đơn máy tính tiền. Ký tự 4 của serial là M

suffixstringBắt buộc

Hai ký tự cuối của serial, do người bán tự đặt để phân biệt các mẫu cùng loại. Đúng 2 chữ cái, ví dụ TV.

#Ví dụ

Request mẫu trên sandbox: hoá đơn GTGT, có mã (bỏ trống has_tax_authority_code), năm 2026, hoá đơn điện tử bình thường, hai ký tự cuối TV. Serial được ghép là C26TTV.

cURL
curl -X POST https://sandbox.api.hddt.dev/v1/invoices/templates \
  -H "Authorization: Bearer $HDDT_TOKEN" \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "form": "1",
    "year": 2026,
    "cash_register": "0",
    "suffix": "TV"
  }'

#Phản hồi

Khi tạo thành công, API trả 200 OK hoặc 201 Created với mẫu vừa tạo.

idstringBắt buộc

Định danh mẫu vừa tạo trên trang quản lý.

objectstringBắt buộc

Luôn là invoice_template_registration.

template_idstringBắt buộc

Ghép form và serial vừa tạo, ví dụ 1C26TTV.

formstringBắt buộc

Mẫu số vừa tạo.

serialstringBắt buộc

Ký hiệu vừa ghép. Ví dụ C26TTV khi có mã, năm 2026, hoá đơn điện tử bình thường và suffix TV.

publishedbooleanBắt buộc

false ngay sau khi tạo, cho đến khi mẫu được duyệt.

200 OK
{
  "id": "15899",
  "object": "invoice_template_registration",
  "template_id": "1C26TTV",
  "form": "1",
  "serial": "C26TTV",
  "published": false
}

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

409 conflict—Tuỳ chọn

Cặp form và serial đã tồn tại.

422 validation_error—Tuỳ chọn

Thiếu form, year, cash_register hoặc suffix; form không phải 1 hoặc 2; year không phải năm 4 chữ số; cash_register không phải 0 hoặc 1; suffix không phải đúng 2 chữ cái; hoặc has_tax_authority_code không phải true hoặc false.

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 đóHạn mức hoá đơnTiếp theoDuyệt số lượng hoá đơn
Trang này có hữu ích không?
Cập nhật lần cuối: 06/11/2026

Trên trang này

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