Sản phẩm bán — QBIS Open API

Dòng sản phẩm / dịch vụ bán trong đơn hàng (thiết bị bán kèm, linh kiện). Gửi kèm trong items[] khi tạo đơn.

Thao tác và endpoint

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

Khoá tra cứu: id — ID bản ghi do QBIS cấp (vd 8812345). Tạo: là dòng con của orders — không tạo lẻ bằng POST /items (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ả
`product`	chuỗi	có		có	Sản phẩm, dịch vụ. Gửi `code` của `products`, vd `SP001`. Trả về `{code, name}`
`quantity`	số	có		có	Số lượng
`price`	số	không		có	Đơn giá
`discount`	số	không		có	Giảm giá
`amount`	số	không		có	Thành tiền
`note`	chuỗi dài	không		có	Ghi chú
`serial`	chuỗi dài	không		có	IMEI / Serial
`warrantyMonths`	số	không		có	Thời gian bảo hành
`id`	chuỗi	—	có		ID bản ghi do QBIS cấp. Khoá tra cứu (vd `8812345`)

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/items \
  -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 '{
  "product": "SP001",
  "quantity": 2,
  "price": 150000,
  "discount": 0,
  "amount": 300000,
  "note": "Dán tại cửa hàng",
  "serial": "R5CX12ABC3D",
  "warrantyMonths": 12
}'

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}/items kiểm tra trước khi gửi lại. Tạo cùng lúc với orders: gửi trong mảng items[] (xem ví dụ của orders).

{
  "status": 201,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "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",
    "warnings": []
  }
}

Ví dụ tra cứu

curl https://db.qbis.vn/open/api/v1/items/8812345 \
  -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.

{
  "status": 200,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "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"
  }
}

Ví dụ danh sách

curl "https://db.qbis.vn/open/api/v1/items?updatedSince=05%2F11%2F2026%2008%3A00&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: product, quantity, price, discount, amount, note, serial, warrantyMonths.