Xác thực API (Authentication)
Hướng dẫn lấy thông tin xác thực và sử dụng API_KEY, SECRET_KEY, STORE_KEY để kết nối hệ thống ngoài với QBIS.
Thiết lập
1. Bật tính năng API tích hợp
Trước khi sử dụng API, quản trị viên cần bật tính năng trong phần cấu hình hệ thống.
Quản trị › Cấu hình phần mềm › API tích hợp QBIS › Bật "Cho phép mở kết nối API"
1
Truy cập menu Quản trị
Đăng nhập bằng tài khoản có quyền Quản trị hệ thống. Vào Quản trị → Cấu hình phần mềm → API tích hợp QBIS.
2
Bật tùy chọn kết nối API
Tìm tùy chọn "Cho phép mở kết nối API vào phần mềm" và bật lên (ON). Hệ thống tự sinh 3 thông tin xác thực.
✓
3 thông tin xác thực được sinh tự động
Hệ thống tự sinh API_KEY, SECRET_KEY và STORE_KEY. Sao chép và lưu lại ở nơi bảo mật.
Thông tin xác thực
2. Các thông tin xác thực
Sau khi bật tính năng, hệ thống cung cấp 3 thông tin cần thiết để xác thực mọi request API:
🔐
API_KEY Hệ thống tự sinh
Mã định danh kết nối — dùng để nhận biết nguồn gọi API
Ví dụ
qbis_key_a1b2c3d4e5f6g7h8i9j0
🔒
SECRET_KEY Hệ thống tự sinh
Key bảo mật — dùng để ký và xác minh tính toàn vẹn của request
Ví dụ
qbis_secret_z9y8x7w6v5u4t3s2r1q0
🏢
STORE_KEY Mã định danh đơn vị
Mã định danh của đơn vị sử dụng — xác định dữ liệu thuộc về tổ chức nào trên QBIS
Cách sử dụng
3. Cách sử dụng trong Request
Cả 3 thông tin xác thực được truyền vào body data của mỗi request. Tất cả API đều dùng HTTP POST.
| Trường |
Vị trí |
BB |
Giá trị |
api_key |
Body JSON |
Có |
Giá trị API_KEY từ cấu hình |
secret_key |
Body JSON |
Có |
Giá trị SECRET_KEY từ cấu hình |
store_key |
Body JSON |
Có |
Giá trị STORE_KEY từ cấu hình |
...params |
Body JSON |
Tùy endpoint |
Tham số nghiệp vụ của từng API |
📋
Content-Type bắt buộc: Mọi request phải có header Content-Type: application/json và URL phải dùng HTTPS.
Ví dụ
4. Ví dụ thực tế
Ví dụ gọi API lấy danh sách Lead với đầy đủ 3 thông tin xác thực trong body:
cURL
curl -X POST https://api.qbis.vn/v1/leads/list \
-H "Content-Type: application/json" \
-d '{
"api_key": "qbis_key_a1b2c3d4e5f6g7h8i9j0",
"secret_key": "qbis_secret_z9y8x7w6v5u4t3s2r1q0",
"store_key": "088287028781",
"page": 1,
"limit": 20
}'
JavaScript
const response = await fetch('https://api.qbis.vn/v1/leads/list', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
api_key: 'qbis_key_a1b2c3d4e5f6g7h8i9j0',
secret_key: 'qbis_secret_z9y8x7w6v5u4t3s2r1q0',
store_key: '088287028781',
page: 1, limit: 20
})
});
const data = await response.json();
PHP
$response = Http::post('https://api.qbis.vn/v1/leads/list', [
'api_key' => 'qbis_key_a1b2c3d4e5f6g7h8i9j0',
'secret_key' => 'qbis_secret_z9y8x7w6v5u4t3s2r1q0',
'store_key' => '088287028781',
'page' => 1, 'limit' => 20,
]);
$data = $response->json();
Response — Thành công
{ "success": true, "code": 200, "data": { "items": [...], "total": 142 } }
Response — Lỗi xác thực
{ "success": false, "code": 401, "message": "api_key không hợp lệ hoặc không có quyền truy cập" }
Bảo mật
5. Lưu ý bảo mật
🚫
Không commit key vào source code. Dùng biến môi trường (.env) hoặc secret manager để lưu API_KEY và SECRET_KEY.
🚫
Không gọi API từ frontend (browser/app). Key sẽ bị lộ. Mọi request phải thực hiện từ phía server-side.
⚠️
Cấp lại key khi nghi ngờ bị lộ. Vào Quản trị → API tích hợp QBIS, tắt và bật lại để hệ thống sinh bộ key mới. Key cũ bị vô hiệu hóa ngay lập tức.
✅
Luôn dùng HTTPS. Mọi request đến API QBIS phải qua HTTPS. Request HTTP thuần sẽ bị từ chối.
Cần hỗ trợ thiết lập kết nối API?
Đội kỹ thuật QBIS sẵn sàng hỗ trợ thiết kế và kiểm tra luồng tích hợp.
✉ Liên hệ hỗ trợ