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ênVị tríKiểuBắt buộcMô tả
tokenheaderstringBắt buộcaccessToken của người dùng. Không dùng Authorization: Bearer.
Accept-LanguageheaderstringTuỳ chọnvi để 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 serverTime và remainingSeconds, không theo đồng hồ thiết bị.
  • data = null khô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ểuMô tả
assignedTaskIdUUIDMã lượt làm việc, dùng khi nộp bài. Mỗi lần nhận sinh mã mới.
taskUuidUUIDMã nhiệm vụ, dùng để đọc nội dung.
projectUuidUUIDDự án chứa nhiệm vụ.
statusstringLuôn là PENDING ngay sau khi nhận.
assignedAtdatetimeThời điểm giao.
expiredAtdatetimeHạn giữ nhiệm vụ; quá hạn thì bị thu hồi.
serverTimedatetimeGiờ server, để bù lệch đồng hồ.
remainingSecondsnumberSố 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ốngerrorCodeGợi ý xử lý
Hồ sơ chưa khớp dự án nàoKhông cóMời người dùng bổ sung hồ sơ
Hết nhiệm vụ trong các dự án phù hợpKhô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ào1024Chuyển sang luồng bài kiểm tra
Đang giữ tối đa số nhiệm vụ cùng lúcKhông cóMở lại nhiệm vụ đang làm dở
Luồng bài kiểm tra đầu vào

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ồi
CANCELLED
Đã huỷ

Mã lỗi

MãÝ nghĩaCách xử lý
httpCode 401Header 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.
Cấu trúc response và lỗi dùng chung