Mục lục tài liệu

Kịch bản 2: Khách vãng lai

Nhận nhiệm vụ (guest)

Nhận một lượt làm việc cho thiết bị, kèm luôn nội dung nhiệm vụ. Gọi từ backend của bạn.

POST/questlab/integration/guest/tasks/request
Kịch bản
2: Khách vãng lai
Xác thực
x-api-key + transactionId, gọi từ backend (Xác thực)

Tham số

TênVị tríKiểuBắt buộcMô tả
x-api-keyheaderstringBắt buộcApi key do QuestLab cấp. Chỉ gửi từ backend có địa chỉ IP đã đăng ký.
transactionIdheaderstringBắt buộcKhoá đối soát do bạn đặt, mỗi lượt gọi một mã.
X-Partner-CodeheaderstringTuỳ chọnMã đối tác để đối chiếu. Lệch với api-key thì nhận 403 (2013).
Content-TypeheaderstringBắt buộcapplication/json
deviceIdbodystringBắt buộcMã thiết bị ổn định, tối đa 255 ký tự. Mỗi deviceId mới là một người dùng mới.

Cần chú ý

  • Chỉ nhận nhiệm vụ thuộc dự án đã gán cho tài khoản tích hợp của bạn. Chưa gán dự án nào thì luôn nhận 2025.
  • 2025 (hết nhiệm vụ) là trạng thái bình thường: hiển thị trạng thái trống và cho thử lại.
  • Lưu assignedTaskId để mở lại nhiệm vụ khi ứng dụng khởi động lại.
  • Chọn màn theo khoá có giá trị trong task.data: image cho ảnh, text/html/pdf cho tài liệu, audio cho âm thanh.

Request mẫu

POST /questlab/integration/guest/tasks/request
bash
curl -X POST "$GW/questlab/integration/guest/tasks/request" \
  -H "x-api-key: $API_KEY" \
  -H "transactionId: ACME-GUEST-0001" \
  -H "Content-Type: application/json" \
  -d '{ "deviceId": "8201b4a3396c4ea6" }'

Biến $GW, $API_KEY, $ACCESS_TOKEN được giải thích ở trang Xác thực.

Response

Trường trong `data`KiểuMô tả
partnerCodestringMã đối tác suy ra từ api-key.
deviceIdstringThiết bị đã gửi.
questlabUserIdUUIDNgười dùng QuestLab tạo tự động cho thiết bị, ổn định qua các lần gọi.
transactionIdstringGiá trị header đã gửi.
assignedbooleanLuôn là true khi có data.
assignedTaskIdUUIDMã lượt làm việc, dùng khi nộp bài và mở lại nhiệm vụ.
taskUuidUUIDMã nhiệm vụ, để đối soát.
projectUuidUUIDDự án chứa nhiệm vụ.
expiredAtdatetimeHạn giữ nhiệm vụ.
task.dataobjectNội dung hiển thị; media là signed URL.
task.annotationsarrayBài đã nộp của thiết bị này.
task.assignedTasksarrayTrạng thái lượt làm việc.
messagestringThông điệp hiển thị được.
200 OK
json
{
  "status": true,
  "httpCode": 200,
  "data": {
    "partnerCode": "ACME",
    "deviceId": "8201b4a3396c4ea6",
    "questlabUserId": "15603676-f0ea-4fe9-9d04-cf07901728f0",
    "transactionId": "ACME-GUEST-0001",
    "assigned": true,
    "assignedTaskId": "08119968-6c06-4b7e-88bb-70267cc0771f",
    "taskUuid": "0293ce6b-a126-41f1-be9f-ca561c08ad36",
    "projectUuid": "95812f4f-915e-41f1-be9f-ca561c08ad36",
    "expiredAt": "2026-09-21T07:17:28.446Z",
    "task": {
      "id": "0293ce6b-a126-41f1-be9f-ca561c08ad36",
      "data": { "image": "https://.../questlab/media/...?expires=...&signature=..." },
      "annotations": [],
      "assignedTasks": [
        { "id": "08119968-6c06-4b7e-88bb-70267cc0771f", "status": "PENDING", "expiredAt": "2026-09-21T07:17:28.446Z" }
      ]
    },
    "message": "Task assigned successfully."
  }
}

Mã lỗi

MãÝ nghĩaCách xử lý
HTTP 401x-api-key sai hoặc hết hạn, hoặc IP gọi tới chưa được đăng ký.Kiểm tra cấu hình, không retry. Liên hệ QuestLab nếu cần.
2013X-Partner-Code không khớp api-key.Sửa hoặc bỏ header.
2021Thiếu header transactionId.Bổ sung header.
2025Hết nhiệm vụ trong phạm vi của bạn.Hiển thị trạng thái trống, thử lại sau.
httpCode 400deviceId rỗng.Bổ sung deviceId.
Cấu trúc response và lỗi dùng chung