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ê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 |
sourceType | body | string | Bắt buộc | SDK_INTEGRATION, THIRD_PARTY_APP hoặc PARTNER_APP. |
externalUserId | body | string | Bắt buộc | Mã người dùng phía bạn. Mỗi người dùng một mã, giữ cố định. |
deviceId | body | string | Tuỳ chọn | Mã thiết bị. Gửi rỗng thì giữ giá trị cũ. |
name, email, phone | body | string | Tuỳ chọn | Thông tin liên hệ, chỉ dùng ở lần khởi tạo đầu tiên. |
gender, occupation, university, operatingArea, skill | body | string | Tuỳ chọn | Hồ 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, youtubeUrl | body | string | Tuỳ chọn | Liên kết mạng xã hội. |
metadata | body | object | Tuỳ chọn | Dữ 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-keyvà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.
accessTokenlà chuỗi phiên, không phải JWT. Ứng dụng gửi nó trong headertoken.
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ểu | Mô tả |
|---|---|---|
partnerCode | string | Mã đối tác suy ra từ api-key. |
sourceType | string | Giá trị đã gửi. |
externalUserId | string | Mã người dùng phía bạn, để đối chiếu. |
questlabUserId | UUID | Id người dùng bên QuestLab, dùng để đối soát. |
status | string | ACTIVE hoặc INACTIVE. Người dùng bị khoá không nhận được nhiệm vụ. |
created | boolean | true là vừa tạo mới; false là đã có từ trước và trường hồ sơ bị bỏ qua. |
accessToken | string | Token phiên, gửi trong header token. |
expiresIn | number | Số giây còn lại của accessToken. |
refreshToken | string | Dùng để làm mới phiên. |
refreshExpiresIn | number | Số 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ĩ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. |
2015 | Gọi bằng token của người dùng thay vì x-api-key. | Dùng x-api-key. |
2021 | Thiếu header transactionId. | Bổ sung header. |
2022 | sourceType không hợp lệ. | Dùng một trong ba giá trị hợp lệ. |
httpCode 503 | Dịch vụ hồ sơ tạm thời lỗi. | Retry có backoff. |
