Mô hình tích hợp dữ liệu với QBIS

QBIS Open API là cổng HTTPS + JSON để hệ thống của bạn đọc và ghi dữ liệu trực tiếp vào phần mềm QBIS của doanh nghiệp. Mọi API dùng chung một kiểu gọi, một cách xác thực và một dạng phản hồi — nắm một API là dùng được tất cả.

1. Kiến trúc tổng quan

Hệ thống của bạnWebsite, app, POS, CRM, tổng đài, sàn TMĐT, phần mềm kế toán…

HTTPS · JSON
3 khoá trong header

Cổng QBIS Open APIKiểm khoá, giới hạn tốc độ, kiểm dữ liệu, ghi nhật ký mọi request

Biểu mẫu
nghiệp vụ

Phần mềm QBIS của đơn vịKhách hàng, đơn hàng, phiếu yêu cầu, sản phẩm…

Cổng không ghi thẳng vào cơ sở dữ liệu. Mỗi lệnh tạo hoặc sửa đi qua đúng biểu mẫu trong phần mềm, nên mã tự sinh, giá trị mặc định, kiểm tra trường bắt buộc và liên kết giữa các phiếu chạy y như khi nhân viên nhập tay. Bản ghi tạo qua API ghi người tạo là API KEY của đơn vị để dễ đối chiếu.

2. Tài nguyên và thao tác

Mỗi API là một tài nguyên có tên ngắn (alias) như customers, orders, tickets, gắn với một biểu mẫu trong QBIS. Mọi tài nguyên dùng chung bộ thao tác dưới đây; API nào bật thao tác nào thì xem ở trang của API đó.

Thao tác	Gọi	Dùng khi
Tạo	`POST /{alias}`	Đẩy bản ghi mới vào QBIS, kèm dòng con nếu có
Xem	`GET /{alias}/{khoá}`	Tra một bản ghi theo khoá, trả kèm các lưới con
Sửa	`PUT /{alias}/{khoá}`	Cập nhật các trường được phép sửa
Danh sách	`GET /{alias}?updatedSince=…&page=1&size=50`	Lấy các bản ghi mới đổi để đồng bộ: trả `data.records[]` và `hasMore`, tối đa 200 bản ghi mỗi trang
Lưới con	`GET /{alias}/{khoá}/{con}`	Đọc dòng con, ví dụ các phiếu yêu cầu của một đơn hàng
Định nghĩa	`GET /_schema/{alias}`	Lấy danh sách trường và mã danh mục mới nhất của đơn vị bạn
OpenAPI	`GET /_openapi`	Nạp toàn bộ API vào Postman, Swagger

Đường dẫn đầy đủ = Base URL + đường trên, ví dụ https://db.qbis.vn/open/api/v1/customers/0901234567.

3. Khoá bản ghi và gọi lại an toàn

Mỗi tài nguyên có một khoá để tìm bản ghi: khách hàng tìm theo số điện thoại, đơn hàng theo mã đơn, phiếu yêu cầu theo mã phiếu… Khoá của từng API ghi ở trang API đó.

API có khoá do bạn gửi: khi tạo luôn gửi kèm khoá của bạn (ví dụ mã đơn trong hệ thống của bạn). Mất kết nối giữa chừng thì gửi lại y nguyên — cùng khoá là cùng một bản ghi, không tạo trùng.
Khoá đã có thì QBIS xử lý theo cấu hình của API: trả lại bản ghi đã có, từ chối (409 DUPLICATE), hoặc cập nhật bản ghi đó.
API mà khoá do QBIS cấp: tra lại bằng GET trước khi gửi lại.
Tạo mới thành công trả HTTP 201 kèm bản ghi vừa tạo (trường QBIS tự cấp đã có giá trị).

Bảng chống trùng của từng API: mục Chống trùng và gọi lại an toàn ở trang Giới thiệu QBIS Open API.

4. Dữ liệu cha – con trong một lần gọi

Nghiệp vụ nhiều tầng gửi trong một request. Ví dụ đơn hàng dịch vụ: thông tin đơn, khách hàng, các phiếu yêu cầu (mỗi thiết bị một phiếu) và các dòng sản phẩm bán đi cùng nhau; QBIS lưu đơn rồi gắn từng dòng con vào đúng đơn đó. Khách hàng tra theo số điện thoại, chưa có thì tự tạo.

