Đơn hàng dịch vụ gửi từ đối tác: khách hàng (tìm theo số điện thoại, chưa có thì tạo), các phiếu yêu cầu tickets[] (mỗi thiết bị một phiếu) và sản phẩm bán items[]. Gửi lại cùng code sẽ nhận lại đơn cũ.
Thao tác và endpoint
| Thao tác | Endpoint |
|---|---|
| Tạo | POST /orders |
| Xem một | GET /orders/{code} |
| Danh sách | GET /orders?updatedSince=…&page=1&size=50 |
| Danh sách items của một đơn hàng dịch vụ | GET /orders/{code}/items |
| Thêm items vào đơn hàng dịch vụ đã có | POST /orders/{code}/items |
| Danh sách tickets của một đơn hàng dịch vụ | GET /orders/{code}/tickets |
| Thêm tickets vào đơn hàng dịch vụ đã có | POST /orders/{code}/tickets |
| Định nghĩa trường | GET /_schema/orders |
Khoá tra cứu: code — Mã đơn hàng (vd PO-2026-000123). Chống trùng khi tạo: Gửi code: gọi lại cùng code → HTTP 200 kèm bản ghi đã có, không tạo trùng (dòng con gửi kèm không được thêm lần nữa).
Trường dữ liệu
| Trường | Kiểu | Bắt buộc | Chỉ đọc | Lọc | Mô tả |
|---|---|---|---|---|---|
code | chuỗi | không | có | Mã đơn hàng. Khoá tra cứu (vd PO-2026-000123) | |
customer | chuỗi / object | có | có | Thông tin khách hàng. Gửi phone của customers, vd 0901234567; chưa có thì gửi object (vd {"phone": "…", "name": "…"}) để QBIS tạo mới. Trả về {code, name} | |
note | chuỗi | không | có | Ghi chú đơn hàng | |
status | mã danh mục | — | có | có | Trạng thái đơn hàng. Gửi code, trả về {code, name} — mã ở mục 5.3.2 |
total | số | — | có | có | Tổng tiền |
paid | số | — | có | có | Đã thanh toán |
debt | số | — | có | Còn nợ | |
createdDate | ngày giờ dd/MM/yyyy HH:mm | — | có | Thời điểm tạo bản ghi trên QBIS | |
updatedDate | ngày giờ dd/MM/yyyy HH:mm | — | có | Thời điểm cập nhật gần nhất (mốc so với updatedSince) (mục 3.3) | |
items[] | mảng | không | Gửi kèm khi tạo (tối đa 50 dòng); trả về khi xem một, đọc riêng bằng GET /orders/{code}/items, thêm vào bản ghi đã có bằng POST …/items. Trường: xem items | ||
tickets[] | mảng | không | Gửi kèm khi tạo (tối đa 50 dòng); trả về khi xem một, đọc riêng bằng GET /orders/{code}/tickets, thêm vào bản ghi đã có bằng POST …/tickets. Trường: xem tickets |
Mã danh mục
status — Trạng thái đơn hàng (QBIS cập nhật theo tiến độ)
Bảng trên là mã mặc định của QBIS. Đơn vị có thể ẩn / thêm mã, và trường lấy từ danh mục riêng của đơn vị không in ở đây — danh sách đúng của đơn vị bạn:
GET /_schema/orders (thuộc tính values của trường).Ví dụ tạo
curl -X POST https://db.qbis.vn/open/api/v1/orders \
-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 '{
"code": "PO-2026-000123",
"customer": {
"name": "Nguyễn Văn An",
"phone": "0901234567",
"address": "12 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM"
},
"note": "Khách hẹn nhận máy buổi chiều",
"items": [
{
"product": "SP001",
"quantity": 2,
"price": 150000,
"discount": 0,
"amount": 300000,
"note": "Dán tại cửa hàng",
"serial": "R5CX12ABC3D",
"warrantyMonths": 12
}
],
"tickets": [
{
"productName": "Điện thoại Samsung Galaxy A55",
"imei": "356789012345678",
"serial": "R5CX12ABC3D",
"condition": "Trầy nhẹ cạnh viền, không kèm sạc",
"issue": "Không lên nguồn, sạc không vào",
"requestType": "Repair",
"dueDate": "08/11/2026 17:00"
}
]
}'Tạo mới: HTTP 201 kèm bản ghi vừa tạo (trường QBIS tự cấp đã có giá trị). Khoá đã có: HTTP 200 kèm bản ghi đã có, không tạo trùng (dòng con gửi kèm không được thêm lần nữa).
{
"status": 201,
"success": true,
"code": "OK",
"message": "",
"data": {
"code": "PO-2026-000123",
"customer": {
"code": "0901234567",
"name": "Nguyễn Văn An"
},
"note": "Khách hẹn nhận máy buổi chiều",
"status": {
"code": "new",
"name": "Chưa thanh toán"
},
"total": 300000,
"paid": 0,
"debt": 300000,
"createdDate": "05/11/2026 09:15",
"updatedDate": "05/11/2026 09:15",
"items": [
{
"product": {
"code": "SP001",
"name": "Kính cường lực Galaxy A55"
},
"quantity": 2,
"price": 150000,
"discount": 0,
"amount": 300000,
"note": "Dán tại cửa hàng",
"serial": "R5CX12ABC3D",
"warrantyMonths": 12,
"id": "8812345"
}
],
"tickets": [
{
"code": "Y261105002",
"diagnosis": "",
"productName": "Điện thoại Samsung Galaxy A55",
"solution": "",
"returnStatus": {
"code": "0",
"name": "Chưa tạo phiếu trả"
},
"returnDate": "",
"imei": "356789012345678",
"serial": "R5CX12ABC3D",
"condition": "Trầy nhẹ cạnh viền, không kèm sạc",
"issue": "Không lên nguồn, sạc không vào",
"requestType": {
"code": "Repair",
"name": "Sửa chữa"
},
"status": {
"code": "Pending",
"name": "Mới tiếp nhận"
},
"station": "",
"technician": "",
"dueDate": "08/11/2026 17:00",
"completedDate": "",
"total": 0,
"value": 0,
"createdDate": "05/11/2026 09:15",
"updatedDate": "05/11/2026 09:15"
}
],
"warnings": []
}
}Ví dụ tra cứu
curl https://db.qbis.vn/open/api/v1/orders/PO-2026-000123 \
-H "X-Store-Key: YOUR_STORE_KEY" -H "X-Api-Key: YOUR_API_KEY" -H "X-Secret-Key: YOUR_SECRET_KEY"HTTP 200, data là bản ghi kèm items[], tickets[]. Không có → 404 NOT_FOUND.
{
"status": 200,
"success": true,
"code": "OK",
"message": "",
"data": {
"code": "PO-2026-000123",
"customer": {
"code": "0901234567",
"name": "Nguyễn Văn An"
},
"note": "Khách hẹn nhận máy buổi chiều",
"status": {
"code": "cancel",
"name": "Hủy bỏ"
},
"total": 300000,
"paid": 0,
"debt": 300000,
"createdDate": "05/11/2026 09:15",
"updatedDate": "06/11/2026 14:30",
"items": [
{
"product": {
"code": "SP001",
"name": "Kính cường lực Galaxy A55"
},
"quantity": 2,
"price": 150000,
"discount": 0,
"amount": 300000,
"note": "Dán tại cửa hàng",
"serial": "R5CX12ABC3D",
"warrantyMonths": 12,
"id": "8812345"
}
],
"tickets": [
{
"code": "Y261105002",
"diagnosis": "Hỏng IC nguồn",
"productName": "Điện thoại Samsung Galaxy A55",
"solution": "Thay IC nguồn",
"returnStatus": {
"code": "0",
"name": "Chưa tạo phiếu trả"
},
"returnDate": "",
"imei": "356789012345678",
"serial": "R5CX12ABC3D",
"condition": "Trầy nhẹ cạnh viền, không kèm sạc",
"issue": "Không lên nguồn, sạc không vào",
"requestType": {
"code": "Repair",
"name": "Sửa chữa"
},
"status": {
"code": "InProgress",
"name": "Đang xử lý"
},
"station": "Trạm kỹ thuật trung tâm",
"technician": "Trần Văn Bình",
"dueDate": "08/11/2026 17:00",
"completedDate": "",
"total": 850000,
"value": 850000,
"createdDate": "05/11/2026 09:15",
"updatedDate": "06/11/2026 14:30"
}
]
}
}Ví dụ danh sách
curl "https://db.qbis.vn/open/api/v1/orders?updatedSince=05%2F11%2F2026%2008%3A00&status=cancel&page=1&size=50" \
-H "X-Store-Key: YOUR_STORE_KEY" -H "X-Api-Key: YOUR_API_KEY" -H "X-Secret-Key: YOUR_SECRET_KEY"Trả data.records[] (mỗi phần tử như data ở ví dụ tra cứu, không kèm dòng con), page, size, count, hasMore — mục 3.3. Lọc đúng bằng theo: code, customer, note, status, total, paid.