Skip to main content

04 — API: Assessment System

Endpoint untuk menjalankan assessment (Ice Breaker, Universal, Adaptive Confirmation) dan melihat hasil.

Ice Breaker Assessment​

POST /assessments/guest/ice-breaker​

Mulai Ice Breaker Assessment untuk guest (tanpa login).

Access: Public

// Request Body
{
  "guestId": "guest_abc123",          // ID sementara dari frontend
  "deviceInfo": {
    "platform": "web",
    "browser": "chrome",
    "isMobile": false
  }
}

// Response 201
{
  "success": true,
  "data": {
    "sessionId": "as_V1StGXR8_Z5j",
    "type": "ice_breaker",
    "status": "in_progress",
    "currentQuestion": {
      "index": 0,
      "text": "Hi there! 👋 Let's start with something simple. Can you tell me a little about yourself?",
      "audioUrl": "https://r2.eljoy.id/tts/ice-breaker-q0.mp3",
      "type": "open_ended",
      "estimatedDurationSec": 30
    },
    "totalQuestions": 3,
    "companionMood": "friendly"
  }
}

POST /assessments/guest/ice-breaker/:sessionId/answer​

Kirim jawaban suara untuk pertanyaan Ice Breaker.

Access: Public

POST /api/v1/assessments/guest/ice-breaker/as_V1StGXR8_Z5j/answer
Content-Type: multipart/form-data

audio: <file> (webm/mp3/wav, max 10MB)
questionIndex: 0
// Response 200 (ada pertanyaan berikutnya)
{
  "success": true,
  "data": {
    "answered": {
      "questionIndex": 0,
      "transcript": "My name is Budi, I work as a software engineer in Jakarta",
      "quickFeedback": "Great start! Your pronunciation is clear. 👍"
    },
    "nextQuestion": {
      "index": 1,
      "text": "Nice to meet you, Budi! What do you like to do in your free time?",
      "audioUrl": "https://r2.eljoy.id/tts/ice-breaker-q1.mp3",
      "type": "open_ended",
      "estimatedDurationSec": 30
    },
    "progress": {
      "answered": 1,
      "total": 3
    }
  }
}

// Response 200 (assessment selesai)
{
  "success": true,
  "data": {
    "answered": {
      "questionIndex": 2,
      "transcript": "I think technology can help people learn faster",
      "quickFeedback": "Interesting perspective! Well articulated."
    },
    "completed": true,
    "resultId": "as_V1StGXR8_Z5j"
  }
}

GET /assessments/guest/ice-breaker/:sessionId/result​

Ambil hasil Ice Breaker Assessment.

Access: Public

// Response 200
{
  "success": true,
  "data": {
    "sessionId": "as_V1StGXR8_Z5j",
    "type": "ice_breaker",
    "status": "completed",

    "cefrEstimate": "b1",
    "cefrLabel": "Intermediate",
    "overallScore": 68,

    "quickSummary": "Kamu sudah bisa berkomunikasi dengan cukup baik! Pronunciation-mu jelas dan kamu berani mengekspresikan pendapat.",

    "skillHighlights": [
      { "skill": "pronunciation", "score": 72, "label": "Baik" },
      { "skill": "fluency", "score": 58, "label": "Perlu Latihan" },
      { "skill": "confidence", "score": 75, "label": "Baik" }
    ],

    "encouragement": "Kamu punya potensi besar! Dengan latihan rutin, kamu bisa mencapai level B2 dalam 3-4 bulan. 🚀",

    "nextStep": {
      "action": "start_universal_assessment",
      "label": "Lanjut Assessment Lengkap",
      "description": "Assessment 5 menit untuk mengetahui kemampuanmu lebih detail"
    }
  }
}

Universal Assessment​

POST /assessments/guest/universal​

Mulai Universal Assessment setelah Ice Breaker.

Access: Public

// Request Body
{
  "guestId": "guest_abc123",
  "iceBreakerSessionId": "as_V1StGXR8_Z5j"   // Referensi ke hasil Ice Breaker
}

// Response 201
{
  "success": true,
  "data": {
    "sessionId": "as_anotherSessionId",
    "type": "universal",
    "status": "in_progress",
    "estimatedDurationMin": 5,
    "currentQuestion": {
      "index": 0,
      "text": "Look at this picture and describe what you see.",
      "imageUrl": "https://r2.eljoy.id/content/assess-img-01.jpg",
      "type": "picture_description",
      "estimatedDurationSec": 60
    },
    "totalQuestions": 5,
    "adaptiveNote": "Pertanyaan akan menyesuaikan berdasarkan jawabanmu"
  }
}

POST /assessments/guest/universal/:sessionId/answer​

Kirim jawaban untuk Universal Assessment. Format sama dengan Ice Breaker answer.

Access: Public

Request dan response format sama dengan Ice Breaker answer endpoint. Bedanya, pertanyaan berikutnya dipilih secara adaptive berdasarkan performa jawaban sebelumnya.

