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ên | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
x-api-key | header | string | Bắt buộc | Api key do QuestLab cấp. Chỉ gửi từ backend có địa chỉ IP đã đăng ký. |
transactionId | header | string | Bắt buộc | Khoá đối soát do bạn đặt, mỗi lượt gọi một mã. |
X-Partner-Code | header | string | Tuỳ chọn | Mã đối tác để đối chiếu. Lệch với api-key thì nhận 403 (2013). |
Content-Type | header | string | Bắt buộc | application/json |
deviceId | body | string | Bắt buộc | Mã 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:imagecho ảnh,text/html/pdfcho tài liệu,audiocho â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ểu | Mô tả |
|---|---|---|
partnerCode | string | Mã đối tác suy ra từ api-key. |
deviceId | string | Thiết bị đã gửi. |
questlabUserId | UUID | Người dùng QuestLab tạo tự động cho thiết bị, ổn định qua các lần gọi. |
transactionId | string | Giá trị header đã gửi. |
assigned | boolean | Luôn là true khi có data. |
assignedTaskId | UUID | Mã lượt làm việc, dùng khi nộp bài và mở lại nhiệm vụ. |
taskUuid | UUID | Mã nhiệm vụ, để đối soát. |
projectUuid | UUID | Dự án chứa nhiệm vụ. |
expiredAt | datetime | Hạn giữ nhiệm vụ. |
task.data | object | Nội dung hiển thị; media là signed URL. |
task.annotations | array | Bài đã nộp của thiết bị này. |
task.assignedTasks | array | Trạng thái lượt làm việc. |
message | string | Thô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ĩa | Cách xử lý |
|---|---|---|
HTTP 401 | x-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. |
2013 | X-Partner-Code không khớp api-key. | Sửa hoặc bỏ header. |
2021 | Thiếu header transactionId. | Bổ sung header. |
2025 | Hế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 400 | deviceId rỗng. | Bổ sung deviceId. |
