API — Quest

Tóm tắt endpoint

Method	Path	Mô tả	Auth	Rate limit
GET	`/api/v1/quests/daily`	Lấy daily quests và recount progress.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/quests/:code/claim`	Claim karma reward nếu complete.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.

GET Auth required apiLimiter

Endpoint này dùng để lấy daily quests và recount progress. Gọi endpoint này khi client cần thao tác đúng phạm vi module quest.

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/quests/daily \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "quest",
    "endpoint": "/api/v1/quests/daily"
  }
}

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Daily reset lúc 07:00 UTC+7.

POST Auth required apiLimiter

Endpoint này dùng để claim karma reward nếu complete. Gọi endpoint này khi client cần thao tác đúng phạm vi module quest.

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/quests/POST_1/claim \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "quest",
    "endpoint": "/api/v1/quests/:code/claim"
  }
}

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Daily reset lúc 07:00 UTC+7.