Lấy danh sách mẫu hoá đơn
Đang hỗ trợMẫu số và ký hiệu đã đăng ký, chọn khi tạo hoá đơn.
/v1/invoices/templates
API hoá đơn điện tử dành cho developer
Tạo, tra cứu và tải hoá đơn điện tử qua REST API thống nhất. hddt.dev kết nối nhà cung cấp hoá đơn và điều phối chữ ký số cùng quy trình gửi nhận kết quả, để đội ngũ của bạn tập trung vào sản phẩm.
REST API · JSON · Sandbox riêng · Gọi trực tiếp bằng HTTP
Vì sao dùng hddt.dev
Một lớp API thống nhất giúp nối quy trình hoá đơn điện tử vào phần mềm bán hàng, ERP, CRM hoặc nền tảng bạn đang xây.
Tạo, tra cứu và tải hoá đơn qua REST và JSON, thay vì tự nối nhiều luồng với nhà cung cấp hoá đơn.
Kiểm thử bằng key và dữ liệu sandbox. Hoá đơn sandbox không được gửi cơ quan thuế.
Mỗi app có App ID, API key và môi trường riêng để tách sản phẩm, quyền truy cập và hạn mức.
Đọc kết quả trên response, tra cứu danh sách hoá đơn, hoặc nhận webhook khi đã cấu hình.
Tích hợp
Bắt đầu trong Sandbox, kiểm thử quy trình, rồi chuyển Live khi ứng dụng đã sẵn sàng.
Đăng ký hoặc đăng nhập bằng email, vào console và tạo app cho hệ thống cần tích hợp.
App mới có sẵn key sandbox. Dùng key đó cùng App ID để lấy token và gọi API thử.
Lấy mẫu hoá đơn, tạo hoá đơn thử, đối chiếu response và các mã lỗi trên tài liệu.
Khai báo mã số thuế, tích hợp thử trên sandbox, rồi gửi yêu cầu bật Live. Key Live chỉ dùng sau khi được duyệt.
API
Chọn endpoint theo việc cần làm.
Chuẩn bị mẫu, tạo hoá đơn, xem danh sách và tải file.
Mẫu số và ký hiệu đã đăng ký, chọn khi tạo hoá đơn.
/v1/invoices/templatesLưu nháp hoặc tạo và phát hành, tuỳ issue_mode.
/v1/invoicesLọc theo mẫu, ngày lập, số hoá đơn, loại và trạng thái.
/v1/invoicesTải PDF để gửi khách hoặc XML để lưu trữ, đối soát.
/v1/invoices/{id}/downloadĐiền thông tin người mua trước khi tạo hoá đơn.
Lấy tên, địa chỉ và trạng thái hoạt động từ mã số thuế.
/v1/tax-codes/{mst}Ví dụ
Gửi dữ liệu người mua và hàng hoá. API trả mã hoá đơn để bạn lưu và theo dõi tiếp. Đây là ví dụ rút gọn, không đủ cho mọi loại hoá đơn.
curl -X POST https://sandbox.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" \
-d '{
"issue_mode": 0,
"invoice_type": 0,
"template_id": "1C26TAA",
"currency": "VND",
"exchange_rate": 1,
"buyer": {
"tax_code": "0312345678",
"name": "Công ty TNHH ABC"
},
"items": [{
"item_type": 1,
"line_number": 1,
"name": "Gói phần mềm",
"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
}'Response minh hoạ
success là kết quả tạo hoá đơn trên môi trường đang gọi.
{
"success": true,
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"number": 125,
"lookup_code": "ABC123"
},
"error_code": "",
"message": "Thành công"
}Ví dụ lưu nháp trên Sandbox với issue_mode bằng 0. Phát hành dùng issue_mode bằng 1. Token lấy từ POST /v1/invoices/token, rồi gửi kèm api_key và app_id. Một số API khác, như tra cứu mã số thuế, dùng Authorization Bearer với chính API key.
Luồng xử lý
Các bước dưới đây là cách hệ thống điều phối. Không phải bước nào cũng xong ngay trong cùng một response.
Hệ thống của bạn gọi API với token, API key và App ID cùng môi trường.
hddt.dev kiểm tra xác thực, định dạng và các trường bắt buộc trước khi tạo.
Nền tảng điều phối lập hoá đơn và ký số theo cấu hình của ứng dụng.
Live đi theo quy trình phát hành. Sandbox dừng ở dữ liệu thử, không gửi cơ quan thuế.
Mã hoá đơn, số hoá đơn và mã tra cứu trả về để bạn lưu và đối soát.
Đọc lại trạng thái bằng API, hoặc nhận sự kiện nếu webhook của app đang bật.
Developer Console
Quản lý thông tin kết nối, API key, chữ ký số và nhật ký request theo từng ứng dụng.
Ứng dụng
Shop demo
API key
hddt_test_4f9c••••••••••a21eCông ty TNHH ABC
5.500.000 ₫
Cửa hàng demo
1.210.000 ₫
Dữ liệu minh hoạ. Key được che.
Use case
Bạn vẫn dựng workflow trong phần mềm của mình. hddt.dev cung cấp API để gọi tại bước lập và theo dõi hoá đơn.
Có thể gọi API tạo hoá đơn từ đơn hàng sau khi thanh toán hoặc hoàn tất giao dịch.
Có thể nối dữ liệu khách hàng và đơn hàng sang hoá đơn trong quy trình bạn đang vận hành.
Mỗi doanh nghiệp dùng phần mềm của bạn có thể gắn với một ứng dụng và bộ key riêng.
Có thể lập hoá đơn từ đơn hàng và đồng bộ mã tra cứu, số hoá đơn về hệ thống quản lý.
Vận hành
Những khả năng dưới đây đang có trên console và API. Tuân thủ hoá đơn còn phụ thuộc dữ liệu đầu vào, chứng thư số và quy định hiện hành.
Key sandbox có tiền tố riêng. Key Live không dùng lẫn với host sandbox.
Thu hồi trên console khi key lộ. Key đã thu hồi không gọi được API.
Request tới API đi qua HTTPS. Webhook đăng ký bằng URL HTTPS.
Có thể khai báo dải IP được phép gọi API cho từng môi trường của app.
Console đọc nhật ký theo môi trường đang xem khi API đã ghi log.
Tab Chữ ký số hiện chứng thư đang khai báo. Kết quả phát hành còn phụ thuộc chứng thư, dữ liệu và quy trình áp dụng.
Chi phí
Sandbox để kiểm thử. Live tính theo hạn mức hoá đơn. Chữ ký số là gói riêng.
Dùng để kiểm thử tích hợp. Hoá đơn tạo trên sandbox không gửi cơ quan thuế.
Phí phát hành tính theo gói hạn mức hoá đơn trên môi trường Live. Chi tiết từng bậc nằm ở trang bảng giá.
Gói chữ ký số tính riêng, không gộp vào hạn mức hoá đơn. Xem cùng trang bảng giá.
Hỏi đáp
Không. Hoá đơn tạo bằng key và host sandbox không được gửi cơ quan thuế. Dùng Live sau khi ứng dụng được duyệt để phát hành hoá đơn thật.
Trên tổng quan ứng dụng, hoàn tất tích hợp thử trên sandbox và khai báo mã số thuế ở Cài đặt hoá đơn. Đủ điều kiện thì gửi yêu cầu chuyển Live. Đội hỗ trợ xác minh rồi mới bật Live. Sau đó dùng host và API key của Live, không dùng lại key sandbox.
Khai báo mã số thuế và tên đơn vị ở tab Cài đặt hoá đơn. Chứng thư số hiện ở tab Chữ ký số khi tài khoản nhà cung cấp đã được gắn với app. Việc chọn hoặc đăng ký chứng thư mới trên tab hiện chưa được lưu.
Mọi ngôn ngữ gửi được HTTP. Trang này có ví dụ cURL, Node.js, Python và PHP bằng HTTP thuần. Không cần cài SDK để gọi API.
Có. Mỗi ứng dụng có App ID và API key riêng cho Sandbox và cho Live. Thu hồi key trên tab Kết nối và bảo mật của đúng môi trường.
Không kết luận chỉ từ timeout. Khi tạo hoá đơn có thể gửi header Idempotency-Key. 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. Bạn cũng có thể tra cứu lại bằng API danh sách hoá đơn.
Không. success cho biết request tạo được hoá đơn trên môi trường đang gọi và trả id (UUID), number, lookup_code. Trạng thái với cơ quan thuế cần tra cứu tiếp hoặc nhận webhook, nếu bạn đã đăng ký.
Có endpoint tải hoá đơn để lấy PDF hoặc XML. Cách gọi và tham số nằm trong tài liệu API.
Đăng ký được các sự kiện: tất cả, tạo mẫu hoá đơn, duyệt số lượng mẫu hoá đơn, xoá mẫu hoá đơn, tạo nháp hoá đơn, phát hành hoá đơn, ký hoá đơn, CQT phản hồi, và xoá hoá đơn nháp. Bí mật ký chỉ trả một lần lúc tạo webhook. Thông báo là JSON. Chữ ký là HMAC-SHA256 của nguyên văn body. URL được chờ tối đa 3 giây và không được gửi lại nếu lỗi.
Tạo tài khoản, khởi tạo ứng dụng và thử API trong Sandbox trước khi kết nối Live.