# 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