Mục lục tài liệu
Quy ước & mã lỗi
Quy ước dùng chung cho mọi API. Mỗi trang API chỉ ghi lỗi riêng của API đó; lỗi dùng chung nằm ở trang này.
Cấu trúc response
HTTP status luôn là 200, kể cả khi nghiệp vụ thất bại; kết quả nằm trong body. Kiểm tra data == null trước, sau đó tới errorCode. Riêng lỗi xác thực ở tầng gateway (sai x-api-key, IP chưa đăng ký) có thể trả HTTP 401 thật.
{
"status": true,
"httpCode": 200,
"message": "OK",
"errorCode": null,
"data": { }
}| Trường | Ý nghĩa |
|---|---|
status | true là xử lý xong (không có nghĩa là có dữ liệu); false là có lỗi |
httpCode | Mã nghiệp vụ: 200, 400, 401, 403, 404, 409, 503 |
message | Thông điệp hiển thị được cho người dùng |
errorCode | Mã lỗi ngắn để rẽ nhánh, ổn định hơn message |
data | Payload; null khi không có kết quả |
Phân trang
page bắt đầu từ 1 ở assignments, tasks/my-assigned, projects/discover và guest/assignments; bắt đầu từ 0 ở campaigns/public. total là tổng số bản ghi khớp bộ lọc.
Thời gian & đếm ngược
Mốc thời gian là ISO-8601 UTC. Dùng serverTime để bù lệch đồng hồ thiết bị và đếm ngược từ remainingSeconds, không tính expiredAt - now bằng đồng hồ máy.
Định danh
Mọi id là UUID. lsTaskId (kiểu số) chỉ dùng để đối soát, không dùng để gọi API.
Media
Ảnh, âm thanh, PDF trong data là signed URL gắn với phiên: khi tải phải gửi kèm header xác thực như các API khác (token ở kịch bản 1, x-api-key từ backend ở kịch bản 2) và giữ nguyên query expires, signature. URL dạng /media/... phải ghép với gateway kèm prefix /questlab. Không gửi các header này tới URL của bên thứ ba.
Phiên bản API
/questlab/sdk/v1 được giữ ổn định; thay đổi phá vỡ tương thích sẽ ra v2. Response có thể được bổ sung trường mới, vì vậy client cần bỏ qua trường không nhận ra.
Định dạng kết quả gán nhãn
result theo định dạng Label Studio. from_name / to_name lấy từ cấu hình nhãn của dự án (kịch bản 1: GET /questlab/sdk/v1/projects/{projectId}), không hardcode. Toạ độ ảnh tính theo phần trăm từ 0 đến 100, không phải pixel.
| Loại | type | Khoá trong value |
|---|---|---|
| Ảnh (bounding box) | rectanglelabels | x, y, width, height, rotation, rectanglelabels |
| Văn bản | labels | start, end, text, labels |
| HTML | hypertextlabels | start, end, startOffset, endOffset, globalOffsets, text, hypertextlabels |
| Lựa chọn | choices | choices |
| Văn bản tự do | textarea | text |
| Số | number | number |
Mã lỗi dùng chung
Rẽ nhánh theo errorCode; message chỉ dùng để hiển thị.
| Mã | Ý nghĩa | Cách xử lý |
|---|---|---|
HTTP 401 (gateway) | x-api-key sai/hết hạn hoặc IP chưa đăng ký | Kiểm tra cấu hình, không retry; liên hệ QuestLab |
httpCode 401 | token thiếu hoặc hết hạn (kịch bản 1) | Làm mới phiên; thất bại thì khởi tạo lại |
2013 | X-Partner-Code không khớp api-key | Sửa hoặc bỏ header |
2015 | Gọi API tích hợp bằng token thay vì x-api-key | Dùng x-api-key cho /questlab/integration/** |
2021 | Thiếu header transactionId | Bổ sung header |
2025 | Hết nhiệm vụ trong phạm vi (kịch bản 2) | Hiển thị trạng thái trống, thử lại sau |
2030 | assignedTaskId không tồn tại | Nhận nhiệm vụ mới |
2031, 2032 | Lượt làm việc không thuộc tài khoản tích hợp của bạn | Không retry |
1024 | Cần vượt qua bài kiểm tra của chiến dịch | Chuyển sang luồng bài kiểm tra |
2000 đến 2004 | Gợi ý nhiệm vụ không còn hợp lệ (API gợi ý) | Tải lại danh sách gợi ý, không hiển thị lỗi |
2005 | Đã giữ tối đa số nhiệm vụ cùng lúc (API gợi ý) | Dẫn tới danh sách nhiệm vụ đang làm |
2006, 2007 | Dịch vụ phụ thuộc tạm thời lỗi (API gợi ý) | Retry có backoff |
Checklist trước khi go-live
- Đã nhận
x-api-key, đăng ký IP backend và địa chỉ gateway từ QuestLab. x-api-keychỉ nằm ở backend, không có trong ứng dụng.deviceId/externalUserIdđược sinh một lần và lưu trong bộ nhớ bảo mật.- Gửi
transactionIdở mọi API/questlab/integration/**, mỗi lượt gọi một mã. - Kịch bản 1 gửi
token: {accessToken}ở mọi API và khi tải media, không dùngAuthorization: Bearer. - Kịch bản 1 làm mới token trước hạn, không khởi tạo lại chỉ để lấy token.
- Xử lý kết quả theo
datavàerrorCode, không theo HTTP status hay chuỗimessage. - Đếm ngược theo
serverTime+remainingSeconds. - Lưu
assignedTaskIdđể khôi phục nhiệm vụ đang làm khi ứng dụng khởi động lại. - Không đọc
drafts/predictionskhi dựng màn gán nhãn.