Dòng con thuộc về bản ghi cha nên tạo qua bản ghi cha: tạo lẻ một dòng con bằng POST /{alias-con} sẽ bị từ chối (HTTP 405). Đọc lại bằng GET đơn hàng sẽ trả kèm các lưới con; cần riêng một lưới thì gọi GET /{alias}/{khoá}/{con}.

5. Đồng bộ hai chiều

Chiều	Cách làm
Hệ thống của bạn → QBIS	Gọi `POST` / `PUT` ngay khi dữ liệu phát sinh ở phía bạn (đơn mới, khách mới, đổi thông tin…).
QBIS → hệ thống của bạn	Định kỳ gọi danh sách với `updatedSince` = thời điểm bắt đầu lần đồng bộ trước (hoặc `createdSince` để lấy bản ghi mới tạo), phân trang `page` / `size` đến khi `hasMore = false`; giá trị ngày giờ trên URL phải URL-encode. Hoặc tra một bản ghi theo khoá, không quá 1 lần/phút cho mỗi bản ghi.
QBIS chủ động báo khi có sự kiện	Dùng Tự động hoá của QBIS dựng theo kịch bản — xem Câu hỏi thường gặp.

6. Gọi thử trước khi chạy thật

QBIS không có môi trường thử riêng — mọi lệnh gọi chạy trên dữ liệu thật của đơn vị; lệnh GET chỉ đọc nên gọi thử thoải mái. Thêm ?dryRun=1 vào lệnh POST hoặc PUT: QBIS kiểm tra khoá, trường bắt buộc, định dạng, mã danh mục, tra khách hàng, sản phẩm và trùng khoá rồi trả về bản ghi sẽ ghi (đã chuẩn hoá) — không ghi gì. Khi kết quả đúng như mong muốn, bỏ dryRun để chạy thật; cần thử ghi thật thì thống nhất với đơn vị một mã thử (ví dụ bắt đầu bằng TEST-) để huỷ sau.

7. Định dạng dữ liệu và phản hồi

Ngày dd/MM/yyyy, ngày giờ dd/MM/yyyy HH:mm theo giờ Việt Nam (GMT+7); khi gửi lên nhận thêm ISO 8601.
Số là số JSON thường (350000, 4.5), không dấu phân cách nghìn. Số điện thoại tự chuẩn hoá về dạng 0xxxxxxxxx.
Trường danh mục (trạng thái, loại yêu cầu…) gửi theo mã; mỗi đơn vị một bộ mã — lấy bằng GET /_schema/{alias}.
Mỗi khoá tối đa 60 request/phút (vượt → HTTP 429 kèm Retry-After); body tối đa 512 KB, 50 dòng mỗi lưới con trong một request.

Mọi phản hồi cùng một vỏ JSON, status trùng HTTP status:

{
  "status": 200,
  "success": true,
  "code": "OK",
  "message": "",
  "data": { }
}

Khi lỗi, success là false, data là null, code là mã lỗi và message nêu lý do — bảng mã lỗi ở trang Giới thiệu QBIS Open API. Lệnh tạo có thể kèm warnings[] — điều không chặn việc ghi (trường đã bỏ qua, danh mục không khớp…), nên ghi log để rà. Mọi request đều được QBIS ghi nhật ký (thời gian, khoá, bản ghi) để đối chiếu khi cần.

8. Các bước triển khai

Gửi yêu cầu để QBIS bật kết nối API cho đơn vị, lấy 3 khoá — xem Thông tin xác thực dùng cho API.
Chọn các API cần dùng ở menu bên trái; gọi GET /_schema/{alias} để lấy mã danh mục của đơn vị.
Gọi thử với ?dryRun=1 đến khi dữ liệu trả về đúng.
Chạy thật với một bản ghi, kiểm tra trên phần mềm QBIS rồi mới bật cho toàn bộ.
Theo dõi lỗi trả về (code, message); cần hỗ trợ thì gửi QBIS thời điểm gọi và khoá bản ghi.