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.
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 đó.
| API | Header |
|---|---|
| Thông tin ứng dụng, Cập nhật ứng dụng | api_key |
| Danh sách webhook, Thêm webhook, Lấy token | api_key và app_id |
| Các API hoá đơn sau Lấy token | Authorization: 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 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 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
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 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.