Những câu doanh nghiệp hay hỏi QBIS trước khi nối phần mềm của mình — CRM, website bán hàng, tổng đài, phần mềm kế toán… — với QBIS.
QBIS có API chính thức để tìm khách theo số điện thoại và tạo khách mới không?
Có. Dùng API Khách hàng (customers):
- Tìm khách theo số điện thoại:
GET /customers/{số điện thoại}— số điện thoại là khoá tra cứu khách hàng. - Tạo khách mới:
POST /customersvới tên, số điện thoại, địa chỉ, email… - Gửi đơn hàng bằng
POST /orderskèm số điện thoại khách: khách chưa có thì QBIS tự tạo, không cần gọi hai lần.
Trường riêng của doanh nghiệp như biển số xe, nguồn khách, nhân viên sale, chi nhánh: QBIS cấu hình thêm vào API theo biểu mẫu khách hàng của đơn vị bạn — gửi danh sách trường cần dùng cho QBIS. Dữ liệu luôn ghi vào đúng đơn vị sở hữu khoá API.
Tài liệu từng API nằm ở menu bên trái; cách bật kết nối và lấy khoá xem bài Thông tin xác thực dùng cho API.
Webhook trong Tự động hoá gửi được những sự kiện nào? Nội dung gửi có những trường gì?
QBIS tách hai chiều:
- Webhook dùng để nhận sự kiện từ hệ thống bên ngoài gửi vào QBIS.
- Tự động hoá (automation) dùng để QBIS gửi sự kiện ra hệ thống của bạn, ví dụ khi tạo phiếu dịch vụ, đổi trạng thái phiếu, lập phiếu thu, huỷ phiếu.
Nội dung gửi đi do kịch bản quyết định — có thể gồm số điện thoại khách, mã phiếu, tổng tiền, số đã thu, nhân viên phụ trách… Bạn mô tả kịch bản (sự kiện nào, cần những trường gì, gửi tới địa chỉ nào) rồi gửi QBIS xem để dựng.
Ai bật Webhook, Tự động hoá cho đơn vị? Có mất phí không?
QBIS xem kịch bản của từng đơn vị rồi mới tính phí dựng; kịch bản đơn giản có thể không mất phí. Khi webhook, tự động hoá đã dựng xong đúng kịch bản, quản trị của đơn vị tự vào phần mềm bật hoặc tắt, không cần chờ QBIS.
API có giới hạn số lần gọi không?
Không giới hạn tổng số lần gọi theo ngày hay theo tháng. Để bảo vệ hệ thống, mỗi khoá API gọi tối đa 60 request/phút; vượt mức sẽ nhận HTTP 429 RATE_LIMITED kèm header Retry-After — chờ đúng số giây đó rồi gửi lại.
- Tra trạng thái một bản ghi không quá 1 lần/phút.
- Cần đồng bộ nhiều bản ghi: gọi danh sách với
updatedSince(mỗi trang tối đa 200 bản ghi) để chỉ lấy bản ghi mới đổi, thay vì tra lần lượt từng bản ghi.
Có môi trường thử (sandbox) riêng không?
Khô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 đầy đủ — trường bắt buộc, định dạng, mã danh mục, tra khách hàng, sản phẩm, trùng khoá — nhưng không ghi gì. Khi cần thử ghi thật, thống nhất trước với đơn vị một mã thử (ví dụ khoá bắt đầu bằng TEST-) để đơn vị huỷ sau khi kiểm tra.
Mất kết nối giữa chừng, gọi lại có bị tạo trùng không?
Với API có khoá do bạn gửi (ví dụ mã đơn trong hệ thống của bạn): không. Cùng khoá thì QBIS hiểu là cùng một bản ghi và xử lý theo cấu hình của API — trả lại bản ghi đã có, từ chối với 409 DUPLICATE, hoặc cập nhật bản ghi đó.
Với API mà khoá do QBIS cấp, hãy tra lại bằng GET trước khi gửi lại. Dòng con (phiếu yêu cầu, sản phẩm bán của một đơn) nên gửi kèm trong cùng một lần tạo bản ghi cha. Bảng chống trùng của từng API nằm ở trang Giới thiệu QBIS Open API.