Thông tin xác thực dùng cho API

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.

Nội dung

1.Bật tính năng API tích hợp 2.Các thông tin xác thực 3.Cách sử dụng trong Request 4.Ví dụ thực tế 5.Lưu ý bảo mật

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"

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.

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

Ví dụ

088287028781

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ợ