Phiếu yêu cầu — QBIS Open API

Phiếu yêu cầu sửa chữa / bảo hành của đơn hàng (mỗi thiết bị một phiếu). Dùng để tra cứu tiến độ xử lý.

Thao tác và endpoint

Thao tác	Endpoint
Tạo cùng đơn hàng dịch vụ	Gửi mảng `tickets[]` trong `POST /orders`
Thêm vào đơn hàng dịch vụ đã có	POST `/orders/{code}/tickets`
Xem một	GET `/tickets/{code}`
Danh sách	GET `/tickets?updatedSince=…&page=1&size=50`
Định nghĩa trường	GET `/_schema/tickets`

Khoá tra cứu: code — Số phiếu, do QBIS cấp (vd Y261105002). Tạo: là dòng con của orders — không tạo lẻ bằng POST /tickets (trả 405); xem mục 3.6.

Trường dữ liệu

Trường	Kiểu	Bắt buộc	Chỉ đọc	Lọc	Mô tả
`code`	chuỗi	—	có	có	Số phiếu. Khoá tra cứu, do QBIS cấp (vd `Y261105002`)
`diagnosis`	chuỗi dài	—	có	có	Chi tiết chẩn đoán
`productName`	chuỗi	không		có	Thiết bị nhận
`solution`	chuỗi dài	—	có	có	Phương án sửa chữa
`returnStatus`	mã danh mục	—	có	có	Trạng thái trả máy. Gửi `code`, trả về `{code, name}` — mã ở mục 5.1.2
`returnDate`	ngày giờ `dd/MM/yyyy HH:mm`	—	có	có	Ngày trả
`imei`	chuỗi	không		có	Số IMEI (15 chữ số) — máy có IMEI: điện thoại, máy tính bảng
`serial`	chuỗi	không		có	Số serial (S/N) in trên tem máy; máy không có S/N thì gửi IMEI
`condition`	chuỗi dài	không		có	Tình trạng khi nhận
`issue`	chuỗi dài	không		có	Ghi chú khi nhận
`requestType`	mã danh mục	không		có	Loại yêu cầu. Gửi `code`, trả về `{code, name}` — mã ở mục 5.1.2
`status`	mã danh mục	—	có	có	Trạng thái. Gửi `code`, trả về `{code, name}` — mã ở mục 5.1.2
`station`	chuỗi	—	có	có	Gắn trạm xử lý
`technician`	chuỗi	—	có	có	Kỹ thuật
`dueDate`	ngày giờ `dd/MM/yyyy HH:mm`	không		có	Thời gian hẹn
`completedDate`	ngày giờ `dd/MM/yyyy HH:mm`	—	có	có	Ngày hoàn thành
`total`	số	—	có	có	Tổng tiền phiếu
`value`	số	—	có	có	Giá trị phiếu
`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)

Mã danh mục

returnStatus — Trạng thái trả máy (QBIS cập nhật theo tiến độ)

code	name
`0`	Chưa tạo phiếu trả
`1`	Đã tạo phiếu trả

requestType — Loại yêu cầu

status — Trạng thái (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/tickets (thuộc tính values của trường).

Ví dụ thêm vào đơn hàng dịch vụ đã có

curl -X POST https://db.qbis.vn/open/api/v1/orders/PO-2026-000123/tickets \
  -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 '{
  "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"
}'

HTTP 201 kèm dòng vừa thêm. Không có khoá chống trùng — gọi lại sẽ thêm dòng nữa; mất kết nối thì GET /orders/{code}/tickets kiểm tra trước khi gửi lại. Tạo cùng lúc với orders: gửi trong mảng tickets[] (xem ví dụ của orders).

{
  "status": 201,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "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/tickets/Y261105002 \
  -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. Không có → 404 NOT_FOUND. Ví dụ dưới là phiếu đang xử lý: đã có chẩn đoán, kỹ thuật; chưa có ngày hoàn thành / ngày trả.

{
  "status": 200,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "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/tickets?updatedSince=05%2F11%2F2026%2008%3A00&status=InProgress&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, diagnosis, productName, solution, returnStatus, returnDate, imei, serial, condition, issue, requestType, status, station, technician, dueDate, completedDate, total, value.