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 token
POST/v1/invoices/token

Lấy token

Gửi App ID trên header để lấy token ngắn hạn dùng cho các API hoá đơn. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng.

MarkdownOpenAPI

#Giới thiệu

Trước khi gọi các API hoá đơn, gửi App ID trên header để lấy một token ngắn hạn. App ID chọn đúng ứng dụng đã tạo trong trang quản trị.

Lấy App ID cạnh tên ứng dụng trên trang chi tiết (tab Kết nối & bảo mật). Không gửi body. Không gửi username hay password nhà cung cấp trong request. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng (đội hỗ trợ cấu hình trên trang quản trị). Gửi API key và App ID trên header. Key sandbox có tiền tố hddt_test_. Token sandbox không gọi được host Live và ngược lại.

Token có thời hạn. Hết hạn hoặc khi API hoá đơn trả 401, gọi lại endpoint này để lấy token mới.

#Endpoint

Gửi POST tới host của môi trường đang dùng. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.

Đặt API key vào header api_key và App ID vào header app_id. Không có body. API key phải thuộc đúng ứng dụng có App ID đó.

Chỉ gọi từ server

API key, App ID và token không được đưa vào trình duyệt, ứng dụng mobile hay log công khai. Giữ chúng phía backend của bạn.

#Header

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. Thay API key và App ID bằng giá trị của ứng dụng bạn.

cURL
curl -X POST https://sandbox.api.hddt.dev/v1/invoices/token \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID"

#Phản hồi

Khi App ID hợp lệ và ứng dụng đã có mã số thuế cùng tài khoản nhà cung cấp, API trả 200 OK. Lưu token phía server và dùng cho đến expires_at.

tokenstringBắt buộc

Chuỗi dùng trong header Authorization của các API hoá đơn. Gửi kèm header api_key và app_id. Không ghi token ra log.

token_typestringBắt buộc

Luôn là Bearer.

expires_inintegerBắt buộc

Số giây token còn hiệu lực, tính từ lúc phản hồi. Mặc định 3600 (1 giờ).

expires_atstringBắt buộc

Thời điểm hết hạn, ISO 8601, múi giờ +07:00.

200 OK
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-10-27T15:09:00+07:00"
}

#Dùng token

Gửi token vừa nhận vào header Authorization của các API trong mục Hoá đơn, ví dụ tạo hoá đơn, danh sách và tải PDF. Đồng thời gửi API key trong header api_key và App ID trong header app_id. Các giá trị phải đang hiệu lực, cùng ứng dụng và cùng môi trường với token.

Khi còn hơn một phút trước expires_at, hoặc khi nhận 401, hãy gọi lại endpoint này với cùng header app_id. Có thể giữ một token cho mỗi cặp môi trường và App ID, rồi dùng chung cho các request song song cho đến khi hết hạn.

cURL
curl https://sandbox.api.hddt.dev/v1/invoices \
  -H "Authorization: Bearer $HDDT_TOKEN" \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID"

#Mã lỗi

Các trường hợp thường gặp khi lấy token:

401 unauthorized—Tuỳ chọn

Thiếu header api_key hoặc app_id; API key sai, đã thu hồi, hoặc không thuộc App ID; hoặc ứng dụng chưa có mã số thuế / tài khoản nhà cung cấp.

403 forbidden—Tuỳ chọn

Ứng dụng đang tạm dừng, hoặc môi trường Live của app chưa được bật.

404 not_found—Tuỳ chọn

Không có ứng dụng nào khớp app_id.

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

Trên trang này

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