# hddt.dev > REST API hoá đơn điện tử. Tệp này chỉ liệt kê trang tài liệu đã phát hành. Sandbox: https://sandbox.api.hddt.dev Live: https://api.hddt.dev Xác thực: - API ứng dụng: header `api_key`. Webhook và Lấy token: header `api_key` và `app_id`. Key sandbox có tiền tố `hddt_test_`. Webhook tìm ứng dụng theo `app_id`. - Token hoá đơn: gọi `POST /v1/invoices/token` với header `api_key` và `app_id` (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. API hoá đơn sau đó gửi token trong `Authorization: Bearer `, API key trong header `api_key`, cùng `app_id`. - Tra cứu MST: header `api_key` và `app_id`. Không dùng Authorization và không dùng token hoá đơn. - App ID: sao chép trên trang chi tiết ứng dụng (tab Kết nối & bảo mật). Tài khoản nhà cung cấp do đội hỗ trợ gắn với ứng dụng — không gửi username / password khi lấy token. - [OpenAPI 3.1](/openapi.json): Hợp đồng của các endpoint đã có trang tài liệu. - [Toàn bộ markdown](/llms-full.txt): Nội dung các trang đã phát hành, nối lại. ## Bắt đầu - [Bắt đầu nhanh](/docs/quickstart.md): trang mô tả — 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ế. - [Xác thực](/docs/authentication.md): trang mô tả — 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. - [Môi trường sandbox](/docs/sandbox.md): trang mô tả — Sandbox để thử tích hợp. Hoá đơn không gửi cơ quan thuế. Live chỉ gọi được sau khi được duyệt. - [Mã lỗi](/docs/errors.md): trang mô tả — Lỗi của hddt.dev trả mã HTTP và error.code. Lỗi nghiệp vụ khi tạo hoặc ký hoá đơn nằm ở success, error_code và message. ## Ứng dụng - [Thông tin ứng dụng](/docs/apps.md): GET /v1/apps/{app_id} — Đọc hồ sơ ứng dụng đã tạo trong trang quản trị: tên, trạng thái, mã số thuế và hạn mức của môi trường gắn với API key. - [Cập nhật ứng dụng](/docs/apps/update.md): PATCH /v1/apps/{app_id} — Sửa một phần hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị hoặc trạng thái. Trường không gửi giữ nguyên. ## Hoá đơn - [Lấy token](/docs/invoices.md): 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. - [Lấy mẫu hoá đơn](/docs/invoices/templates.md): GET /v1/invoices/templates — Danh sách mẫu số và ký hiệu hoá đơn đã đăng ký theo năm, để chọn template_id khi tạo hoá đơn. - [Danh sách mẫu đã đăng ký](/docs/invoices/templates/registered.md): GET /v1/invoices/templates/registered — Danh sách mẫu số và ký hiệu hoá đơn đã tạo trên trang quản lý, kèm số lượng đã dùng và còn lại của từng mẫu. - [Hạn mức hoá đơn](/docs/invoices/quota.md): GET /v1/invoices/quota — Xem ngân sách hoá đơn của doanh nghiệp trên trang quản lý: tổng số đã có và số còn lại để phát hành. - [Tạo mẫu hoá đơn](/docs/invoices/templates/create.md): POST /v1/invoices/templates — Tạo mẫu số–ký hiệu mới. Gửi ký hiệu mẫu, năm lập, loại hoá đơn thường hoặc máy tính tiền, và hai ký tự cuối do người bán tự đặt. Bỏ trống ô có mã thì hiểu là có mã cơ quan thuế. - [Duyệt số lượng hoá đơn](/docs/invoices/templates/approve-quantity.md): POST /v1/invoices/templates/approve-quantity — Cấp hoặc cập nhật số lượng hoá đơn cho một hoặc nhiều mẫu đã đăng ký trên trang quản lý. - [Xoá mẫu chưa duyệt](/docs/invoices/templates/delete.md): DELETE /v1/invoices/templates/{id} — Xoá một mẫu hoá đơn đã tạo nhưng chưa được duyệt số lượng trên trang quản lý. - [Tạo hoá đơn](/docs/invoices/create.md): POST /v1/invoices — Tạo một hoá đơn nháp hoặc phát hành hoá đơn điện tử. Tên trường là tiếng Anh. Mỗi lần phát hành thành công trừ một hoá đơn khỏi hạn mức của app. - [Danh sách hoá đơn](/docs/invoices/list.md): GET /v1/invoices — Lấy danh sách chi tiết hoá đơn theo bộ lọc. Tên trường là tiếng Anh, cùng key với API Tạo hoá đơn. - [Ký hoá đơn nháp](/docs/invoices/sign.md): POST /v1/invoices/sign — Ký một hoá đơn đã lưu nháp. Gửi invoice_code là UUID lấy từ data.id của API Tạo hoá đơn. - [Xoá hoá đơn nháp](/docs/invoices/cancel.md): DELETE /v1/invoices/{id} — Xoá một hoá đơn đang lưu nháp. Hoá đơn đã phát hành không xoá bằng API này. ## Tra cứu - [Tra cứu mã số thuế](/docs/tax-codes.md): GET /v1/tax-codes/{mst} — Lấy tên đơn vị, địa chỉ và trạng thái hoạt động từ mã số thuế (MST) để tự điền thông tin người mua khi lập hoá đơn. ## Webhook - [Danh sách webhook](/docs/webhooks.md): GET /v1/webhooks — Lấy các webhook của ứng dụng xác định bởi app_id: URL, trạng thái bật và sự kiện đã đăng ký. - [Thêm webhook](/docs/webhooks/create.md): POST /v1/webhooks — Đăng ký URL nhận thông báo theo sự kiện mẫu hoá đơn và hoá đơn. Secret chỉ trả một lần trong phản hồi này. - [Nhận và kiểm tra webhook](/docs/webhooks/verify.md): trang mô tả — Đọc thông báo hddt.dev gửi tới URL của bạn, xem dữ liệu từng sự kiện và kiểm tra chữ ký HMAC-SHA256.