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

Kịch bản 1: Người dùng định danh

Khởi tạo người dùng

Tạo (hoặc lấy lại) danh tính QuestLab cho người dùng của bạn và cấp cặp token phiên. Gọi từ backend của bạn, sau đó trả accessToken và refreshToken cho ứng dụng.

POST/questlab/integration/users/init
Kịch bản
1: Người dùng định danh
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
sourceTypebodystringBắt buộcSDK_INTEGRATION, THIRD_PARTY_APP hoặc PARTNER_APP.
externalUserIdbodystringBắt buộcMã người dùng phía bạn. Mỗi người dùng một mã, giữ cố định.
deviceIdbodystringTuỳ chọnMã thiết bị. Gửi rỗng thì giữ giá trị cũ.
name, email, phonebodystringTuỳ chọnThông tin liên hệ, chỉ dùng ở lần khởi tạo đầu tiên.
gender, occupation, university, operatingArea, skillbodystringTuỳ chọnHồ sơ dùng để ghép dự án, chỉ có tác dụng ở lần khởi tạo đầu tiên. Giá trị hợp lệ của occupation, skill lấy từ GET /auth/user/annotator-info/occupations và /skills.
facebookUrl, zaloPhone, tiktokId, youtubeUrlbodystringTuỳ chọnLiên kết mạng xã hội.
metadatabodyobjectTuỳ chọnDữ liệu tuỳ ý, lưu dạng JSON.

Cần chú ý

  • Gọi từ backend của bạn. Không nhúng x-api-key vào ứng dụng.
  • Khai báo đầy đủ hồ sơ ở lần đầu: hồ sơ quyết định người dùng được nhận dự án nào. Các lần sau (created = false) mọi trường hồ sơ đều bị bỏ qua.
  • Không gọi lại API này chỉ để lấy token mới: mỗi lần khởi tạo thu hồi phiên cũ của người dùng trên thiết bị khác. Dùng API Làm mới phiên.
  • accessToken là chuỗi phiên, không phải JWT. Ứng dụng gửi nó trong header token.

Request mẫu

POST /questlab/integration/users/init
bash
curl -X POST "$GW/questlab/integration/users/init" \
  -H "x-api-key: $API_KEY" \
  -H "transactionId: ACME-INIT-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "SDK_INTEGRATION",
    "externalUserId": "acme_user_9",
    "deviceId": "8201b4a3396c4ea6",
    "name": "Nguyen Van A",
    "gender": "MALE",
    "operatingArea": "HANOI",
    "skill": "IMAGE,AUDIO"
  }'

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.
sourceTypestringGiá trị đã gửi.
externalUserIdstringMã người dùng phía bạn, để đối chiếu.
questlabUserIdUUIDId người dùng bên QuestLab, dùng để đối soát.
statusstringACTIVE hoặc INACTIVE. Người dùng bị khoá không nhận được nhiệm vụ.
createdbooleantrue là vừa tạo mới; false là đã có từ trước và trường hồ sơ bị bỏ qua.
accessTokenstringToken phiên, gửi trong header token.
expiresInnumberSố giây còn lại của accessToken.
refreshTokenstringDùng để làm mới phiên.
refreshExpiresInnumberSố giây còn lại của refreshToken; hết hạn thì khởi tạo lại.
200 OK
json
{
  "status": true,
  "httpCode": 200,
  "data": {
    "partnerCode": "ACME",
    "sourceType": "SDK_INTEGRATION",
    "externalUserId": "acme_user_9",
    "questlabUserId": "15603676-f0ea-4fe9-9d04-cf07901728f0",
    "status": "ACTIVE",
    "created": true,
    "accessToken": "5c928cb5dc8699012200c99c7cc0ec139f0b06dfe1b66dc2aa1d223c9405a491",
    "expiresIn": 86400,
    "refreshToken": "c04995dca1aaab2afa08b95d621c1802f92691783e484d3ca5e28eb1786509c2",
    "refreshExpiresIn": 2592000
  }
}

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.
2015Gọi bằng token của người dùng thay vì x-api-key.Dùng x-api-key.
2021Thiếu header transactionId.Bổ sung header.
2022sourceType không hợp lệ.Dùng một trong ba giá trị hợp lệ.
httpCode 503Dịch vụ hồ sơ tạm thời lỗi.Retry có backoff.
Cấu trúc response và lỗi dùng chung