# Lấy token > Chỉ dùng endpoint, field, mã lỗi và ví dụ trong trang này. Không thêm API chưa được mô tả ở đây. `POST /v1/invoices/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:** 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 Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `api_key` | string | có | API key của ứng dụng. | | `app_id` | string | 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: ```bash 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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `token` | string | 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_type` | string | có | Luôn là Bearer. | | `expires_in` | integer | 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_at` | string | có | Thời điểm hết hạn, ISO 8601, múi giờ +07:00. | 200 OK: ```json { "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: ```bash 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: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | 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` | — | không | Ứ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` | — | không | Không có ứng dụng nào khớp app_id. | Trang HTML: /docs/invoices Cập nhật: 16/11/2026