Mục lục tài liệu
Kịch bản 1: Người dùng định danh
Nhận nhiệm vụ
QuestLab tự chọn nhiệm vụ phù hợp với hồ sơ và phạm vi dự án của người dùng, rồi giữ nhiệm vụ đó cho người dùng đến expiredAt.
POST
/questlab/sdk/v1/assignments/request- Kịch bản
- 1: Người dùng định danh
- Xác thực
- Header
token: {accessToken}(Xác thực)
Tham số
| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
token | header | string | Bắt buộc | accessToken của người dùng. Không dùng Authorization: Bearer. |
Accept-Language | header | string | Tuỳ chọn | vi để nhận message tiếng Việt; giá trị khác trả tiếng Anh. |
Cần chú ý
- Không có body hay query: danh tính lấy từ
token. - Lưu
assignedTaskId(để nộp bài) vàtaskUuid(để đọc nội dung). - Đếm ngược theo
serverTimevàremainingSeconds, không theo đồng hồ thiết bị. data = nullkhông phải lỗi hệ thống. Xem mục Khi không nhận được nhiệm vụ.
Request mẫu
POST /questlab/sdk/v1/assignments/request
bash
curl -X POST "$GW/questlab/sdk/v1/assignments/request" \
-H "token: $ACCESS_TOKEN" \
-H "Accept-Language: vi"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ả |
|---|---|---|
assignedTaskId | UUID | Mã lượt làm việc, dùng khi nộp bài. Mỗi lần nhận sinh mã mới. |
taskUuid | UUID | Mã nhiệm vụ, dùng để đọc nội dung. |
projectUuid | UUID | Dự án chứa nhiệm vụ. |
status | string | Luôn là PENDING ngay sau khi nhận. |
assignedAt | datetime | Thời điểm giao. |
expiredAt | datetime | Hạn giữ nhiệm vụ; quá hạn thì bị thu hồi. |
serverTime | datetime | Giờ server, để bù lệch đồng hồ. |
remainingSeconds | number | Số giây còn lại, đếm ngược từ đây. |
200 OK
json
{
"status": true,
"httpCode": 200,
"message": "Nhận nhiệm vụ thành công.",
"data": {
"assignedTaskId": "08119968-6c06-4b7e-88bb-70267cc0771f",
"taskUuid": "0293ce6b-a126-11f1-be9f-ca561c08ad36",
"projectUuid": "95812f4f-915e-11f1-be9f-ca561c08ad36",
"status": "PENDING",
"assignedAt": "2026-09-14T07:17:28.446Z",
"expiredAt": "2026-09-17T07:17:28.446Z",
"serverTime": "2026-09-14T07:17:28.500Z",
"remainingSeconds": 259199
}
}Khi không nhận được nhiệm vụ
Response có status = true nhưng data = null. Rẽ nhánh theo errorCode và hiển thị message cho người dùng. Không so sánh chuỗi message vì nội dung thay đổi theo ngôn ngữ.
| Tình huống | errorCode | Gợi ý xử lý |
|---|---|---|
| Hồ sơ chưa khớp dự án nào | Không có | Mời người dùng bổ sung hồ sơ |
| Hết nhiệm vụ trong các dự án phù hợp | Không có | Hiển thị trạng thái trống, thử lại sau |
| Chiến dịch yêu cầu bài kiểm tra đầu vào | 1024 | Chuyển sang luồng bài kiểm tra |
| Đang giữ tối đa số nhiệm vụ cùng lúc | Không có | Mở lại nhiệm vụ đang làm dở |
Vòng đời lượt làm việc
Nhiệm vụ hoàn thành khi nhận đủ số bài nộp theo overlap của dự án.
PENDING
Vừa nhận, đang làm
ANNOTATED
Đã nộp bài
EXPIRED
Quá
expiredAt, nhiệm vụ được thu hồiCANCELLED
Đã huỷ
Mã lỗi
| Mã | Ý nghĩa | Cách xử lý |
|---|---|---|
httpCode 401 | Header token thiếu hoặc đã hết hạn. | Làm mới phiên; thất bại thì khởi tạo lại qua backend. |
