/v1/invoices/tokenLấ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.
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
Header
api_keystringBắt buộcAPI 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 -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ộcChuỗ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ộcLuôn là Bearer.
expires_inintegerBắt buộcSố 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ộcThời điểm hết hạn, ISO 8601, múi giờ +07:00.
{
"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 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ọnThiế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ọnKhông có ứng dụng nào khớp app_id.