Khách hàng — QBIS Open API

Khách hàng của trung tâm. Đơn hàng tìm khách theo số điện thoại, chưa có thì tạo mới.

Thao tác và endpoint

Thao tác	Endpoint
Tạo	POST `/customers`
Xem một	GET `/customers/{phone}`
Định nghĩa trường	GET `/_schema/customers`

Khoá tra cứu: phone — Số điện thoại (vd 0901234567). Số điện thoại tự chuẩn hoá (mục 3.5). Chống trùng khi tạo: Gửi phone: gọi lại cùng phone → HTTP 200 kèm bản ghi đã có, không tạo trùng.

Trường dữ liệu

Trường	Kiểu	Bắt buộc	Chỉ đọc	Mô tả
`code`	chuỗi	—	có	Mã khách hàng
`name`	chuỗi	có		Tên khách hàng
`email`	chuỗi	không		Email
`phone`	chuỗi	không		Số điện thoại. Khoá tra cứu (vd `0901234567`). Tự chuẩn hoá về `0xxxxxxxxx` (mục 3.5)
`address`	chuỗi dài	không		Địa chỉ

Ví dụ tạo

curl -X POST https://db.qbis.vn/open/api/v1/customers \
  -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 '{
  "name": "Nguyễn Văn An",
  "email": "an.nguyen@example.com",
  "phone": "0901234567",
  "address": "12 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM"
}'

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.

{
  "status": 201,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "code": "KH000123",
    "name": "Nguyễn Văn An",
    "email": "an.nguyen@example.com",
    "phone": "0901234567",
    "address": "12 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM",
    "warnings": []
  }
}

Ví dụ tra cứu

curl https://db.qbis.vn/open/api/v1/customers/0901234567 \
  -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": {
    "code": "KH000123",
    "name": "Nguyễn Văn An",
    "email": "an.nguyen@example.com",
    "phone": "0901234567",
    "address": "12 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM"
  }
}