hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuTạo hoá đơn
POST/v1/invoices

Tạ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.

MarkdownOpenAPI

#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.

AuthorizationstringBắt buộc

Bearer token lấy từ API Lấy token.

api_keystringBắt buộc

API 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ộc

application/json.

Idempotency-KeystringTuỳ chọn

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.

issue_modeintegerTuỳ chọn

Cá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ộ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_idstringTuỳ chọn

Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA.

issued_atstring (date-time)Tuỳ chọn

Ngày lập hoá đơn.

currencystringBắt buộ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_ratenumberBắt buộc

Tỷ giá. Với VND gửi 1. Tối đa 7 chữ số, 2 chữ số thập phân.

payment_methodstringTuỳ chọn

Hình thức thanh toán.

lookup_codestringTuỳ chọn

Mã tra cứu. Tối đa 100 ký tự.

lookup_code_duplicate_policyintegerTuỳ chọn

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.

referencestringTuỳ chọn

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_policyintegerTuỳ chọn

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.

notestringTuỳ chọn

Ghi chú. Tối đa 255 ký tự.

related_invoice_idstringTuỳ chọn

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.

subtotalnumberBắt buộc

Tổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân.

trade_discountnumberBắt buộ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_deductionnumberBắt buộ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_totalnumberBắt buộc

Tổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân.

totalnumberBắt buộ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_wordsstringTuỳ chọn

Tổng tiền thanh toán bằng chữ. Tối đa 255 ký tự.

buyerobjectTuỳ chọn

Người mua. Xem mục Người mua.

itemsarrayBắt buộc

Danh sách hàng hoá, dịch vụ. Xem mục Dòng hàng.

feesarrayTuỳ chọn

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.

seller_store_codestringTuỳ chọn

Mã cửa hàng, điểm bán. Tối đa 50 ký tự.

seller_store_namestringTuỳ chọn

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ế.

namestringTuỳ chọn

Tên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự.

tax_codestringTuỳ chọn

Mã số thuế người mua. Tối đa 14 ký tự.

addressstringTuỳ chọn

Địa chỉ. Tối đa 400 ký tự.

codestringTuỳ chọn

Mã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự.

phonestringTuỳ chọn

Số điện thoại. Tối đa 20 ký tự.

emailstringTuỳ chọn

Email. Tối đa 50 ký tự.

contact_namestringTuỳ chọn

Họ và tên người mua hàng. Tối đa 100 ký tự.

bank_accountstringTuỳ chọn

Số tài khoản ngân hàng.

bank_namestringTuỳ chọn

Tên ngân hàng.

citizen_idstringTuỳ chọn

Số định danh cá nhân (CCCD). Tối đa 12 ký tự.

budget_unit_codestringTuỳ chọn

Mã đơn vị quan hệ ngân sách. Tối đa 7 ký tự.

passportstringTuỳ chọn

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ụ.

item_typeintegerBắt buộ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_numberintegerBắt buộc

Số thứ tự dòng. Tối đa 4 chữ số.

codestringTuỳ chọn

Mã hàng hoá, dịch vụ. Tối đa 50 ký tự.

namestringBắt buộc

Tê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ộc

Số 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ộ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_ratenumberBắt buộ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_amountnumberBắt buộ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.

amountnumberBắt buộ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_ratenumberBắt buộ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_amountnumberBắt buộc

Tiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân.

line_totalnumberBắt buộ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.

namestringTuỳ chọn

Tên loại phí. Tối đa 100 ký tự.

amountnumberTuỳ chọn

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
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

Đổ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.

successbooleanBắt buộc

true khi tạo được hoá đơn, false khi thất bại.

dataobjectBắt buộ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_codestringBắt buộc

Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ.

messagestringBắt buộc

Thông báo thành công hoặc thất bại.

idstringTuỳ chọn

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.

numberintegerTuỳ chọn

Số hoá đơn nằm trong data khi tạo thành công. Tối đa 8 chữ số.

lookup_codestringTuỳ chọn

Mã tra cứu nằm trong data khi tạo thành công. Tối đa 100 ký tự.

pdf_urlstringTuỳ chọn

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_urlstringTuỳ chọn

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
{
  "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ọn

Request sai định dạng hoặc thiếu tham số bắt buộc.

401 unauthorized—Tuỳ chọn

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—Tuỳ chọn

Hết hạn mức hoá đơn của môi trường đang gọi.

404 not_found—Tuỳ chọn

Không tìm thấy template_id hoặc related_invoice_id.

409 conflict—Tuỳ chọn

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—Tuỳ chọn

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—Tuỳ chọn

Vượt giới hạn số request cho phép.

Trước đóXoá mẫu chưa duyệtTiếp theoDanh sách hoá đơn
Trang này có hữu ích không?
Cập nhật lần cuối: 10/11/2026

Trên trang này

  • Giới thiệu
  • Endpoint
  • Header
  • Body
  • Người bán
  • Người mua
  • Dòng hàng
  • Loại phí
  • Ví dụ
  • Phản hồi
  • Mã lỗi
Đăng nhậpBắt đầu ngay