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ệuXác thực

Xác thực

Ba cách gửi API key và token. Mỗi API chỉ dùng một cách. Key và host phải cùng môi trường.

Markdown

#Giới thiệu

Mỗi endpoint chỉ nhận một kiểu xác thực. Không gửi Authorization cho API ứng dụng, webhook, Lấy token hay tra cứu mã số thuế. Không dùng token hoá đơn cho những API đó.

APIHeader
Thông tin ứng dụng, Cập nhật ứng dụngapi_key
Danh sách webhook, Thêm webhook, Lấy tokenapi_key và app_id
Các API hoá đơn sau Lấy tokenAuthorization: Bearer <token>, kèm api_key và app_id
Tra cứu mã số thuếapi_key và app_id

#API key

Tạo và sao chép key trên tab Kết nối & bảo mật của ứng dụng. Key sandbox có tiền tố hddt_test_. Key Live có tiền tố hddt_live_. Gửi nguyên chuỗi trong header api_key, không thêm chữ Bearer.

Danh sách webhook, Thêm webhook, Lấy token và Tra cứu mã số thuế còn gửi App ID trong header app_id. App ID là UUID trên cùng tab. Webhook tìm ứng dụng theo app_id, rồi kiểm tra API key thuộc ứng dụng đó. Lấy token chỉ dùng header api_key và app_id, không có body. Tra cứu mã số thuế cũng yêu cầu API key thuộc đúng app_id.

cURL
curl https://sandbox.api.hddt.dev/v1/apps/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "api_key: $HDDT_API_KEY"

#Token hoá đơn

Gọi POST /v1/invoices/token với header api_key và app_id. Endpoint này không nhận Authorization và không có body. 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. Phản hồi có token và expires_at. Mặc định token còn 3600 giây.

Các API hoá đơn phía sau gửi token trong Authorization: Bearer, đồng thời gửi lại api_key và app_id. Ba giá trị phải còn hiệu lực, cùng ứng dụng và cùng môi trường. Token hết hạn hoặc API trả 401 thì lấy token mới.

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"

Idempotency-Key

Khi tạo hoá đơn, có thể gửi thêm Idempotency-Key. Gửi lại cùng key và cùng nội dung để nhận lại kết quả đã tạo. Cùng key nhưng nội dung khác trả 409.

#Tra cứu mã số thuế

GET /v1/tax-codes/{mst} gửi API key trong header api_key và App ID trong header app_id. Không dùng Authorization và không dùng token hoá đơn. Endpoint không trừ hạn mức phát hành.

cURL
curl https://sandbox.api.hddt.dev/v1/tax-codes/0312345678 \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID"

#Key và host

Key và host phải cùng môi trường. Key hddt_test_ chỉ gọi https://sandbox.api.hddt.dev. Key hddt_live_ chỉ gọi https://api.hddt.dev. Gửi chéo trả 403. Token lấy trên sandbox không dùng được trên Live.

Header chọn nhà cung cấp tạm chưa có trên tài liệu. Không gửi header provider.

#Giữ bí mật

Gọi API từ backend. Không nhúng key hay token vào mã chạy trên trình duyệt. Không ghi API key hay token ra log. Key bị lộ thì thu hồi trên tab Kết nối & bảo mật rồi tạo key mới.

Trước đóBắt đầu nhanhTiếp theoMôi trường sandbox
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
  • API key
  • Token hoá đơn
  • Tra cứu mã số thuế
  • Key và host
  • Giữ bí mật
Đăng nhậpBắt đầu ngay