Quickstart
Flow tối thiểu cho backend tích hợp bài đánh giá và lấy report.
Base URL
Docs và SDK dùng base URL kết thúc bằng /api. Các ví dụ bên dưới gọi /v1 trên cùng base URL này.
http://localhost:4000/apihttps://api.psyforge.dev/apiMint access token
Gửi tenant API key bằng Authorization: Bearer để lấy JWT ngắn hạn. Dùng JWT này cho các request tiếp theo.
export PSYFORGE_API_BASE="https://api.psyforge.dev/api" curl -X POST "$PSYFORGE_API_BASE/v1/auth/token" \ -H "Authorization: Bearer $PSYFORGE_API_KEY"
Tạo assessment session
Chọn framework và locale. Idempotency-Key giúp replay cùng request không tạo thêm session trùng.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"frameworkCode":"big-five","locale":"en","subjectRef":"candidate-001"}'Lấy câu hỏi tiếp theo
Client không tự chọn thứ tự câu hỏi. Server trả về item kế tiếp hoặc item null khi session đã đủ dữ liệu.
curl "$PSYFORGE_API_BASE/v1/sessions/$SID/next-item" \ -H "Authorization: Bearer $JWT"
Gửi response
Gửi itemId và answerValue/answerText. Với Likert, answerValue là số trên thang đo của item.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/responses" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"itemId":"$ITEM","answerValue":5}'Submit session
Submit đóng session. Sau bước này client không gửi thêm response cho session đó.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/submit" \ -H "Authorization: Bearer $JWT"
Tạo và poll report
Khi cần kết quả theo session, gọi POST /v1/sessions/SESSION_ID/reports rồi Poll GET /v1/sessions/SESSION_ID/reports/latest cho tới khi có trạng thái ready + download URL.
curl -s -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/reports" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{"locale":"en"}'
# Poll by session id (public/report lookup)
curl "$PSYFORGE_API_BASE/v1/sessions/$SID/reports/latest" \
-H "Authorization: Bearer $JWT"