/v1/invoicesTạo hoá đơn
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
Header
Token, API key và App ID phải cùng ứng dụng, cùng môi trường.
AuthorizationstringBắt buộcBearer token lấy từ API Lấy token.
api_keystringBắt buộcAPI key của ứng dụng.
app_idstringBắt buộ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-TypestringBắt buộcapplication/json.
Idempotency-KeystringTuỳ chọnChuỗ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.
issue_modeintegerTuỳ chọnCách tạo.
0 lưu nháp
1 tạo và phát hành
Tối đa 10 chữ số.
invoice_typeintegerBắt buộcTí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_idstringTuỳ chọnMã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA.
issued_atstring (date-time)Tuỳ chọnNgày lập hoá đơn.
currencystringBắt buộcMã 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_ratenumberBắt buộcTỷ giá. Với VND gửi 1. Tối đa 7 chữ số, 2 chữ số thập phân.
payment_methodstringTuỳ chọnHình thức thanh toán.
lookup_codestringTuỳ chọnMã tra cứu. Tối đa 100 ký tự.
lookup_code_duplicate_policyintegerTuỳ chọnCá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.
referencestringTuỳ chọnMã 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_policyintegerTuỳ chọnCá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.
notestringTuỳ chọnGhi chú. Tối đa 255 ký tự.
related_invoice_idstringTuỳ chọnUUID 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.
subtotalnumberBắt buộcTổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân.
trade_discountnumberBắt buộcTổ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_deductionnumberBắt buộcTổ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_totalnumberBắt buộcTổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân.
totalnumberBắt buộcTổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân.
total_in_wordsstringTuỳ chọnTổng tiền thanh toán bằng chữ. Tối đa 255 ký tự.
buyerobjectTuỳ chọnNgười mua. Xem mục Người mua.
itemsarrayBắt buộcDanh sách hàng hoá, dịch vụ. Xem mục Dòng hàng.
feesarrayTuỳ chọnDanh 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.
seller_store_codestringTuỳ chọnMã cửa hàng, điểm bán. Tối đa 50 ký tự.
seller_store_namestringTuỳ chọnTê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ế.
namestringTuỳ chọnTên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự.
tax_codestringTuỳ chọnMã số thuế người mua. Tối đa 14 ký tự.
addressstringTuỳ chọnĐịa chỉ. Tối đa 400 ký tự.
codestringTuỳ chọnMã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự.
phonestringTuỳ chọnSố điện thoại. Tối đa 20 ký tự.
emailstringTuỳ chọnEmail. Tối đa 50 ký tự.
contact_namestringTuỳ chọnHọ và tên người mua hàng. Tối đa 100 ký tự.
bank_accountstringTuỳ chọnSố tài khoản ngân hàng.
bank_namestringTuỳ chọnTên ngân hàng.
citizen_idstringTuỳ chọnSố định danh cá nhân (CCCD). Tối đa 12 ký tự.
budget_unit_codestringTuỳ chọnMã đơn vị quan hệ ngân sách. Tối đa 7 ký tự.
passportstringTuỳ chọnSố 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ụ.
item_typeintegerBắt buộcTí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_numberintegerBắt buộcSố thứ tự dòng. Tối đa 4 chữ số.
codestringTuỳ chọnMã hàng hoá, dịch vụ. Tối đa 50 ký tự.
namestringBắt buộcTên hàng hoá, dịch vụ. Tối đa 500 ký tự.
unitstringTuỳ chọnĐơn vị tính. Tối đa 50 ký tự.
quantitynumberBắt buộcSố lượng. Tối đa 21 chữ số, 6 chữ số thập phân.
unit_pricenumberBắt buộcĐơn giá. Tối đa 21 chữ số, 6 chữ số thập phân.
amount_before_discountnumberBắt buộcThà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_ratenumberBắt buộcTỷ 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_amountnumberBắt buộcSố 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.
amountnumberBắt buộcThà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_ratenumberBắt buộcThuế 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_amountnumberBắt buộcTiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân.
line_totalnumberBắt buộcTiề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.
namestringTuỳ chọnTên loại phí. Tối đa 100 ký tự.
amountnumberTuỳ chọnTiề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 -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": "[email protected]"
},
"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
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.
successbooleanBắt buộctrue khi tạo được hoá đơn, false khi thất bại.
dataobjectBắt buộcKế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_codestringBắt buộcTrống khi thành công. Khi thất bại là mã lỗi nghiệp vụ.
messagestringBắt buộcThông báo thành công hoặc thất bại.
idstringTuỳ chọnUUID 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.
numberintegerTuỳ chọnSố hoá đơn nằm trong data khi tạo thành công. Tối đa 8 chữ số.
lookup_codestringTuỳ chọnMã tra cứu nằm trong data khi tạo thành công. Tối đa 100 ký tự.
pdf_urlstringTuỳ chọnCó 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_urlstringTuỳ chọnChỉ 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.
{
"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.
400 bad_request—Tuỳ chọnRequest sai định dạng hoặc thiếu tham số bắt buộc.
401 unauthorized—Tuỳ chọnThiế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—Tuỳ chọnHết hạn mức hoá đơn của môi trường đang gọi.
404 not_found—Tuỳ chọnKhông tìm thấy template_id hoặc related_invoice_id.
409 conflict—Tuỳ chọnTrù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—Tuỳ chọnDữ 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—Tuỳ chọnVượt giới hạn số request cho phép.