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

Mỗi request gửi kèm 3 khoá của đơn vị trong header. QBIS chỉ xử lý khi khoá đúng và đơn vị đã bật kết nối API; dữ liệu đọc, ghi luôn thuộc đúng đơn vị sở hữu khoá.

1. Bật kết nối API cho đơn vị

Gửi yêu cầu để QBIS bật tính năng API tích hợp cho đơn vị của bạn. Sau đó quản trị đơn vị vào phần mềm QBIS: Cấu hình phần mềm → API tích hợp QBIS, bật Mở kết nối API vào phần mềm và xem 3 khoá.

2. Ba khoá của đơn vị

Khoá	Ý nghĩa
STORE KEY	Mã đơn vị (12 số) — cho QBIS biết dữ liệu thuộc đơn vị nào.
API KEY	Định danh khoá. Bản ghi tạo qua API ghi người tạo là khoá này.
SECRET KEY	Mật khẩu của khoá — chỉ lưu ở máy chủ của bạn, không đưa cho bên thứ ba.

3. Gửi khoá trong header

Mỗi request gửi đủ 3 header dưới đây; lệnh POST / PUT thêm Content-Type.

Header	Giá trị
`X-Store-Key`	STORE KEY (mã đơn vị)
`X-Api-Key`	API KEY
`X-Secret-Key`	SECRET KEY
`Content-Type`	`application/json; charset=utf-8` (với POST / PUT)

Kiểm tra khoá trước — lệnh chỉ đọc, không ghi gì, trả định nghĩa trường của một API:

curl https://db.qbis.vn/open/api/v1/_schema/customers \
  -H "X-Store-Key: YOUR_STORE_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY"

Ví dụ tìm khách hàng theo số điện thoại:

curl https://db.qbis.vn/open/api/v1/customers/0901234567 \
  -H "X-Store-Key: YOUR_STORE_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY"

Ví dụ gọi thử tạo khách hàng, chưa ghi (dryRun=1):

curl -X POST "https://db.qbis.vn/open/api/v1/customers?dryRun=1" \
  -H "X-Store-Key: YOUR_STORE_KEY" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{ "name": "Nguyễn Văn A", "phone": "0901234567" }'

Thay YOUR_STORE_KEY, YOUR_API_KEY, YOUR_SECRET_KEY bằng khoá của đơn vị bạn.

4. Phạm vi quyền của khoá

Khoá API của đơn vị có quyền như quản trị đơn vị: đọc được toàn bộ dữ liệu của đơn vị qua các API đã mở.
Bản ghi tạo, sửa qua API ghi người thao tác là API KEY.
Khoá của đơn vị nào chỉ đọc, ghi được dữ liệu của đơn vị đó.

5. Lỗi xác thực

HTTP	code	Khi nào	Cách xử lý
401	`UNAUTHORIZED`	Thiếu khoá hoặc khoá sai	Kiểm tra đủ 3 header và giá trị khoá
403	`API_DISABLED`	Đơn vị chưa bật kết nối API	Bật ở Cấu hình phần mềm → API tích hợp QBIS hoặc gửi yêu cầu QBIS
429	`RATE_LIMITED`	Quá 60 request/phút với một khoá	Chờ đúng số giây trong header `Retry-After` rồi gửi lại

Body lỗi luôn có dạng { "status": 401, "success": false, "code": "UNAUTHORIZED", "message": "…", "data": null }.

6. Giữ khoá an toàn

Chỉ gọi API từ máy chủ của bạn; không nhúng khoá vào app di động, website phía người dùng cuối.
Không đặt khoá trên URL; luôn gửi qua header.
Không gửi khoá qua chat, email; người cần dùng tự lấy trong phần mềm.
Nghi khoá bị lộ: báo ngay QBIS để đổi khoá, rồi cập nhật khoá mới vào hệ thống của bạn.
Mọi request đều được QBIS ghi nhật ký (thời gian, khoá, bản ghi) để đối chiếu khi cần.