GET /assessments/guest/universal/:sessionId/result​

Ambil preview hasil Universal Assessment (tidak lengkap, karena belum register).

Access: Public

// Response 200
{
  "success": true,
  "data": {
    "sessionId": "as_anotherSessionId",
    "type": "universal",
    "status": "completed",

    "cefrEstimate": "b1",
    "overallScore": 65,

    // Preview — detail terbatas untuk mendorong registrasi
    "previewSkills": {
      "pronunciation": 72,
      "grammar": "🔒",           // Locked — perlu register
      "vocabulary": "🔒",
      "fluency": 58,
      "coherence": "🔒",
      "confidence": 75,
      "engagement": "🔒"
    },

    "teaser": "Ada 4 insight penting tentang kemampuanmu yang belum terungkap. Daftar untuk melihat hasil lengkap dan dapatkan Blueprint belajar personal! 🎓",

    "nextStep": {
      "action": "register",
      "label": "Daftar & Lihat Hasil Lengkap",
      "description": "Gratis! Hanya perlu email dan password."
    }
  }
}

Adaptive Confirmation Assessment​

POST /assessments/adaptive-confirmation​

Mulai Adaptive Confirmation Assessment (setelah register).

Access: Authenticated (Member)

// Request Body — kosong, data diambil dari profil user

// Response 201
{
  "success": true,
  "data": {
    "sessionId": "as_confirmSessionId",
    "type": "adaptive_confirmation",
    "status": "in_progress",
    "purpose": "Mengkonfirmasi dan menyempurnakan profil kemampuanmu berdasarkan hasil assessment sebelumnya",
    "currentQuestion": {
      "index": 0,
      "text": "Let's do a quick role play. Imagine you're calling a restaurant to make a reservation for dinner tonight.",
      "type": "role_play",
      "context": "You need to book a table for 4 people at 7 PM",
      "estimatedDurationSec": 90
    },
    "totalQuestions": 3,
    "basedOn": "Berdasarkan hasil assessment sebelumnya, kami ingin mengkonfirmasi beberapa kemampuanmu"
  }
}

POST /assessments/adaptive-confirmation/:sessionId/answer​

Kirim jawaban untuk Adaptive Confirmation.

Access: Authenticated

Format sama dengan assessment answer endpoint lainnya.

GET /assessments/:sessionId/result​

Ambil hasil assessment lengkap (untuk user yang sudah login).

Access: Authenticated

// Response 200
{
  "success": true,
  "data": {
    "sessionId": "as_confirmSessionId",
    "type": "adaptive_confirmation",
    "status": "completed",

    "cefrLevel": "b1",
    "cefrLabel": "Intermediate",
    "cefrConfidence": 0.85,
    "overallScore": 67,

    // Skill Radar lengkap (7 dimensi)
    "skillRadar": {
      "pronunciation": { "score": 72, "label": "Baik", "trend": "stable" },
      "grammar": { "score": 60, "label": "Cukup", "trend": "improving" },
      "vocabulary": { "score": 65, "label": "Cukup", "trend": "stable" },
      "fluency": { "score": 58, "label": "Perlu Latihan", "trend": "stable" },
      "coherence": { "score": 68, "label": "Baik", "trend": "stable" },
      "confidence": { "score": 75, "label": "Baik", "trend": "improving" },
      "engagement": { "score": 80, "label": "Sangat Baik", "trend": "stable" }
    },

    // Strengths & areas to improve
    "strengths": [
      "Kamu percaya diri saat berbicara — ini modal yang sangat penting!",
      "Pronunciation-mu jelas, lawan bicara mudah memahami ucapanmu"
    ],
    "improvements": [
      "Fluency bisa ditingkatkan dengan latihan speaking rutin — kurangi jeda panjang",
      "Coba perkaya vocabulary dengan latihan topik bisnis dan opini"
    ],

    // Detailed feedback per answer
    "answerDetails": [
      {
        "questionIndex": 0,
        "questionText": "...",
        "transcript": "...",
        "score": 70,
        "feedback": "...",
        "corrections": [
          {
            "original": "I want to booking",
            "corrected": "I'd like to book",
            "explanation": "Gunakan 'would like to + base verb' untuk permintaan yang sopan"
          }
        ]
      }
    ]
  }
}

Assessment History​

GET /assessments/history​

Ambil riwayat semua assessment user.

Access: Authenticated

// Query: ?type=ice_breaker&limit=10

// Response 200
{
  "success": true,
  "data": [
    {
      "sessionId": "as_confirmSessionId",
      "type": "adaptive_confirmation",
      "status": "completed",
      "cefrResult": "b1",
      "overallScore": 67,
      "completedAt": "2026-09-20T10:30:00Z"
    },
    {
      "sessionId": "as_anotherSessionId",
      "type": "universal",
      "status": "completed",
      "cefrResult": "b1",
      "overallScore": 65,
      "completedAt": "2026-09-20T09:45:00Z"
    }
  ],
  "pagination": { ... }
}