Tổng quan API

API hoadon.pro cho phép hệ thống của bạn (ERP, phần mềm kế toán, công cụ báo cáo) đọc hoá đơn, theo dõi kết nối Cơ quan Thuế, và nhận sự kiện qua webhook mà không cần mở giao diện web. Trang này nêu các quy ước chung áp dụng cho mọi endpoint.

Địa chỉ và tài liệu tham chiếu

Mục	Giá trị
Địa chỉ gốc	`https://api.hoadon.pro`
API công khai	Mọi đường dẫn bắt đầu bằng `/v1/`
Tra cứu endpoint và schema	Scalar
Đặc tả OpenAPI 3.1	`https://api.hoadon.pro/openapi.json`

Tài liệu ở site này giải thích khái niệm và quy ước. Danh sách endpoint, tham số và schema đầy đủ luôn nằm ở Scalar, được sinh trực tiếp từ đặc tả nên không bao giờ lệch với API thật.

Quy ước dữ liệu

JSON, snake_case cho mọi trường.
Ngày theo định dạng YYYY-MM-DD; thời điểm theo RFC 3339, ví dụ 2026-10-15T09:30:12Z.
Tiền tệ là chuỗi số thập phân, không phải số: "31350000", "12.5". Điều này tránh sai số dấu phẩy động; hãy đọc bằng kiểu decimal của ngôn ngữ bạn dùng.
Mã số thuế là chuỗi, kể cả khi toàn chữ số, để giữ số 0 đứng đầu.

Phạm vi tổ chức

Dữ liệu thuộc về các tổ chức (xem Khái niệm). Khoá API chỉ truy cập được các tổ chức mà nó được cấp:

Endpoint danh sách nhận tham số org_id (có thể lặp lại để chọn nhiều tổ chức). Nếu bỏ trống, API trả dữ liệu của mọi tổ chức khoá được phép truy cập.
Endpoint tạo mới nhận org_id trong nội dung yêu cầu.
Truy cập một tài nguyên theo mã mà khoá không có quyền trả về 404 (không tìm thấy), không phải 403, để không tiết lộ tài nguyên có tồn tại hay không.

Các bước đầu tiên

Tạo API key và lưu khoá an toàn.
Gọi API đầu tiên.
Đọc Xác thực, Phân trang, Lỗi.
Với thao tác ghi, dùng Idempotency; chú ý giới hạn tốc độ.
Để nhận sự kiện theo thời gian thực, cấu hình webhook.

Môi trường thử

Khoá có tiền tố hd_test_ dành cho môi trường thử nghiệm; khoá hd_live_ dành cho dữ liệu thật. Xem Xác thực.