# Bắt đầu nhanh > 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. Tạo ứng dụng, lấy token sandbox và phát hành một hoá đơn thử. Hoá đơn sandbox không gửi tới cơ quan thuế. ## Giới thiệu Làm trên Sandbox trước. Host là https://sandbox.api.hddt.dev. API key có tiền tố hddt_test_. Hoá đơn tạo ở đây không được gửi cơ quan thuế. Ba giá trị đi cùng nhau trên mọi API hoá đơn: API key, App ID và token. Token lấy từ API Lấy token, hết hạn sau khoảng 1 giờ. ## Chuẩn bị Đăng nhập, tạo một ứng dụng. Ứng dụng mới mở ở Sandbox và đã có API key sandbox. Mở tab Kết nối & bảo mật, chọn Sandbox, rồi sao chép Base URL, App ID và API key. Lấy token chỉ cần gửi App ID trên header cùng API key. 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ợ gắn tài khoản trên trang quản trị. Chưa có tài khoản thì API Lấy token trả 401. > **Chỉ gọi từ server:** Không đưa API key, App ID hay token vào trình duyệt, ứng dụng mobile hoặc Git. ## Lấy token Gửi POST /v1/invoices/token. Header api_key và app_id phải cùng một ứng dụng. Không có body. Không gửi username hay password. 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" ``` > **Giữ token:** Phản hồi có token, token_type Bearer và expires_at. Dùng đến expires_at. Hết hạn hoặc khi API hoá đơn trả 401 thì gọi lại endpoint này. ## Lấy mẫu Gửi GET /v1/invoices/templates với năm trên query. Header Authorization mang token vừa lấy. Gửi kèm api_key và app_id. Lấy id của một mẫu để điền template_id lúc tạo hoá đơn. Chưa có mẫu trong năm đó thì data là mảng rỗng. Tạo mẫu bằng API Tạo mẫu hoá đơn. cURL: ```bash 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" ``` ## Tạo hoá đơn Gửi POST /v1/invoices. issue_mode bằng 1 là tạo và phát hành. invoice_type bằng 0 là hoá đơn mới. currency gửi VND thì exchange_rate là 1. Đủ trường bắt buộc của dòng hàng nằm ở trang Tạo hoá đơn. Khi thành công, success là true. data.id là UUID của hoá đơn, data.number là số hoá đơn, data.lookup_code là mã tra cứu. cURL: ```bash curl -X POST https://sandbox.api.hddt.dev/v1/invoices \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c1d6c3e-2f4b-4a8e" \ -d '{ "issue_mode": 1, "invoice_type": 0, "template_id": "1C26TAA", "currency": "VND", "exchange_rate": 1, "items": [ { "item_type": 1, "line_number": 1, "name": "Gói phần mềm", "quantity": 1, "unit_price": 5000000, "amount_before_discount": 5000000, "discount_rate": 0, "discount_amount": 0, "amount": 5000000, "vat_rate": 10, "tax_amount": 500000, "line_total": 5500000 } ], "subtotal": 5000000, "trade_discount": 0, "other_deduction": 0, "tax_total": 500000, "total": 5500000 }' ``` > **Sandbox không ra cơ quan thuế:** Hoá đơn sandbox không được gửi cơ quan thuế và trừ vào sổ hạn mức thử. Phát hành thật dùng host https://api.hddt.dev với API key tiền tố hddt_live_ sau khi Live được duyệt. ## Tiếp theo Đọc Xác thực để chọn đúng header cho từng API. Đọc Môi trường sandbox trước khi gọi Live. Danh sách đủ trường nằm ở trang Tạo hoá đơn. Muốn nhận kết quả sau khi phát hành, thêm webhook rồi xem trang Nhận và kiểm tra. Trang HTML: /docs/quickstart Cập nhật: 16/11/2026