Lead (khách hàng tiềm năng)

Lead gửi từ đối tác (website, landing page, quảng cáo…): thông tin liên hệ theo cột của tệp lead và nguồn lead; tra cứu tiến độ chăm sóc: trạng thái, sale phụ trách, lịch hẹn, đã chốt / lost. Mã lead do QBIS cấp; QBIS tự nhận lead trùng theo cột duy nhất của tệp.

Thao tác và endpoint

Khoá tra cứu: code — Mã lead do QBIS cấp (vd 000123). Chống trùng khi tạo: Không có khoá chống trùng (khoá do QBIS cấp): mỗi lần gọi tạo một bản ghi mới.

Trường dữ liệu

Mã danh mục

source — Nguồn lead

utmCampaign — UTM Campaign (QBIS cập nhật theo tiến độ)

status — Trạng thái (QBIS cập nhật theo tiến độ)

noAnswerStatus — Trạng thái không nghe máy (QBIS cập nhật theo tiến độ)

appointmentStatus — Trạng thái hẹn (QBIS cập nhật theo tiến độ)

Ví dụ tạo

curl -X POST https://db.qbis.vn/open/api/v1/leads \
  -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 '{
  "contact": {
    "name": "Nguyễn Văn An",
    "phone": "0901234567",
    "email": "an.nguyen@example.com"
  },
  "leadFile": "Lead website tháng 11/2026",
  "source": "Lead web",
  "value": 300000
}'

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ó: không áp dụng (khoá do QBIS cấp).

{
  "status": 201,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "code": "000123",
    "contact": {
      "name": "Nguyễn Văn An",
      "phone": "0901234567",
      "email": "an.nguyen@example.com"
    },
    "leadFile": {
      "code": "Lead website tháng 11/2026",
      "name": "Lead website tháng 11/2026"
    },
    "source": {
      "code": "Lead web",
      "name": "Lead web"
    },
    "utmCampaign": null,
    "value": 300000,
    "status": {
      "code": "Đăng ký",
      "name": "Đăng ký"
    },
    "salesperson": "",
    "noAnswerStatus": null,
    "appointmentStatus": null,
    "appointmentDate": "",
    "appointmentTime": "",
    "closed": false,
    "lost": false,
    "lostReason": "",
    "convertedDeal": "",
    "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/leads/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. Không có → 404 NOT_FOUND.

{
  "status": 200,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "code": "000123",
    "contact": {
      "name": "Nguyễn Văn An",
      "phone": "0901234567",
      "email": "an.nguyen@example.com"
    },
    "leadFile": {
      "code": "Lead website tháng 11/2026",
      "name": "Lead website tháng 11/2026"
    },
    "source": {
      "code": "Lead web",
      "name": "Lead web"
    },
    "utmCampaign": null,
    "value": 300000,
    "status": {
      "code": "Kích hoạt tài khoản",
      "name": "Kích hoạt tài khoản"
    },
    "salesperson": "Trần Văn Bình",
    "noAnswerStatus": null,
    "appointmentStatus": null,
    "appointmentDate": "",
    "appointmentTime": "",
    "closed": false,
    "lost": false,
    "lostReason": "",
    "convertedDeal": "",
    "createdDate": "05/11/2026 09:15",
    "updatedDate": "06/11/2026 14:30"
  }
}

Ví dụ sửa

curl -X PUT https://db.qbis.vn/open/api/v1/leads/000123 \
  -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 '{
  "contact": {
    "email": "an.nguyen@congty.vn"
  },
  "value": 500000
}'

• Chỉ gửi trường cần đổi; trường không gửi giữ nguyên; gửi null để xoá giá trị trường (trừ trường bắt buộc). Trường chỉ đọc gửi lên bị bỏ qua.
• Cột động (contact): chỉ các cột gửi lên thay đổi, cột khác giữ nguyên; gửi "" cho một cột để xoá giá trị cột đó.
• Thành công: HTTP 200 kèm bản ghi sau khi sửa (như ví dụ tra cứu) và warnings. Không có → 404. Thêm ?dryRun=1 để thử mà không ghi.

Ví dụ xoá

curl -X DELETE https://db.qbis.vn/open/api/v1/leads/000123 \
  -H "X-Store-Key: YOUR_STORE_KEY" -H "X-Api-Key: YOUR_API_KEY" -H "X-Secret-Key: YOUR_SECRET_KEY"

{
  "status": 200,
  "success": true,
  "code": "OK",
  "message": "",
  "data": {
    "code": "000123",
    "deleted": true
  }
}

Xoá không hoàn tác được qua API. QBIS chạy đúng các bước như khi xoá trên phần mềm (kiểm tra ràng buộc, xoá dữ liệu con, ghi nhật ký với người xoá là khoá API). Bị ràng buộc không cho xoá → 422 SAVE_FAILED kèm lý do. Thêm ?dryRun=1 để kiểm tra mà không xoá.

Ví dụ danh sách

curl "https://db.qbis.vn/open/api/v1/leads?updatedSince=05%2F11%2F2026%2008%3A00&status=Ki%CC%81ch%20hoa%CC%A3t%20ta%CC%80i%20khoa%CC%89n&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, source, utmCampaign, value, status, salesperson, noAnswerStatus, appointmentStatus, appointmentDate, appointmentTime, closed, lost, lostReason, convertedDeal.