# 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