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ệuDanh sách hoá đơn
GET/v1/invoices

Danh sách hoá đơn

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.

MarkdownOpenAPI

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

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

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

template_idstringBắt buộ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_fromstring (date)Tuỳ chọn

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_tostring (date)Tuỳ chọn

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.

numberintegerTuỳ chọn

Số hoá đơn. Tối đa 8 chữ số.

invoice_codestringTuỳ chọn

UUID của hoá đơn, cùng data.id trả về khi tạo.

invoice_kindintegerTuỳ chọn

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

statusintegerTuỳ chọn

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

customerstringTuỳ chọn

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

successbooleanBắt buộc

true khi lấy được danh sách, false khi thất bại.

dataarrayBắt buộc

Danh sách hoá đơn. Mảng rỗng khi không có hoá đơn khớp bộ lọc.

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.

invoice_codestringBắt buộc

UUID của hoá đơn. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh.

numberintegerTuỳ chọn

Số hoá đơn. Tối đa 8 chữ số.

lookup_codestringTuỳ chọn

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

statusintegerBắt buộ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_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, 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 là 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.

referencestringTuỳ chọn

Mã tham chiếu của hoá đơn trên hệ thống của bạn. Tối đa 20 ký tự.

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 đó, khi invoice_type là thay thế hoặc điều chỉnh.

seller_store_codestringTuỳ chọn

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

seller_store_namestringTuỳ chọn

Tên cửa hàng, điểm bán. Xem mục Người bán. Tối đa 400 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í.

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

200 OK
{
  "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": "[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"
    }
  ],
  "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.

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. Có mặt khi hoá đơn có thông tin người mua.

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

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.

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

400 bad_request—Tuỳ chọn

Request sai định dạng.

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.

422 validation_error—Tuỳ chọn

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

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

Trước đóTạo hoá đơnTiếp theoKý hoá đơn nháp
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
  • Param
  • Ví dụ
  • Phản hồi
  • Người bán
  • Người mua
  • Dòng hàng
  • Loại phí
  • Mã lỗi
Đăng nhậpBắt đầu ngay