# 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. --- # 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 --- # Xác thực > 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. 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 , 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: ```bash 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: ```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" ``` > **Idempotency-Key:** Khi tạo hoá đơn, có thể gửi thêm Idempotency-Key. Gửi lại cùng key và cùng nội dung để nhận lại kết quả đã tạo. Cùng key nhưng nội dung khác trả 409. ## 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: ```bash 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. Trang HTML: /docs/authentication Cập nhật: 16/11/2026 --- # Môi trường sandbox > 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. 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. ## Giới thiệu Ứng dụng mới luôn ở Sandbox. Dùng Sandbox để lấy token, tạo mẫu, tạo hoá đơn và nhận webhook. Hoá đơn sandbox không được gửi cơ quan thuế. Nút Thử API trên tài liệu chỉ gọi Sandbox. Gọi Live bằng client hoặc cURL với key Live. ## Hai môi trường Chọn host theo key đang giữ. Gửi key sandbox tới host Live, hoặc key Live tới host Sandbox, API trả 403. | Môi trường | Host | Tiền tố API key | | --- | --- | --- | | Sandbox | `https://sandbox.api.hddt.dev` | `hddt_test_` | | Live | `https://api.hddt.dev` | `hddt_live_` | ## Dữ liệu tách riêng Sandbox và Live là hai sổ riêng: API key, hạn mức, hoá đơn và webhook. Key sandbox không đọc được hoá đơn hay webhook Live. Thêm webhook bằng key hddt_test_ và App ID của ứng dụng thì URL đó chỉ nhận sự kiện sandbox. App ID dùng chung cho cả hai môi trường. Token thì không: token lấy trên host nào chỉ gọi lại host đó. ## Hạn mức Ứng dụng mới có 1.000 hoá đơn sandbox. Đây là tổng số được dùng, không làm mới theo tháng. Đây là sổ thử, không phải hoá đơn thật. Khi số còn lại về 0, API phát hành trả 402. Xem số đã dùng và còn lại bằng API Thông tin ứng dụng hoặc API Hạn mức hoá đơn. Live có sổ hạn mức riêng. Hết hạn mức Live thì cần mua thêm. Sandbox không trừ vào sổ Live. ## Dữ liệu mẫu Tra cứu mã số thuế trên sandbox: 0312345678 và 0109876543 luôn trả dữ liệu mẫu. MST khác có thể không có kết quả mẫu. Tài khoản nhà cung cấp để lấy token do đội hỗ trợ gắn với ứng dụng trên trang quản trị. Client không gửi username hay password khi gọi API Lấy token. ## Chuyển sang Live Live chưa được duyệt thì không gọi được host Live. Trên tab Tổng quan, khi ứng dụng còn Sandbox, mục Điều kiện chuyển sang Live gồm đã thử tích hợp trên sandbox và đã khai báo mã số thuế. Đủ điều kiện thì gửi yêu cầu chuyển sang Live. Đội hỗ trợ xác minh rồi bật Live. Sau khi Live được bật, chọn Live trên đầu trang chi tiết để lấy API key hddt_live_ và Base URL https://api.hddt.dev. Vẫn có thể chọn lại Sandbox để thử. Hoá đơn Live được phát hành thật. > **Đừng trộn key:** Đổi sang Live thì đổi cả host, API key và token. Giữ nguyên token sandbox khi gọi api.hddt.dev sẽ bị từ chối. Trang HTML: /docs/sandbox Cập nhật: 16/11/2026 --- # Mã lỗi > 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. 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. ## Giới thiệu Đọc mã HTTP trước. 2xx là request được chấp nhận. 4xx là request của bạn cần sửa. 5xx là lỗi phía hddt.dev hoặc nhà cung cấp, thử lại sau. Trang từng API liệt kê mã riêng của endpoint đó. Bảng dưới đây là các mã dùng chung. ## Thân lỗi Lỗi xác thực, định dạng và giới hạn trả JSON có error.code và error.message. error.param chỉ có khi lỗi trỏ vào một trường. 401: ```json { "error": { "code": "unauthorized", "message": "Thiếu xác thực." } } ``` ## Mã thường gặp Cùng một mã HTTP có thể kèm câu message khác nhau. Dùng error.code để rẽ nhánh, dùng message để hiện cho người tích hợp. | HTTP | Mã | Khi nào | | --- | --- | --- | | `400` | `bad_request` | JSON sai hoặc thiếu tham số bắt buộc. | | `401` | `unauthorized` | Thiếu hoặc sai API key, token hết hạn, token không cùng ứng dụng với key, hoặc ứng dụng chưa cấu hình tài khoản nhà cung cấp khi lấy token. | | `402` | `—` | Hết hạn mức hoá đơn của môi trường đang gọi. | | `403` | `forbidden` | Key không thuộc ứng dụng, key và host khác môi trường, ứng dụng đang tạm dừng, hoặc Live chưa được bật. | | `404` | `not_found` | Không có ứng dụng, mẫu, hoá đơn, hoặc không có endpoint. | | `409` | `conflict` | Cùng Idempotency-Key nhưng nội dung khác, hoặc mã tham chiếu đã tồn tại theo chính sách đang gửi. | | `422` | `validation_error` | Trường có mặt nhưng giá trị không hợp lệ. | | `429` | `rate_limited` | Vượt số request cho phép trong một phút. | | `500` | `internal_error` | Lỗi nội bộ. Thử lại sau. | | `503` | `provider_unavailable` | Tra cứu mã số thuế không thực hiện được lúc này. | ## Giới hạn request Mỗi môi trường có một giới hạn request mỗi phút. Số này hiện trên tab Kết nối & bảo mật, dòng Giới hạn. Phản hồi có header X-RateLimit-Limit và X-RateLimit-Remaining. Khi vượt giới hạn, API trả 429 rate_limited và header Retry-After là số giây còn lại trong phút hiện tại. Chờ hết khoảng đó rồi gửi lại. Không gửi dồn ngay. ## Lỗi nghiệp vụ hoá đơn Tạo hoá đơn, ký hoá đơn và danh sách hoá đơn còn có dạng kết quả nghiệp vụ: success là false, error_code và message mô tả lý do từ quy trình hoá đơn. Đó không phải error.code ở mục Thân lỗi. Lỗi xác thực, hết hạn mức và sai định dạng của hddt.dev vẫn trả mã HTTP trong bảng trên, kể cả khi gọi các API hoá đơn. > **Không thử lại mọi lỗi:** 401 và 422 cần sửa request hoặc lấy token mới. 409 với cùng Idempotency-Key nghĩa là nội dung đã đổi, hãy dùng key mới. 429 chờ Retry-After. 5xx có thể gửi lại. Trang HTML: /docs/errors Cập nhật: 16/11/2026 --- # Thông tin ứng dụng > 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. `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. ## Giới thiệu API này trả thông tin một ứng dụng bạn đã tạo trong trang quản trị. Dùng khi cần đối chiếu App ID, tên đơn vị, trạng thái hoạt động hoặc số hoá đơn còn lại trước khi phát hành. Xác thực bằng API key trong header api_key. Key quyết định môi trường được trả về: key hddt_test_ đọc sandbox, key Live đọc production. Endpoint không dùng token hoá đơn và không trừ hạn mức phát hành. ## Endpoint Gửi GET với App ID trên đường dẫn. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. API key phải thuộc đúng ứng dụng có app_id đó. Phản hồi không chứa API key, bí mật webhook hay danh sách IP cho phép. > **Một key, một môi trường:** Mỗi API key chỉ đọc được sổ hạn mức của môi trường nó thuộc về. Muốn xem cả sandbox và Live thì gọi hai lần, mỗi lần một key. ## 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. | ## Param Nằm trên đường dẫn. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `app_id` | string | có | Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479. | ## Ví dụ Request mẫu trên sandbox. Thay App ID và API key bằng giá trị của ứng dụng bạn. cURL: ```bash curl https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "api_key: $HDDT_API_KEY" ``` ## Phản hồi Khi key hợp lệ và khớp ứng dụng, API trả 200 OK. Trường environment là sandbox hoặc live, đúng với key vừa dùng. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | App ID, trùng giá trị trên đường dẫn. | | `object` | string | có | Luôn là app. | | `name` | string | có | Tên ứng dụng trong trang quản trị. | | `description` | string | có | Mô tả ngắn. Chuỗi rỗng nếu chưa nhập. | | `status` | string | có | active khi ứng dụng đang chạy, paused khi đang tạm dừng. | | `tax_code` | string | không | Mã số thuế đơn vị phát hành. null nếu chưa khai báo. | | `company_name` | string | không | Tên đơn vị phát hành. null nếu chưa khai báo. | | `environment` | string | có | sandbox hoặc live, theo API key của request. | | `base_url` | string | có | Host gốc của môi trường đó, gồm tiền tố /v1. | | `rate_limit` | integer | có | Số request tối đa mỗi phút của môi trường này. | | `created_at` | string | có | Thời điểm tạo ứng dụng, ISO 8601, múi giờ +07:00. | 200 OK: ```json { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "object": "app", "name": "Shop ABC", "description": "Website bán hàng, xuất hoá đơn tự động khi đơn hàng hoàn tất.", "status": "active", "tax_code": "0312345678", "company_name": "Công ty TNHH Thương mại ABC", "environment": "sandbox", "base_url": "https://sandbox.api.hddt.dev/v1", "rate_limit": 30, "quota": { "invoices_used": 342, "invoices_remaining": 658 }, "created_at": "2026-03-12T09:00:00+07:00" } ``` ### Hạn mức Object quota theo môi trường của API key. Đây là tổng số hoá đơn được dùng, không làm mới theo tháng. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `invoices_used` | integer | có | Tổng số hoá đơn đã phát hành trong môi trường này. | | `invoices_remaining` | integer | có | Tổng số hoá đơn còn lại của môi trường. Không làm mới theo tháng. Khi về 0, API phát hành trả 402. | ## Mã lỗi Các trường hợp thường gặp khi đọc thông tin ứng dụng: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu header api_key, API key sai hoặc đã bị thu hồi. | | `403 forbidden` | — | không | API key không thuộc app_id này, hoặc gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live). | | `404 not_found` | — | không | Không có ứng dụng nào khớp app_id. | | `422 validation_error` | — | không | app_id không phải UUID. | Trang HTML: /docs/apps Cập nhật: 27/10/2026 --- # Cập nhật ứng dụng > 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. `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. ## Giới thiệu API này sửa hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị và trạng thái chạy hoặc tạm dừng. Hạn mức, API key, webhook và danh sách IP không đổi qua endpoint này. Sandbox và Live là hai hệ thống tách biệt. Gọi trên Live sẽ sửa hồ sơ chính thức, và console hiển thị đúng hồ sơ này. Gọi trên Sandbox chỉ sửa bản dùng để thử. Lần tới khi bạn sửa ứng dụng trên console, bản Sandbox sẽ bị ghi đè theo hồ sơ chính thức. Chỉ gửi những trường cần sửa. Trường bỏ qua giữ giá trị hiện tại. Xác thực bằng API key của ứng dụng đó, không dùng token hoá đơn và không trừ hạn mức phát hành. ## Endpoint Gửi PATCH tới cùng đường dẫn với API đọc thông tin ứng dụng. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Body là JSON. Cần ít nhất một trường. API key phải thuộc đúng app_id trên đường dẫn. > **Tạm dừng:** status = paused ngắt phát hành hoá đơn ngay, không xoá ứng dụng. Gửi status = active để mở lại. ## 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. | | `Content-Type` | string | có | application/json. | ## Param Nằm trên đường dẫn. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `app_id` | string | có | Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479. | ## Body Mọi trường đều tuỳ chọn. Gửi ít nhất một trường. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `name` | string | không | Tên ứng dụng sau khi bỏ khoảng trắng hai đầu. Từ 3 đến 50 ký tự. | | `description` | string | không | Mô tả ngắn, tối đa 160 ký tự. Chuỗi rỗng để xoá mô tả. | | `tax_code` | string | không | Mã số thuế 10 số, hoặc chi nhánh dạng 0302712571-999. 13 số liền cũng được chấp nhận và được lưu thành dạng có dấu gạch. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống. | | `company_name` | string | không | Tên đơn vị phát hành. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống. | | `status` | string | không | active hoặc paused. | ## Ví dụ Đổi tên đơn vị và mã số thuế, giữ nguyên các trường khác. cURL: ```bash curl -X PATCH https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "api_key: $HDDT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tax_code": "0312345678", "company_name": "Công ty TNHH Thương mại ABC" }' ``` ## Phản hồi Khi hợp lệ, API trả 200 OK với cùng dạng object app như API thông tin ứng dụng. Các trường vừa gửi đã được ghi; hạn mức vẫn là sổ của môi trường gắn với API key. 200 OK: ```json { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "object": "app", "name": "Shop ABC", "description": "Website bán hàng, xuất hoá đơn tự động khi đơn hàng hoàn tất.", "status": "active", "tax_code": "0312345678", "company_name": "Công ty TNHH Thương mại ABC", "environment": "sandbox", "base_url": "https://sandbox.api.hddt.dev/v1", "rate_limit": 30, "quota": { "invoices_used": 342, "invoices_remaining": 658 }, "created_at": "2026-03-12T09:00:00+07:00" } ``` ## Mã lỗi Các trường hợp thường gặp khi cập nhật ứng dụng: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu header api_key, API key sai hoặc đã bị thu hồi. | | `403 forbidden` | — | không | API key không thuộc app_id này, hoặc gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live). | | `404 not_found` | — | không | Không có ứng dụng nào khớp app_id. | | `422 validation_error` | — | không | Body rỗng, app_id không phải UUID, tên ngoài 3–50 ký tự, mô tả dài hơn 160 ký tự, mã số thuế sai định dạng, status lạ, hoặc xoá mã số thuế / tên đơn vị khi Live đã bật. | Trang HTML: /docs/apps/update Cập nhật: 30/10/2026 --- # 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 --- # Lấy mẫu hoá đơn > 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. `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. ## Giới thiệu API trả các mẫu hoá đơn doanh nghiệp đã đăng ký và còn dùng trong một năm. Khi tạo hoá đơn, gửi id của mẫu vào template_id. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Endpoint không trừ hạn mức phát hành. Muốn xem sổ mẫu kèm số lượng đã dùng, tạo / duyệt / xoá mẫu trên trang quản lý, dùng các API trong nhóm mẫu hoá đơn ngay sau mục này. Các API đó giữ cùng cách gọi (token + api_key + app_id); hệ thống tự dùng tài khoản trang quản lý đã gắn với ứng dụng, không gửi username hay password trang quản lý trong request. ## Endpoint Gửi GET kèm năm trên query string. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Không có mẫu nào trong năm đó vẫn trả 200 với data là mảng rỗng. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | ## Param Nằm trên query string. Vị trí: query. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `year` | integer | có | Năm dương lịch của mẫu đã đăng ký, 4 chữ số. Ví dụ 2026. | ## Ví dụ Request mẫu trên sandbox. Token lấy từ mục Lấy token. 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" ``` ## Phản hồi Khi token còn hiệu lực, API trả 200 OK. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Giá trị gửi vào template_id khi tạo hoá đơn. Ghép ký hiệu mẫu số và ký hiệu hoá đơn, ví dụ 1C26TAA. | | `object` | string | có | Luôn là invoice_template. | | `form` | string | có | Ký hiệu mẫu số hoá đơn, ví dụ 1. | | `serial` | string | có | Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TAA. Xem mục Ký hiệu. | | `year` | integer | có | Năm của mẫu, trùng năm đã gửi trên query. | | `has_tax_authority_code` | boolean | có | true khi ký tự đầu của serial là C (có mã cơ quan thuế).
false khi là K (không mã). | | `invoice_type` | string | có | Ký tự loại hoá đơn, ký tự thứ tư của serial. Một trong T, D, L, M, N, B, G, H. | 200 OK: ```json { "object": "list", "data": [ { "id": "1C26TAA", "object": "invoice_template", "form": "1", "serial": "C26TAA", "year": 2026, "has_tax_authority_code": true, "invoice_type": "T" } ] } ``` ### Ký hiệu serial gồm 6 ký tự. Ký tự đầu là C (có mã cơ quan thuế) hoặc K (không mã). Hai số tiếp theo là hai số cuối của năm lập. Ký tự thứ tư là loại hoá đơn. Hai ký tự cuối do người bán tự đặt để phân biệt các mẫu cùng loại; nếu không cần phân biệt thì thường là YY. | Ký tự | Loại hoá đơn | | --- | --- | | `T` | Hoá đơn doanh nghiệp đăng ký với cơ quan thuế. | | `D` | Bán tài sản công, hàng dự trữ quốc gia hoặc hoá đơn đặc thù. | | `L` | Hoá đơn cấp theo từng lần phát sinh. | | `M` | Hoá đơn khởi tạo từ máy tính tiền. | | `N` | Phiếu xuất kho kiêm vận chuyển nội bộ. | | `B` | Phiếu xuất kho hàng gửi bán đại lý. | | `G` | Tem, vé, thẻ dạng hoá đơn giá trị gia tăng. | | `H` | Tem, vé, thẻ dạng hoá đơn bán hàng. | ## Mã lỗi Các trường hợp thường gặp khi lấy mẫu: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `422 validation_error` | — | không | Thiếu year hoặc year không phải năm dương lịch 4 chữ số. | Trang HTML: /docs/invoices/templates Cập nhật: 09/11/2026 --- # Danh sách mẫu đã đăng ký > 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. `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. ## Giới thiệu API trả các mẫu hoá đơn doanh nghiệp đã tạo trên trang quản lý, gồm mẫu số, ký hiệu, số lượng đã cấp, đã dùng và còn lại. Dùng để đối chiếu hạn mức từng mẫu hoặc lấy id mẫu chưa duyệt trước khi xoá / duyệt số lượng. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn. Khác với API Lấy mẫu hoá đơn theo năm: endpoint đó dùng khi chọn template_id lúc tạo hoá đơn; endpoint này đọc sổ mẫu đã đăng ký kèm số lượng. ## Endpoint Gửi GET không có query. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Chưa có mẫu nào vẫn trả 200 với data là mảng rỗng. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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. Token lấy từ mục Lấy token. cURL: ```bash curl https://sandbox.api.hddt.dev/v1/invoices/templates/registered \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi token còn hiệu lực, API trả 200 OK. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh mẫu đã đăng ký trên trang quản lý. Dùng khi duyệt số lượng hoặc xoá mẫu chưa duyệt. | | `object` | string | có | Luôn là invoice_template_registration. | | `template_id` | string | có | Ghép mẫu số và ký hiệu, ví dụ 1C26TTV. Có thể dùng tương ứng template_id khi tạo hoá đơn. | | `form` | string | có | Ký hiệu mẫu số hoá đơn, ví dụ 1. | | `serial` | string | có | Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TTV. | | `year` | integer | có | Năm suy từ hai số trong serial. | | `quantity` | integer | có | Số lượng hoá đơn đã cấp cho mẫu. | | `used` | integer | có | Số lượng đã dùng. | | `remaining` | integer | có | Số lượng còn lại. | | `invoice_category_name` | string | không | Tên loại hoá đơn, ví dụ Hóa đơn giá trị gia tăng. | | `published` | boolean | có | true khi mẫu đã được duyệt.
false khi mẫu còn chưa duyệt. | 200 OK: ```json { "object": "list", "data": [ { "id": "13362", "object": "invoice_template_registration", "template_id": "1C26TDV", "form": "1", "serial": "C26TDV", "year": 2026, "quantity": 10, "used": 0, "remaining": 10, "invoice_category_name": "Hóa đơn giá trị gia tăng", "published": true } ] } ``` ## Mã lỗi Các trường hợp thường gặp: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `502 bad_gateway` | — | không | Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó. | Trang HTML: /docs/invoices/templates/registered Cập nhật: 04/11/2026 --- # Hạn mức hoá đơn > 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. `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. ## Giới thiệu API trả ngân sách hoá đơn của doanh nghiệp trên trang quản lý: total là tổng số hoá đơn trong hạn mức, remaining là số còn lại có thể dùng để phát hành. Dùng khi cần biết còn bao nhiêu hoá đơn trước khi tạo hoá đơn hoặc duyệt thêm số lượng cho mẫu. Đây là hạn mức tổng của tài khoản, không phải số lượng gắn từng mẫu số–ký hiệu. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn. ## Endpoint Gửi GET không có query. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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. cURL: ```bash curl https://sandbox.api.hddt.dev/v1/invoices/quota \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi token còn hiệu lực, API trả 200 OK. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `object` | string | có | Luôn là invoice_quota. | | `total` | integer | có | Tổng số hoá đơn trong ngân sách / hạn mức của tài khoản. | | `remaining` | integer | có | Số hoá đơn còn lại có thể dùng để phát hành. | 200 OK: ```json { "object": "invoice_quota", "total": 1000, "remaining": 850 } ``` ## Mã lỗi Các trường hợp thường gặp: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `502 bad_gateway` | — | không | Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó. | Trang HTML: /docs/invoices/quota Cập nhật: 04/11/2026 --- # Tạo mẫu hoá đơn > 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/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ế. ## Giới thiệu API tạo một mẫu hoá đơn mới trên trang quản lý. Gửi ký hiệu mẫu, năm lập, chọn hoá đơn điện tử bình thường hoặc hoá đơn máy tính tiền, và hai ký tự cuối để phân biệt mẫu. Có mã cơ quan thuế hay không là tuỳ chọn; bỏ trống thì là có mã. Hệ thống ghép ký hiệu và tự chọn thiết kế mẫu. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn. Sau khi tạo, mẫu thường chưa duyệt. Dùng Duyệt số lượng hoá đơn để cấp số lượng, hoặc Xoá mẫu chưa duyệt nếu tạo nhầm. ## Endpoint Gửi POST với body JSON. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Path trùng với GET Lấy mẫu hoá đơn theo năm; method POST dùng để tạo mẫu mới. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | | `Content-Type` | string | có | application/json. | ## Body Gửi form, year, cash_register và suffix. has_tax_authority_code bỏ trống thì hoá đơn có mã cơ quan thuế. API ghép serial 6 ký tự: ký tự 1 là C hoặc K, ký tự 2–3 là hai số cuối của year, ký tự 4 là T hoặc M, ký tự 5–6 là suffix. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `form` | string | có | Ký hiệu mẫu số.
1: Hoá đơn giá trị gia tăng.
2: Hoá đơn bán hàng. | | `has_tax_authority_code` | boolean | không | Hoá đơn có mã của cơ quan thuế hay không. Bỏ trống thì là có mã.
true khi có mã. Ký tự 1 của serial là C.
false khi không có mã. Ký tự 1 của serial là K. | | `year` | integer | có | Năm lập hoá đơn, 4 chữ số. Hai số cuối thành ký tự 2–3 của serial. Năm 2026 ghi thành 26. | | `cash_register` | string | có | Cách lập hoá đơn.
0: Hoá đơn điện tử bình thường. Ký tự 4 của serial là T.
1: Hoá đơn máy tính tiền. Ký tự 4 của serial là M. | | `suffix` | string | có | Hai ký tự cuối của serial, do người bán tự đặt để phân biệt các mẫu cùng loại. Đúng 2 chữ cái, ví dụ TV. | ## Ví dụ Request mẫu trên sandbox: hoá đơn GTGT, có mã (bỏ trống has_tax_authority_code), năm 2026, hoá đơn điện tử bình thường, hai ký tự cuối TV. Serial được ghép là C26TTV. cURL: ```bash curl -X POST https://sandbox.api.hddt.dev/v1/invoices/templates \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" \ -H "Content-Type: application/json" \ -d '{ "form": "1", "year": 2026, "cash_register": "0", "suffix": "TV" }' ``` ## Phản hồi Khi tạo thành công, API trả 200 OK hoặc 201 Created với mẫu vừa tạo. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh mẫu vừa tạo trên trang quản lý. | | `object` | string | có | Luôn là invoice_template_registration. | | `template_id` | string | có | Ghép form và serial vừa tạo, ví dụ 1C26TTV. | | `form` | string | có | Mẫu số vừa tạo. | | `serial` | string | có | Ký hiệu vừa ghép. Ví dụ C26TTV khi có mã, năm 2026, hoá đơn điện tử bình thường và suffix TV. | | `published` | boolean | có | false ngay sau khi tạo, cho đến khi mẫu được duyệt. | 200 OK: ```json { "id": "15899", "object": "invoice_template_registration", "template_id": "1C26TTV", "form": "1", "serial": "C26TTV", "published": false } ``` ## Mã lỗi Các trường hợp thường gặp: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `409 conflict` | — | không | Cặp form và serial đã tồn tại. | | `422 validation_error` | — | không | Thiếu form, year, cash_register hoặc suffix; form không phải 1 hoặc 2; year không phải năm 4 chữ số; cash_register không phải 0 hoặc 1; suffix không phải đúng 2 chữ cái; hoặc has_tax_authority_code không phải true hoặc false. | | `502 bad_gateway` | — | không | Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó. | Trang HTML: /docs/invoices/templates/create Cập nhật: 06/11/2026 --- # Duyệt số lượng hoá đơn > 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/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ý. ## Giới thiệu API duyệt số lượng cho từng mẫu đã đăng ký. Mỗi dòng chỉ cần id mẫu, số lượng muốn cấp và số lượng trước đó. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn. ## Endpoint Gửi POST với body JSON. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | | `Content-Type` | string | có | application/json. | ## Body Object JSON có mảng items. Mỗi phần tử chỉ gồm id, quantity và quantity_previous. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `items` | array | có | Danh sách mẫu cần duyệt số lượng. Không được để mảng rỗng. | | `items[].id` | integer | có | Id mẫu đã đăng ký (trường id trên Danh sách mẫu đã đăng ký). | | `items[].quantity` | integer | có | Số lượng muốn cấp sau khi duyệt. | | `items[].quantity_previous` | integer | có | Số lượng trước khi duyệt, lấy từ quantity hiện tại của mẫu. | ## Ví dụ Duyệt 10 hoá đơn cho mẫu id 13362 trên sandbox. cURL: ```bash curl -X POST https://sandbox.api.hddt.dev/v1/invoices/templates/approve-quantity \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "id": 13362, "quantity": 10, "quantity_previous": 10 } ] }' ``` ## Phản hồi Khi duyệt thành công, API trả 200 OK. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `object` | string | có | Luôn là invoice_template_approve_quantity. | | `approved` | integer | có | Số dòng mẫu đã duyệt trong request. | 200 OK: ```json { "object": "invoice_template_approve_quantity", "approved": 1 } ``` ## Mã lỗi Các trường hợp thường gặp: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `422 validation_error` | — | không | Thiếu items, mảng rỗng, hoặc một dòng thiếu id, quantity hoặc quantity_previous. | | `502 bad_gateway` | — | không | Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó. | Trang HTML: /docs/invoices/templates/approve-quantity Cập nhật: 06/11/2026 --- # Xoá mẫu chưa duyệt > 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. `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ý. ## Giới thiệu API xoá mẫu đã tạo khi mẫu chưa được duyệt số lượng. Mẫu đã có số lượng sẽ bị từ chối. Gọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Không gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn. ## Endpoint Gửi DELETE với id mẫu trên đường dẫn. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. > **Chỉ mẫu chưa duyệt số lượng:** Lấy id từ Danh sách mẫu đã đăng ký. Mẫu đã được cấp số lượng không xoá được. Thao tác không hoàn tác được. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | ## Param Nằm trên đường dẫn. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh mẫu đã đăng ký. Ví dụ 15899. | ## Ví dụ Request mẫu trên sandbox. cURL: ```bash curl -X DELETE https://sandbox.api.hddt.dev/v1/invoices/templates/15899 \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi xoá thành công, API trả 200 OK. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Id mẫu vừa xoá. | | `object` | string | có | Luôn là invoice_template_registration. | | `deleted` | boolean | có | Luôn là true. | 200 OK: ```json { "id": "15899", "object": "invoice_template_registration", "deleted": true } ``` ## Mã lỗi Các trường hợp thường gặp: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `404 not_found` | — | không | Không có mẫu khớp id. | | `409 conflict` | — | không | Mẫu đã được duyệt số lượng. Chỉ xoá được mẫu có số lượng còn trống. | | `502 bad_gateway` | — | không | Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó. | Trang HTML: /docs/invoices/templates/delete Cập nhật: 06/11/2026 --- # Tạo hoá đơn > 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` 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. ## Giới thiệu API tạo một hoá đơn. issue_mode bằng 0 thì lưu nháp, bằng 1 thì tạo và phát hành. Trường này không bắt buộc. Hoá đơn có mã hay không mã của cơ quan thuế phụ thuộc mẫu đã chọn. Gửi template_id lấy từ API Lấy mẫu hoá đơn. Khi thay thế hoặc điều chỉnh, gửi related_invoice_id bằng id (UUID) của hoá đơn gốc. Thay thế hoặc điều chỉnh chỉ tạo được khi ứng dụng đang dùng đúng nhà cung cấp đã phát hành hoá đơn gốc. reference luôn duy nhất trong ứng dụng. Bỏ trống reference_duplicate_policy, hoặc gửi 0 hoặc 1, thì trùng mã tham chiếu sẽ bị từ chối. lookup_code không có ràng buộc unique trong database; bỏ trống lookup_code_duplicate_policy thì không kiểm tra trùng mã tra cứu. Chưa hỗ trợ vé xe, hàng hoá đặc trưng và các trường mở rộng. Trên sandbox, hoá đơn không được gửi tới cơ quan thuế. Thử trên host sandbox.api.hddt.dev với token, API key tiền tố hddt_test_ và App ID. Phát hành thật trên api.hddt.dev với token và API key Live. ## Endpoint Gửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. > **Hạn mức:** Khi số hoá đơn còn lại của môi trường đang dùng về 0, API trả 402. Hạn mức là tổng số hoá đơn được dùng, không làm mới theo tháng. Hết thì cần nạp thêm. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | | `Content-Type` | string | có | application/json. | | `Idempotency-Key` | string | không | Chuỗi duy nhất cho mỗi lần tạo, ví dụ UUID. Gửi lại cùng key và cùng nội dung để nhận lại kết quả đã tạo. Cùng key nhưng nội dung khác trả 409. | ## Body Trường đánh dấu Bắt buộc phải có. Các trường còn lại chỉ gửi khi có dữ liệu. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `issue_mode` | integer | không | Cách tạo.
0: lưu nháp.
1: tạo và phát hành.
Tối đa 10 chữ số. | | `invoice_type` | integer | có | Tính chất hoá đơn.
0: hoá đơn mới.
1: thay thế.
2: điều chỉnh tăng.
3: điều chỉnh giảm.
4: điều chỉnh thông tin.
5: điều chỉnh tăng và giảm.
Tối đa 5 chữ số. | | `template_id` | string | không | Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA. | | `issued_at` | string (date-time) | không | Ngày lập hoá đơn. | | `currency` | string | có | Mã tiền tệ ISO 4217.
VND: Việt Nam đồng.
USD: đô la Mỹ.
CAD: đô la Canada.
Hệ thống tự map sang mã của từng nhà cung cấp khi gọi nền tảng. | | `exchange_rate` | number | có | Tỷ giá. Với VND gửi 1. Tối đa 7 chữ số, 2 chữ số thập phân. | | `payment_method` | string | không | Hình thức thanh toán. | | `lookup_code` | string | không | Mã tra cứu. Tối đa 100 ký tự. | | `lookup_code_duplicate_policy` | integer | không | Cách xử lý khi lookup_code trùng.
0: trùng thì không tạo.
1: trùng thì xoá hoá đơn chưa phát hành, hoá đơn đã phát hành thì không tạo.
Bỏ trống thì không kiểm tra. | | `reference` | string | không | Mã tham chiếu của hoá đơn trên hệ thống của bạn. Duy nhất trong ứng dụng. Tối đa 20 ký tự. | | `reference_duplicate_policy` | integer | không | Cách xử lý khi reference trùng.
0: giữ để tương thích, trùng thì từ chối.
1: trùng thì từ chối.
2: trùng thì xoá hoá đơn chưa phát hành; hoá đơn đã phát hành thì từ chối.
Bỏ trống: trùng thì từ chối. | | `note` | string | không | Ghi chú. Tối đa 255 ký tự. | | `related_invoice_id` | string | không | UUID của hoá đơn gốc, lấy từ id của hoá đơn đó. Dùng khi invoice_type là thay thế hoặc điều chỉnh. | | `subtotal` | number | có | Tổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân. | | `trade_discount` | number | có | Tổng tiền chiết khấu thương mại. Gửi 0 nếu không chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `other_deduction` | number | có | Tổng giảm trừ khác. Gửi 0 nếu không giảm trừ. Tối đa 21 chữ số, 6 chữ số thập phân. | | `tax_total` | number | có | Tổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân. | | `total` | number | có | Tổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân. | | `total_in_words` | string | không | Tổng tiền thanh toán bằng chữ. Tối đa 255 ký tự. | | `buyer` | object | không | Người mua. Xem mục Người mua. | | `items` | array | có | Danh sách hàng hoá, dịch vụ. Xem mục Dòng hàng. | | `fees` | array | không | Danh sách phí, lệ phí. Xem mục Loại phí. | ### Người bán Tên, mã số thuế và địa chỉ người bán lấy từ tài khoản đã đăng nhập, không gửi trong request. Đơn vị có nhiều điểm bán gửi mã cửa hàng và tên cửa hàng để phân biệt nơi xuất hoá đơn. Cả hai trường đều tuỳ chọn. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `seller_store_code` | string | không | Mã cửa hàng, điểm bán. Tối đa 50 ký tự. | | `seller_store_name` | string | không | Tên cửa hàng, điểm bán. Tối đa 400 ký tự. | ### Người mua Các trường trong buyer đều tuỳ chọn. Có thể lấy name, tax_code và address từ API tra cứu mã số thuế. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `name` | string | không | Tên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự. | | `tax_code` | string | không | Mã số thuế người mua. Tối đa 14 ký tự. | | `address` | string | không | Địa chỉ. Tối đa 400 ký tự. | | `code` | string | không | Mã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự. | | `phone` | string | không | Số điện thoại. Tối đa 20 ký tự. | | `email` | string | không | Email. Tối đa 50 ký tự. | | `contact_name` | string | không | Họ và tên người mua hàng. Tối đa 100 ký tự. | | `bank_account` | string | không | Số tài khoản ngân hàng. | | `bank_name` | string | không | Tên ngân hàng. | | `citizen_id` | string | không | Số định danh cá nhân (CCCD). Tối đa 12 ký tự. | | `budget_unit_code` | string | không | Mã đơn vị quan hệ ngân sách. Tối đa 7 ký tự. | | `passport` | string | không | Số hộ chiếu hoặc giấy tờ nhập xuất cảnh. Tối đa 20 ký tự. | ### Dòng hàng Mỗi phần tử của items là một dòng hàng hoá hoặc dịch vụ. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `item_type` | integer | có | Tính chất dòng.
1: hàng hoá, dịch vụ.
2: khuyến mãi.
3: chiết khấu.
4: ghi chú. | | `line_number` | integer | có | Số thứ tự dòng. Tối đa 4 chữ số. | | `code` | string | không | Mã hàng hoá, dịch vụ. Tối đa 50 ký tự. | | `name` | string | có | Tên hàng hoá, dịch vụ. Tối đa 500 ký tự. | | `unit` | string | không | Đơn vị tính. Tối đa 50 ký tự. | | `quantity` | number | có | Số lượng. Tối đa 21 chữ số, 6 chữ số thập phân. | | `unit_price` | number | có | Đơn giá. Tối đa 21 chữ số, 6 chữ số thập phân. | | `amount_before_discount` | number | có | Thành tiền trước thuế, trước chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `discount_rate` | number | có | Tỷ lệ chiết khấu, đơn vị phần trăm. Gửi 0 nếu không chiết khấu. Tối đa 6 chữ số, 4 chữ số thập phân. | | `discount_amount` | number | có | Số tiền chiết khấu. Gửi 0 nếu không chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `amount` | number | có | Thành tiền trước thuế, sau chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `vat_rate` | number | có | Thuế suất.
-2: không kê khai, không nộp thuế.
-1: không chịu thuế.
0: 0%.
5: 5%.
8: 8%.
10: 10%.
3.5: thuế suất khác. | | `tax_amount` | number | có | Tiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân. | | `line_total` | number | có | Tiền sau thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân. | ### Loại phí Mỗi phần tử của fees là một loại phí. Cả danh sách và từng trường đều tuỳ chọn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `name` | string | không | Tên loại phí. Tối đa 100 ký tự. | | `amount` | number | không | Tiền phí. Tối đa 21 chữ số, 6 chữ số thập phân. | ## Ví dụ Tạo một hoá đơn GTGT mới, tiền Việt Nam, một dòng hàng thuế suất 10%. Thành tiền trước thuế 5.000.000, tiền thuế 500.000, tổng thanh toán 5.500.000. lookup_code_duplicate_policy bằng 0 và reference_duplicate_policy bằng 1 để từ chối khi mã tra cứu hoặc mã tham chiếu đã tồn tại. cURL: ```bash curl -X POST https://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 '{ "invoice_type": 0, "template_id": "1C26TAA", "lookup_code": "7B164DE808", "lookup_code_duplicate_policy": 0, "reference": "DH-1001", "reference_duplicate_policy": 1, "seller_store_code": "CH01", "seller_store_name": "Cửa hàng Quận 1", "currency": "VND", "exchange_rate": 1, "buyer": { "name": "Công ty TNHH ABC", "tax_code": "0312345678", "address": "123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh", "email": "ketoan@abc.vn" }, "items": [ { "item_type": 1, "line_number": 1, "name": "Gói phần mềm", "unit": "Gói", "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, "total_in_words": "Năm triệu năm trăm nghìn đồng" }' ``` > **Sandbox:** Đổi host thành https://sandbox.api.hddt.dev và dùng token cùng API key tiền tố hddt_test_ khi thử. Hoá đơn sandbox không được gửi cơ quan thuế. ## Phản hồi Khi tạo được hoá đơn, success là true. data.id là UUID của hoá đơn, dùng lại cho chi tiết hoá đơn và cho related_invoice_id khi thay thế hoặc điều chỉnh. data.number là số hoá đơn. data.lookup_code là mã tra cứu. Khi có mã số thuế người mua, data.pdf_url mở bản thể hiện, kể cả hoá đơn nháp. data.xml_url chỉ có khi phát hành và tải file XML. Hai link dùng cùng token. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `success` | boolean | có | true khi tạo được hoá đơn, false khi thất bại. | | `data` | object | có | Kết quả tạo hoá đơn. Khi thành công có id (UUID), number và lookup_code. Khi có mã số thuế người mua thì thêm pdf_url. xml_url chỉ có khi phát hành. | | `error_code` | string | có | Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ. | | `message` | string | có | Thông báo thành công hoặc thất bại. | | `id` | string | không | UUID của hoá đơn nằm trong data. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh. | | `number` | integer | không | Số hoá đơn nằm trong data khi tạo thành công. Tối đa 8 chữ số. | | `lookup_code` | string | không | Mã tra cứu nằm trong data khi tạo thành công. Tối đa 100 ký tự. | | `pdf_url` | string | không | Có khi tạo thành công, kể cả nháp, và hoá đơn có mã số thuế người mua. Mở bản thể hiện: https://hddt.dev/tra-cuu/hoa-don?token=...&type=pdf. | | `xml_url` | string | không | Chỉ có khi phát hành, không có ở hoá đơn nháp. Cùng token với pdf_url. Tải file XML: https://hddt.dev/tra-cuu/hoa-don?token=...&type=xml. | Phản hồi: ```json { "success": true, "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "number": 125, "lookup_code": "ABC123", "pdf_url": "https://hddt.dev/tra-cuu/hoa-don?token=1.example&type=pdf", "xml_url": "https://hddt.dev/tra-cuu/hoa-don?token=1.example&type=xml" }, "error_code": "", "message": "Thành công" } ``` ## Mã lỗi Khi hoá đơn không được tạo, success là false, error_code và message mô tả lỗi nghiệp vụ. Lỗi xác thực, hạn mức và định dạng của hddt.dev vẫn trả mã HTTP kèm error.code và error.message. Ngoài các mã dưới đây, xem thêm trang Mã lỗi. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `400 bad_request` | — | không | Request sai định dạng hoặc thiếu tham số bắt buộc. | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. | | `402` | — | không | Hết hạn mức hoá đơn của môi trường đang gọi. | | `404 not_found` | — | không | Không tìm thấy template_id hoặc related_invoice_id. | | `409 conflict` | — | không | Trùng Idempotency-Key với request khác nội dung, mã tra cứu đã tồn tại theo chính sách, hoặc reference đã tồn tại trong ứng dụng. | | `422 validation_error` | — | không | Dữ liệu không hợp lệ: thiếu trường bắt buộc, thuế suất vat_rate ngoài danh mục, hoặc related_invoice_id thuộc nhà cung cấp khác với nhà cung cấp đang dùng. | | `429 rate_limited` | — | không | Vượt giới hạn số request cho phép. | Trang HTML: /docs/invoices/create Cập nhật: 10/11/2026 --- # Danh sách hoá đơn > 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. `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. ## Giới thiệu API trả danh sách chi tiết hoá đơn đã tạo trong ứng dụng. Mỗi phần tử trong data dùng cùng tên trường với body của API Tạo hoá đơn, kèm invoice_code (UUID, cùng data.id lúc tạo), number, lookup_code và status. Bắt buộc gửi template_id. Các bộ lọc còn lại tuỳ chọn. Khi gửi cả issued_from và issued_to, khoảng tìm kiếm tối đa 10 ngày, tính cả hai đầu mút. Endpoint không trừ hạn mức phát hành. Thử trên host sandbox.api.hddt.dev với token, API key tiền tố hddt_test_ và App ID. Dữ liệu Live trên api.hddt.dev với token và API key Live. ## Endpoint Gửi GET với bộ lọc trên query string. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Không có hoá đơn khớp bộ lọc vẫn trả success true và data là mảng rỗng. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | ## Param Nằm trên query string. Ngày lập dùng định dạng yyyy-MM-dd. Khi gửi cả issued_from và issued_to, khoảng tìm kiếm tối đa 10 ngày, tính cả ngày bắt đầu và ngày kết thúc. Vị trí: query. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `template_id` | string | có | Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA. Gồm ký hiệu mẫu số và ký hiệu hoá đơn. | | `issued_from` | string (date) | không | Ngày lập bắt đầu, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_to thì khoảng tối đa 10 ngày. | | `issued_to` | string (date) | không | Ngày lập kết thúc, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_from thì khoảng tối đa 10 ngày. | | `number` | integer | không | Số hoá đơn. Tối đa 8 chữ số. | | `invoice_code` | string | không | UUID của hoá đơn, cùng data.id trả về khi tạo. | | `invoice_kind` | integer | không | Loại hoá đơn cần lấy.
-1: tất cả, gồm hoá đơn nháp.
0: tất cả, không gồm hoá đơn nháp.
1: nháp.
2: hoá đơn mới.
3: hoá đơn xoá bỏ.
4: hoá đơn thay thế.
5: hoá đơn bị thay thế.
6: hoá đơn điều chỉnh tăng.
7: hoá đơn điều chỉnh giảm.
8: hoá đơn điều chỉnh thông tin.
9: hoá đơn điều chỉnh tăng và giảm.
10: hoá đơn bị điều chỉnh.
Tối đa 2 chữ số. | | `status` | integer | không | Trạng thái hoá đơn.
-1: tất cả, gồm hoá đơn nháp.
0: tất cả, không gồm hoá đơn nháp.
1: nháp.
2: lỗi ký.
3: chưa gửi cơ quan thuế.
4: đã cấp mã hoặc đã tiếp nhận.
5: cơ quan thuế chưa phản hồi.
6: không đủ điều kiện cấp mã hoặc tiếp nhận.
Tối đa 2 chữ số. | | `customer` | string | không | Tìm theo thông tin khách hàng. Khớp một trong buyer.name, buyer.tax_code, buyer.contact_name, reference. Tối đa 200 ký tự. | ## Ví dụ Lấy hoá đơn của mẫu 1C26TAA lập từ 01/04 đến 10/04/2026, trạng thái đã cấp mã hoặc đã tiếp nhận. Khoảng ngày không quá 10 ngày. cURL: ```bash curl "https://sandbox.api.hddt.dev/v1/invoices?template_id=1C26TAA&issued_from=2026-04-01&issued_to=2026-04-10&status=4" \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi gọi được, success là true. data là mảng hoá đơn. Trường từ issue_mode trở xuống nằm trong từng phần tử và dùng cùng key với API Tạo hoá đơn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `success` | boolean | có | true khi lấy được danh sách, false khi thất bại. | | `data` | array | có | Danh sách hoá đơn. Mảng rỗng khi không có hoá đơn khớp bộ lọc. | | `error_code` | string | có | Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ. | | `message` | string | có | Thông báo thành công hoặc thất bại. | | `invoice_code` | string | có | UUID của hoá đơn. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh. | | `number` | integer | không | Số hoá đơn. Tối đa 8 chữ số. | | `lookup_code` | string | không | Mã tra cứu. Tối đa 100 ký tự. | | `status` | integer | có | Trạng thái hoá đơn.
1: nháp.
2: lỗi ký.
3: chưa gửi cơ quan thuế.
4: đã cấp mã hoặc đã tiếp nhận.
5: cơ quan thuế chưa phản hồi.
6: không đủ điều kiện cấp mã hoặc tiếp nhận. | | `issue_mode` | integer | không | Cách tạo.
0: lưu nháp.
1: tạo và phát hành.
Tối đa 10 chữ số. | | `invoice_type` | integer | có | Tính chất hoá đơn.
0: hoá đơn mới.
1: thay thế.
2: điều chỉnh tăng.
3: điều chỉnh giảm.
4: điều chỉnh thông tin.
5: điều chỉnh tăng và giảm.
Tối đa 5 chữ số. | | `template_id` | string | không | Mã mẫu, ví dụ 1C26TAA. | | `issued_at` | string (date-time) | không | Ngày lập hoá đơn. | | `currency` | string | có | Mã tiền tệ ISO 4217.
VND: Việt Nam đồng.
USD: đô la Mỹ.
CAD: đô la Canada.
Hệ thống tự map sang mã của từng nhà cung cấp khi gọi nền tảng. | | `exchange_rate` | number | có | Tỷ giá. Với VND là 1. Tối đa 7 chữ số, 2 chữ số thập phân. | | `payment_method` | string | không | Hình thức thanh toán. | | `reference` | string | không | Mã tham chiếu của hoá đơn trên hệ thống của bạn. Tối đa 20 ký tự. | | `note` | string | không | Ghi chú. Tối đa 255 ký tự. | | `related_invoice_id` | string | không | UUID của hoá đơn gốc, lấy từ id của hoá đơn đó, khi invoice_type là thay thế hoặc điều chỉnh. | | `seller_store_code` | string | không | Mã cửa hàng, điểm bán. Xem mục Người bán. Tối đa 50 ký tự. | | `seller_store_name` | string | không | Tên cửa hàng, điểm bán. Xem mục Người bán. Tối đa 400 ký tự. | | `buyer` | object | không | Người mua. Xem mục Người mua. | | `items` | array | có | Danh sách hàng hoá, dịch vụ. Xem mục Dòng hàng. | | `fees` | array | không | Danh sách phí, lệ phí. Xem mục Loại phí. | | `subtotal` | number | có | Tổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân. | | `trade_discount` | number | có | Tổng tiền chiết khấu thương mại. Tối đa 21 chữ số, 6 chữ số thập phân. | | `other_deduction` | number | có | Tổng giảm trừ khác. Tối đa 21 chữ số, 6 chữ số thập phân. | | `tax_total` | number | có | Tổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân. | | `total` | number | có | Tổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân. | | `total_in_words` | string | không | Tổng tiền thanh toán bằng chữ. Tối đa 255 ký tự. | 200 OK: ```json { "success": true, "data": [ { "invoice_code": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "number": 125, "lookup_code": "7B164DE808", "status": 4, "issue_mode": 1, "invoice_type": 0, "template_id": "1C26TAA", "issued_at": "2026-04-11T06:46:41.850Z", "currency": "VND", "exchange_rate": 1, "payment_method": "TM/CK", "reference": "DH-1001", "seller_store_code": "CH01", "seller_store_name": "Cửa hàng Quận 1", "buyer": { "name": "Công ty TNHH ABC", "tax_code": "0312345678", "address": "123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh", "email": "ketoan@abc.vn" }, "items": [ { "item_type": 1, "line_number": 1, "name": "Gói phần mềm", "unit": "Gói", "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, "total_in_words": "Năm triệu năm trăm nghìn đồng" } ], "error_code": "", "message": "Thành công" } ``` ### Người bán Tên, mã số thuế và địa chỉ người bán lấy từ tài khoản đã đăng nhập. Đơn vị có nhiều điểm bán nhận lại mã cửa hàng và tên cửa hàng đã gửi lúc tạo hoá đơn. Hai trường có mặt khi hoá đơn có thông tin điểm bán. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `seller_store_code` | string | không | Mã cửa hàng, điểm bán. Tối đa 50 ký tự. | | `seller_store_name` | string | không | Tên cửa hàng, điểm bán. Tối đa 400 ký tự. | ### Người mua Các trường trong buyer. Có mặt khi hoá đơn có thông tin người mua. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `name` | string | không | Tên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự. | | `tax_code` | string | không | Mã số thuế người mua. Tối đa 14 ký tự. | | `address` | string | không | Địa chỉ. Tối đa 400 ký tự. | | `code` | string | không | Mã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự. | | `phone` | string | không | Số điện thoại. Tối đa 20 ký tự. | | `email` | string | không | Email. Tối đa 50 ký tự. | | `contact_name` | string | không | Họ và tên người mua hàng. Tối đa 100 ký tự. | | `bank_account` | string | không | Số tài khoản ngân hàng. | | `bank_name` | string | không | Tên ngân hàng. | | `citizen_id` | string | không | Số định danh cá nhân (CCCD). Tối đa 12 ký tự. | | `budget_unit_code` | string | không | Mã đơn vị quan hệ ngân sách. Tối đa 7 ký tự. | | `passport` | string | không | Số hộ chiếu hoặc giấy tờ nhập xuất cảnh. Tối đa 20 ký tự. | ### Dòng hàng Mỗi phần tử của items là một dòng hàng hoá hoặc dịch vụ. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `item_type` | integer | có | Tính chất dòng.
1: hàng hoá, dịch vụ.
2: khuyến mãi.
3: chiết khấu.
4: ghi chú. | | `line_number` | integer | có | Số thứ tự dòng. Tối đa 4 chữ số. | | `code` | string | không | Mã hàng hoá, dịch vụ. Tối đa 50 ký tự. | | `name` | string | có | Tên hàng hoá, dịch vụ. Tối đa 500 ký tự. | | `unit` | string | không | Đơn vị tính. Tối đa 50 ký tự. | | `quantity` | number | có | Số lượng. Tối đa 21 chữ số, 6 chữ số thập phân. | | `unit_price` | number | có | Đơn giá. Tối đa 21 chữ số, 6 chữ số thập phân. | | `amount_before_discount` | number | có | Thành tiền trước thuế, trước chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `discount_rate` | number | có | Tỷ lệ chiết khấu, đơn vị phần trăm. Tối đa 6 chữ số, 4 chữ số thập phân. | | `discount_amount` | number | có | Số tiền chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `amount` | number | có | Thành tiền trước thuế, sau chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân. | | `vat_rate` | number | có | Thuế suất.
-2: không kê khai, không nộp thuế.
-1: không chịu thuế.
0: 0%.
5: 5%.
8: 8%.
10: 10%.
3.5: thuế suất khác. | | `tax_amount` | number | có | Tiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân. | | `line_total` | number | có | Tiền sau thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân. | ### Loại phí Mỗi phần tử của fees là một loại phí. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `name` | string | không | Tên loại phí. Tối đa 100 ký tự. | | `amount` | number | không | Tiền phí. Tối đa 21 chữ số, 6 chữ số thập phân. | ## Mã lỗi Khi không lấy được danh sách, success là false, error_code và message mô tả lỗi nghiệp vụ. Lỗi xác thực và định dạng của hddt.dev vẫn trả mã HTTP kèm error.code và error.message. Ngoài các mã dưới đây, xem thêm trang Mã lỗi. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `400 bad_request` | — | không | Request sai định dạng. | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. | | `422 validation_error` | — | không | Thiếu template_id, template_id không đúng ký hiệu mẫu số và ký hiệu hoá đơn, ngày không đúng yyyy-MM-dd, hoặc invoice_kind, status ngoài danh mục. | | `429 rate_limited` | — | không | Vượt giới hạn số request cho phép. | Trang HTML: /docs/invoices/list Cập nhật: 10/11/2026 --- # Ký hoá đơn nháp > 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/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. ## Giới thiệu API ký một hoá đơn đang ở trạng thái nháp. Tạo nháp bằng API Tạo hoá đơn với issue_mode bằng 0, rồi gửi UUID trong data.id vào invoice_code của API này. Hoá đơn đã phát hành không ký lại bằng API này. Trên sandbox, hoá đơn không được gửi tới cơ quan thuế. ## Endpoint Gửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. > **Chỉ hoá đơn nháp:** invoice_code phải là UUID của hoá đơn vừa lưu nháp. Hoá đơn đã phát hành hoặc không tồn tại sẽ không được ký. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | | `Content-Type` | string | có | application/json. | ## Body Chỉ gửi mã số của hoá đơn nháp cần ký. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `invoice_code` | string | có | UUID của hoá đơn nháp, lấy từ data.id của API Tạo hoá đơn. | ## Ví dụ Ký hoá đơn nháp có id 7c9e6679-7425-40de-944b-e07fc1f90ae7 trên sandbox. cURL: ```bash curl -X POST https://sandbox.api.hddt.dev/v1/invoices/sign \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" \ -H "Content-Type: application/json" \ -d '{ "invoice_code": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }' ``` ## Phản hồi Khi ký được hoá đơn, success là true. data là dữ liệu trả về sau khi ký. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `success` | boolean | có | true khi ký được hoá đơn, false khi thất bại. | | `data` | object | có | Dữ liệu trả về khi ký thành công. Khi thất bại có thể trống. | | `error_code` | string | có | Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ. | | `message` | string | có | Thông báo thành công hoặc thất bại. | Phản hồi: ```json { "success": true, "data": {}, "error_code": "", "message": "Thành công" } ``` ## Mã lỗi Khi hoá đơn không được ký, success là false, error_code và message mô tả lỗi nghiệp vụ. Lỗi xác thực và định dạng của hddt.dev vẫn trả mã HTTP kèm error.code và error.message. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `422 validation_error` | — | không | Thiếu invoice_code. | Trang HTML: /docs/invoices/sign Cập nhật: 06/11/2026 --- # Xoá hoá đơn nháp > 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. `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. ## Giới thiệu API xoá một hoá đơn đang lưu nháp. Tạo nháp bằng API Tạo hoá đơn với issue_mode bằng 0, rồi gửi UUID trong data.id lên đường dẫn của API này. Hoá đơn đã phát hành không xoá được. Muốn bỏ một hoá đơn đã phát hành thì dùng quy trình thông báo sai sót, không dùng API này. Thao tác không hoàn tác được. ## Endpoint Gửi DELETE với UUID của hoá đơn nháp trên đường dẫn. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. > **Chỉ hoá đơn nháp:** id phải là UUID của hoá đơn vừa lưu nháp và chưa phát hành. Hoá đơn đã phát hành, đã ký, hoặc không thuộc ứng dụng sẽ không được xoá. ## Header Token, API key và App ID phải cùng ứng dụng, cùng môi trường. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Authorization` | string | có | Bearer token lấy từ API Lấy token. | | `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). | ## Param Nằm trên đường dẫn. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | UUID của hoá đơn nháp, lấy từ data.id của API Tạo hoá đơn. | ## Ví dụ Xoá hoá đơn nháp có id 7c9e6679-7425-40de-944b-e07fc1f90ae7 trên sandbox. cURL: ```bash curl -X DELETE https://sandbox.api.hddt.dev/v1/invoices/7c9e6679-7425-40de-944b-e07fc1f90ae7 \ -H "Authorization: Bearer $HDDT_TOKEN" \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi xoá được hoá đơn nháp, success là true. data.id là UUID vừa xoá. data.deleted là true. Nếu ứng dụng đã đăng ký sự kiện invoice_draft_deleted, hệ thống gửi webhook sau khi xoá. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `success` | boolean | có | true khi xoá được hoá đơn nháp, false khi thất bại. | | `data` | object | có | Kết quả xoá. Khi thành công có id và deleted. | | `error_code` | string | có | Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ. | | `message` | string | có | Thông báo thành công hoặc thất bại. | | `id` | string | có | UUID của hoá đơn nháp vừa xoá, nằm trong data. | | `deleted` | boolean | có | Luôn là true khi xoá thành công, nằm trong data. | 200 OK: ```json { "success": true, "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "deleted": true }, "error_code": "", "message": "Thành công" } ``` ## Mã lỗi Khi hoá đơn không được xoá, success là false, error_code và message mô tả lỗi nghiệp vụ. Lỗi xác thực và định dạng của hddt.dev vẫn trả mã HTTP kèm error.code và error.message. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn. | | `404 not_found` | — | không | Không có hoá đơn nháp với id này trong ứng dụng, hoặc hoá đơn đã được xoá. | | `422 validation_error` | — | không | id không phải UUID, hoặc hoá đơn không còn là nháp (đã ký hoặc đã phát hành). | Trang HTML: /docs/invoices/cancel Cập nhật: 10/11/2026 --- # Tra cứu mã số thuế > 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. `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. ## Giới thiệu Gọi API này khi người dùng nhập mã số thuế trên form bán hàng. Kết quả có tên, địa chỉ và trạng thái để điền người mua trước khi tạo hoá đơn. Trên sandbox, 0312345678 và 0109876543 luôn trả dữ liệu mẫu để thử. ## Endpoint Gửi GET với MST trên đường dẫn. MST 10 số chỉ khớp đúng đơn vị đó, không kèm chi nhánh. Muốn tra chi nhánh thì gửi đủ 13 số. Mọi request cần API key trong header api_key và App ID trong header app_id. API key phải thuộc đúng ứng dụng đó. Không dùng Authorization. Endpoint không trừ hạn mức phát hành hoá đơn, nhưng vẫn tính vào giới hạn số request. ## Header API key và App ID phải cùng một ứng dụng. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `api_key` | string | có | API key của ứng dụng. Phải thuộc đúng app_id. | | `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). | ## Param Nằm trên đường dẫn. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `mst` | string | có | Mã số thuế cần tra cứu. Chấp nhận 10 chữ số hoặc 13 chữ số (MST chi nhánh, dạng XXXXXXXXXX-XXX hoặc 13 số liền không dấu gạch). Chỉ gồm chữ số và dấu gạch ngang nếu có. | ## Ví dụ Request mẫu trên sandbox: cURL: ```bash curl https://sandbox.api.hddt.dev/v1/tax-codes/0312345678 \ -H "api_key: $HDDT_API_KEY" \ -H "app_id: $HDDT_APP_ID" ``` ## Phản hồi Khi tìm thấy MST, API trả 200 OK. Điền buyer bằng name, tax_code và address. Kiểm tra status trước khi phát hành. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `object` | string | có | Luôn là tax_code. | | `id` | string | có | Trùng tax_code. | | `tax_code` | string | có | MST đã chuẩn hoá. 10 số, hoặc chi nhánh dạng 0312345678-001. | | `name` | string | có | Tên đơn vị trên hồ sơ thuế. | | `name_international` | string \| null | có | Tên giao dịch quốc tế. null khi không có. | | `address` | string | có | Địa chỉ trên hồ sơ thuế. | | `status` | string | có | Mã trạng thái. Xem mục Trạng thái. Chỉ active là đang hoạt động. | | `status_label` | string | có | Câu tiếng Việt cùng nghĩa với status, dùng để hiện trên form. | | `tax_office` | string \| null | có | Cơ quan thuế quản lý. null khi không có. | | `representative` | string \| null | có | Người đại diện. null khi không có. | | `updated_at` | string | có | Thời điểm cập nhật thông tin, ISO 8601, múi giờ +07:00. | 200 OK: ```json { "object": "tax_code", "id": "0312345678", "tax_code": "0312345678", "name": "Công ty TNHH ABC", "name_international": null, "address": "123 Nguyễn Huệ, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh", "status": "active", "status_label": "Đang hoạt động", "tax_office": "Cục Thuế TP. Hồ Chí Minh", "representative": "Nguyễn Văn A", "updated_at": "2026-10-20T08:00:00+07:00" } ``` ### Trạng thái status là mã để kiểm tra. status_label là câu tiếng Việt để hiện trên form. | Mã | Mô tả | | --- | --- | | `active` | Đang hoạt động. | | `suspended` | Tạm ngừng hoạt động, hoặc đã ngừng nhưng chưa hoàn thành thủ tục chấm dứt MST. | | `inactive` | Không hoạt động tại địa chỉ đã đăng ký. | | `closed` | Đã ngừng hoạt động và đã chấm dứt hiệu lực MST. | | `unknown` | Không xác định được trạng thái. | > **Chỉ phát hành khi active:** Dùng name và address để điền người mua khi status là active. Các mã còn lại nghĩa là đơn vị không còn hoạt động bình thường. Nên báo cho người dùng trước khi tạo hoá đơn. ## Mã lỗi Các trường hợp thường gặp: | 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 hoặc đã thu hồi, hoặc API key không thuộc App ID. | | `404 not_found` | — | không | Không có đơn vị nào khớp MST đã nhập. | | `422 validation_error` | — | không | MST sai định dạng (độ dài, ký tự không hợp lệ). | | `429 rate_limited` | — | không | Vượt giới hạn số request tra cứu trong khoảng thời gian cho phép. | | `503 provider_unavailable` | — | không | Không tra cứu được mã số thuế lúc này. Thử lại sau. | Trang HTML: /docs/tax-codes Cập nhật: 10/11/2026 --- # Danh sách webhook > 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. `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ý. ## Giới thiệu API trả các webhook đã thêm cho ứng dụng. Header app_id là UUID dùng để tìm ứng dụng. Header api_key phải là key đang hiệu lực của đúng ứng dụng đó. Key có thể được tạo lại, nên không dùng key để định danh ứng dụng. Key hddt_test_ chỉ gọi Sandbox, key Live chỉ gọi Live. Sandbox và Live là hai danh sách riêng. Danh sách không trả secret dùng để ký thông báo. Secret chỉ có trong phản hồi của API Thêm webhook. Endpoint không dùng token hoá đơn và không trừ hạn mức phát hành. ## Endpoint Gửi GET. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. Chưa có webhook vẫn trả 200 và data là mảng rỗng. ## Header Gửi App ID để tìm ứng dụng, và API key của đúng ứng dụng đó. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `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). | | `api_key` | string | có | API key đang hiệu lực của ứng dụng có app_id ở trên. | ## Ví dụ Lấy webhook sandbox của ứng dụng có App ID đã gửi. cURL: ```bash curl https://sandbox.api.hddt.dev/v1/webhooks \ -H "app_id: $HDDT_APP_ID" \ -H "api_key: $HDDT_API_KEY" ``` ## Phản hồi Khi key hợp lệ, API trả 200. data là mảng webhook của môi trường đó. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `object` | string | có | Luôn là list. | | `data` | array | có | Danh sách webhook. Mảng rỗng khi chưa thêm webhook nào. Xem mục Webhook. | 200 OK: ```json { "object": "list", "data": [ { "id": "wh_8f2a1c9d", "object": "webhook", "url": "https://api.cua-ban.vn/webhooks/hddt", "enabled": true, "events": ["invoice_issued", "tax_authority_response"] } ] } ``` ### Webhook Mỗi phần tử của data là một webhook. Không có trường secret. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh webhook, ví dụ wh_8f2a1c9d. | | `object` | string | có | Luôn là webhook. | | `url` | string | có | URL HTTPS nhận thông báo. | | `enabled` | boolean | có | true khi webhook đang nhận thông báo, false khi đang tắt. | | `events` | array of string | có | Các mã trong bảng Sự kiện đang đăng ký. | ### Sự kiện đang đăng ký Mỗi phần tử của events là một mã dưới đây. all nhận mọi sự kiện còn lại. | Mã | Trạng thái | | --- | --- | | `all` | Tất cả | | `template_created` | Tạo mẫu hoá đơn | | `template_quantity_approved` | Duyệt số lượng mẫu hoá đơn | | `template_deleted` | Xoá mẫu hoá đơn | | `invoice_draft_created` | Tạo nháp hoá đơn | | `invoice_issued` | Phát hành hoá đơn | | `invoice_signed` | Ký hoá đơn | | `tax_authority_response` | CQT phản hồi | | `invoice_draft_deleted` | Xoá hoá đơn nháp | ## Mã lỗi Lỗi xác thực trả mã HTTP kèm error.code và error.message. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu header app_id hoặc api_key; API key sai, đã thu hồi, hoặc không thuộc app_id. | | `403 forbidden` | — | không | Gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live). | | `404 not_found` | — | không | Không có ứng dụng nào khớp app_id. | | `422 validation_error` | — | không | app_id không phải UUID. | Trang HTML: /docs/webhooks Cập nhật: 10/11/2026 --- # Thêm webhook > 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/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. ## Giới thiệu API thêm một webhook cho ứng dụng tìm theo header app_id. API key phải thuộc ứng dụng đó. Key hddt_test_ thêm vào sandbox. Key Live thêm vào production. Phản hồi có secret dạng whsec_. Lưu lại ngay. Các lần gọi API Danh sách webhook sau không trả secret này. Dùng secret để kiểm tra chữ ký trên header X-HDDT-Signature. ## Endpoint Gửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev. > **URL phải là HTTPS:** url nhận thông báo phải bắt đầu bằng https://. Không dùng địa chỉ nội bộ. ## Header Gửi App ID của ứng dụng cần gắn webhook và API key của ứng dụng đó. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `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). | | `api_key` | string | có | API key đang hiệu lực của ứng dụng có app_id ở trên. | | `Content-Type` | string | có | application/json. | ## Body Gửi URL và ít nhất một sự kiện. Bỏ trống enabled thì webhook được bật ngay. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `url` | string | có | URL HTTPS nhận POST khi có sự kiện. Ví dụ https://api.cua-ban.vn/webhooks/hddt. | | `events` | array of string | có | Sự kiện cần nhận. Gửi ít nhất một mã trong bảng Sự kiện đang đăng ký. | | `enabled` | boolean | không | Bật nhận thông báo ngay khi tạo.
true: bật.
false: tạo nhưng chưa gửi.
Bỏ trống thì hệ thống dùng true. | ### Sự kiện đang đăng ký Mỗi phần tử của events là một mã dưới đây. all nhận mọi sự kiện còn lại. | Mã | Trạng thái | | --- | --- | | `all` | Tất cả | | `template_created` | Tạo mẫu hoá đơn | | `template_quantity_approved` | Duyệt số lượng mẫu hoá đơn | | `template_deleted` | Xoá mẫu hoá đơn | | `invoice_draft_created` | Tạo nháp hoá đơn | | `invoice_issued` | Phát hành hoá đơn | | `invoice_signed` | Ký hoá đơn | | `tax_authority_response` | CQT phản hồi | | `invoice_draft_deleted` | Xoá hoá đơn nháp | ## Ví dụ Thêm webhook sandbox nhận lúc phát hành hoá đơn và lúc cơ quan thuế phản hồi. cURL: ```bash curl -X POST https://sandbox.api.hddt.dev/v1/webhooks \ -H "app_id: $HDDT_APP_ID" \ -H "api_key: $HDDT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.cua-ban.vn/webhooks/hddt", "events": ["invoice_issued", "tax_authority_response"] }' ``` ## Phản hồi Khi thêm được, API trả 201. secret chỉ có trong phản hồi này. Lưu lại để kiểm tra chữ ký các thông báo sau. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh webhook, ví dụ wh_8f2a1c9d. | | `object` | string | có | Luôn là webhook. | | `url` | string | có | URL HTTPS nhận thông báo. | | `enabled` | boolean | có | true khi webhook đang nhận thông báo, false khi đang tắt. | | `events` | array of string | có | Các mã trong bảng Sự kiện đang đăng ký. | | `secret` | string | có | Bí mật ký thông báo, tiền tố whsec_. Chỉ trả khi vừa thêm webhook. | 201 Created: ```json { "id": "wh_8f2a1c9d", "object": "webhook", "url": "https://api.cua-ban.vn/webhooks/hddt", "enabled": true, "events": ["invoice_issued", "tax_authority_response"], "secret": "whsec_4f8c2a91b7e64d0c" } ``` ## Thông báo gửi tới URL Khi sự kiện trong events xảy ra và enabled là true, hddt.dev gửi POST tới url. Body, chữ ký và cách kiểm tra nằm ở trang Nhận và kiểm tra webhook. ## Mã lỗi Lỗi xác thực và dữ liệu không hợp lệ trả mã HTTP kèm error.code và error.message. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | Thiếu header app_id hoặc api_key; API key sai, đã thu hồi, hoặc không thuộc app_id. | | `403 forbidden` | — | không | Gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live). | | `404 not_found` | — | không | Không có ứng dụng nào khớp app_id. | | `422 validation_error` | — | không | app_id không phải UUID, thiếu url hoặc events, url không phải HTTPS, events rỗng, hoặc có giá trị ngoài all, template_created, template_quantity_approved, template_deleted, invoice_draft_created, invoice_issued, invoice_signed, tax_authority_response, invoice_draft_deleted. | Trang HTML: /docs/webhooks/create Cập nhật: 10/11/2026 --- # Nhận và kiểm tra webhook > 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. Đọ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. ## Giới thiệu Khi một sự kiện đã đăng ký xảy ra và webhook đang bật, hddt.dev gửi POST tới URL của bạn. Thông báo này không gửi API key. Bạn dùng secret nhận lúc thêm webhook để kiểm tra chữ ký. Đọc nguyên văn body trước khi parse JSON. Chữ ký tính trên đúng chuỗi byte đó. Parse rồi stringify lại sẽ làm chữ ký không khớp. all chỉ dùng khi đăng ký. Thông báo gửi đi luôn có type là một sự kiện cụ thể. Request chờ tối đa 3 giây. Hệ thống không đọc body phản hồi và không gửi lại nếu URL lỗi hoặc quá hạn. ## Header Ba header này có trên mọi thông báo. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Content-Type` | string | có | application/json. | | `X-HDDT-Event` | string | có | Mã sự kiện. Trùng với type trong body. Không bao giờ là all. | | `X-HDDT-Signature` | string | có | Chữ ký, dạng sha256= rồi 64 ký tự hex. HMAC-SHA256 của nguyên văn body, khoá là secret. | ## Body Body là một JSON. Các trường dưới đây luôn có. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Mã thông báo, tiền tố evt_. Dùng để bỏ qua thông báo đã xử lý. | | `object` | string | có | Luôn là event. | | `type` | string | có | Mã sự kiện. Trùng header X-HDDT-Event. | | `created_at` | string | có | Thời điểm gửi, ISO 8601, múi giờ +07:00. | | `data` | object | có | Nội dung của sự kiện. Mỗi type có một body mẫu ở các mục bên dưới. | ### Tạo mẫu hoá đơn type là template_created. data là mẫu vừa tạo. published là false cho đến khi mẫu được duyệt số lượng. template_created: ```json { "id": "evt_91ab30c1", "object": "event", "type": "template_created", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "15899", "object": "invoice_template_registration", "template_id": "1C26TTV", "form": "1", "serial": "C26TTV", "published": false } } ``` ### Duyệt số lượng mẫu hoá đơn type là template_quantity_approved. data là mẫu sau khi được cấp số lượng. published là true. template_quantity_approved: ```json { "id": "evt_91ab30c3", "object": "event", "type": "template_quantity_approved", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "13362", "object": "invoice_template_registration", "template_id": "1C26TDV", "form": "1", "serial": "C26TDV", "year": 2026, "quantity": 10, "used": 0, "remaining": 10, "published": true } } ``` ### Xoá mẫu hoá đơn type là template_deleted. data là mẫu vừa xoá. deleted luôn là true. template_deleted: ```json { "id": "evt_91ab30c4", "object": "event", "type": "template_deleted", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "15899", "object": "invoice_template_registration", "deleted": true } } ``` ### Tạo nháp hoá đơn type là invoice_draft_created. data là hoá đơn nháp. status là draft. number và tax_authority_code là null khi chưa có số và chưa có mã cơ quan thuế. invoice_draft_created: ```json { "id": "evt_91ab30c5", "object": "event", "type": "invoice_draft_created", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "invoice", "status": "draft", "template_id": "1C26TAA", "number": null, "tax_authority_code": null, "total_amount": 1100000, "created_at": "2026-11-09T15:40:12+07:00" } } ``` ### Phát hành hoá đơn type là invoice_issued. data là hoá đơn vừa phát hành. status là issued. number đủ 8 chữ số. invoice_issued: ```json { "id": "evt_91ab30c2", "object": "event", "type": "invoice_issued", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "invoice", "status": "issued", "template_id": "1C26TAA", "number": "00000125", "tax_authority_code": null, "total_amount": 1100000, "created_at": "2026-11-09T15:40:12+07:00" } } ``` ### Ký hoá đơn type là invoice_signed. data là hoá đơn vừa ký. status là signed. invoice_signed: ```json { "id": "evt_91ab30c6", "object": "event", "type": "invoice_signed", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "invoice", "status": "signed", "template_id": "1C26TAA", "number": null, "tax_authority_code": null, "total_amount": 1100000, "created_at": "2026-11-09T15:40:12+07:00" } } ``` ### CQT phản hồi type là tax_authority_response. data.id là mã hoá đơn. status là mã trạng thái cơ quan thuế. status_label là câu tiếng Việt của mã đó. note là ghi chú, chuỗi rỗng khi không có. 1: nháp. 2: lỗi ký. 3: chưa gửi cơ quan thuế. 4: đã cấp mã hoặc đã tiếp nhận. 5: cơ quan thuế chưa phản hồi. 6: không đủ điều kiện cấp mã hoặc tiếp nhận. 7: mẫu 04/SS chưa tạo tờ khai. 8: mẫu 04/SS, cơ quan thuế chưa tiếp nhận. 9: mẫu 04/SS, cơ quan thuế đã phê duyệt. tax_authority_response: ```json { "id": "evt_91ab30c7", "object": "event", "type": "tax_authority_response", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "tax_authority_response", "tax_authority_code": "007865BA205F284530AA353E42B75820B9", "status": 4, "status_label": "Đã cấp mã hoặc đã tiếp nhận", "note": "" } } ``` ### Xoá hoá đơn nháp type là invoice_draft_deleted. data là hoá đơn nháp vừa xoá. deleted luôn là true. invoice_draft_deleted: ```json { "id": "evt_91ab30c8", "object": "event", "type": "invoice_draft_deleted", "created_at": "2026-11-09T15:41:00+07:00", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "object": "invoice", "status": "draft", "template_id": "1C26TAA", "number": null, "tax_authority_code": null, "total_amount": 1100000, "created_at": "2026-11-09T15:40:12+07:00", "deleted": true } } ``` ## Chữ ký Khoá HMAC là nguyên secret, gồm tiền tố whsec_. Dữ liệu ký là nguyên văn body, mã UTF-8. Thuật toán là SHA-256. Kết quả viết thường, dạng hex, rồi ghép sau sha256=. Với secret whsec_4f8c2a91b7e64d0c và chuỗi body bên dưới, header đúng là X-HDDT-Signature: sha256=f081d4627f881b9670d94176855760d44cb6c2e40f24aa686a6459e8750d1fee. Nguyên văn body: ```json {"id":"evt_91ab30c2","object":"event","type":"invoice_issued","created_at":"2026-11-09T15:41:00+07:00","data":{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","object":"invoice","status":"issued","template_id":"1C26TAA","number":"00000125","tax_authority_code":null,"total_amount":1100000,"created_at":"2026-11-09T15:40:12+07:00"}} ``` ## Kiểm tra Tính lại chữ ký từ secret và nguyên văn body. So sánh với header bằng hàm so sánh không phụ thuộc thời gian. Sau đó kiểm tra type trùng X-HDDT-Event, rồi mới dùng data. Từ chối khi thiếu header, chữ ký sai, hoặc type không khớp. Không xử lý data trước khi chữ ký đúng. ### Node.js rawBody là Buffer hoặc chuỗi đúng byte nhận được. Nếu framework đã parse JSON, hãy lấy bản raw trước bước đó. Node.js: ```javascript const crypto = require("crypto"); function signatureOk(rawBody, signature, secret) { const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); const expected = Buffer.from("sha256=" + digest); const actual = Buffer.from(signature ?? ""); if (expected.length !== actual.length) return false; return crypto.timingSafeEqual(expected, actual); } const secret = process.env.HDDT_WEBHOOK_SECRET; const signature = headers["x-hddt-signature"]; if (!signatureOk(rawBody, signature, secret)) { throw new Error("Chữ ký webhook không đúng"); } const event = JSON.parse(rawBody); if (event.type !== headers["x-hddt-event"]) { throw new Error("type không khớp X-HDDT-Event"); } ``` ### Python raw_body là bytes của body, chưa json.loads. Python: ```python import hmac import hashlib import json import os def signature_ok(raw_body: bytes, signature: str, secret: str) -> bool: digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() expected = "sha256=" + digest return hmac.compare_digest(expected, signature or "") secret = os.environ["HDDT_WEBHOOK_SECRET"] signature = headers.get("X-HDDT-Signature", "") if not signature_ok(raw_body, signature, secret): raise ValueError("Chữ ký webhook không đúng") event = json.loads(raw_body) if event["type"] != headers.get("X-HDDT-Event"): raise ValueError("type không khớp X-HDDT-Event") ``` ### PHP php://input là nguyên văn body. Đọc một lần rồi vừa kiểm tra chữ ký vừa json_decode. PHP: ```php