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.

Response envelope
json
{
  "status": true,
  "httpCode": 200,
  "message": "OK",
  "errorCode": null,
  "data": { }
}
TrườngÝ nghĩa
statustrue là xử lý xong (không có nghĩa là có dữ liệu); false là có lỗi
httpCodeMã nghiệp vụ: 200, 400, 401, 403, 404, 409, 503
messageThông điệp hiển thị được cho người dùng
errorCodeMã lỗi ngắn để rẽ nhánh, ổn định hơn message
dataPayload; 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ạitypeKhoá trong value
Ảnh (bounding box)rectanglelabelsx, y, width, height, rotation, rectanglelabels
Văn bảnlabelsstart, end, text, labels
HTMLhypertextlabelsstart, end, startOffset, endOffset, globalOffsets, text, hypertextlabels
Lựa chọnchoiceschoices
Văn bản tự dotextareatext
Sốnumbernumber

Mã lỗi dùng chung

Rẽ nhánh theo errorCode; message chỉ dùng để hiển thị.

MãÝ nghĩaCá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 401token 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
2013X-Partner-Code không khớp api-keySửa hoặc bỏ header
2015Gọi API tích hợp bằng token thay vì x-api-keyDùng x-api-key cho /questlab/integration/**
2021Thiếu header transactionIdBổ sung header
2025Hế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
2030assignedTaskId không tồn tạiNhận nhiệm vụ mới
2031, 2032Lượt làm việc không thuộc tài khoản tích hợp của bạnKhông retry
1024Cần vượt qua bài kiểm tra của chiến dịchChuyển sang luồng bài kiểm tra
2000 đến 2004Gợ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, 2007Dị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-key chỉ 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ùng Authorization: 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 data và errorCode, không theo HTTP status hay chuỗi message.
  • Đế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 / predictions khi dựng màn gán nhãn.