Tích hợp lịch sử thi của học viên vào hệ thống của bạn
REST API đơn giản, miễn phí cho các trung tâm tiếng Đức. Chỉ cần email học viên — bạn có thể xác minh họ đã thi gì, đạt bao nhiêu điểm trên SkillTest.
Tích hợp trong 5 phút
Một endpoint REST duy nhất, trả JSON. Không cần SDK, dùng được với mọi ngôn ngữ.
Bảo mật mặc định
Bearer token, log đầy đủ mọi request, không trả đáp án từng câu, chỉ điểm tổng kết.
Miễn phí cho trung tâm
Cấp key miễn phí cho các trung tâm/đơn vị đào tạo đối tác. Không giới hạn số lần gọi hợp lý.
Dùng để làm gì?
Vài ví dụ phổ biến mà các trung tâm tiếng Đức đang làm với API này:
Xác minh trình độ đầu vào
Học viên đăng ký lớp B1 ở trung tâm bạn — gọi API để xem họ đã thi A2 trên SkillTest đạt bao nhiêu điểm, có thực sự đủ trình độ B1 không.
Đồng bộ portal học viên
Hiện toàn bộ lịch sử thi (Goethe / telc / OSD) của học viên ngay trong dashboard nội bộ — không bắt họ phải kể lại đã thi gì.
Báo cáo tiến độ cho phụ huynh
Tự động tổng hợp số lần thi thử, tỉ lệ pass, điểm tốt nhất theo từng cấp độ — gửi báo cáo tuần/tháng.
Gợi ý lớp phù hợp
Dựa trên điểm thi gần nhất + điểm yếu, gợi ý đúng lớp/khoá học cho học viên — tăng tỉ lệ chuyển đổi.
Bắt đầu trong 3 bước
Từ lúc đăng ký đến lúc gọi API thành công — thường mất chưa tới 1 ngày.
Đăng ký nhận key
Test key bằng /ping
GET /api/v1/ping với key vừa nhận. Nếu trả về ok: true là key đã hoạt động.Tích hợp vào hệ thống
/api/v1/test-history với email học viên. Copy code mẫu bên dưới và chạy.Code mẫu
Copy-paste là chạy được. Thay sk_live_xxx bằng key của bạn.
curl -H "Authorization: Bearer sk_live_xxx" \
"https://skilltest.io/api/v1/test-history?email=hocvien@gmail.com"Response mẫu (status 200)
{
"found": true,
"user": {
"id": "a3f1...",
"email": "hocvien@gmail.com",
"display_name": "Nguyễn Văn A",
"created_at": "2026-01-12T08:30:00.000Z"
},
"summary": {
"total_attempts": 7,
"passed_count": 5,
"average_percentage": 72.43,
"by_category": {
"Goethe": { "attempts": 5, "passed": 4, "best_percentage": 89.5 },
"telc": { "attempts": 2, "passed": 1, "best_percentage": 65.0 }
}
},
"verifications": [
{
"category": "Goethe",
"level": "A1",
"status": "verified",
"status_label_vi": "Đã xác minh",
"confidence_score": 78,
"evidence": {
"overall_attempts": 5,
"overall_passed": 4,
"overall_pass_rate": 0.8,
"suspicious_speed_attempts": 0,
"skills": {
"lesen": { "attempts": 2, "passed": 2, "distinct_tests_passed": 2, "best_percentage": 86 },
"hören": { "attempts": 2, "passed": 2, "distinct_tests_passed": 2, "best_percentage": 80 },
"schreiben": { "attempts": 1, "passed": 0, "distinct_tests_passed": 0, "best_percentage": 50 }
}
},
"reasons": [
"✓ Đã pass 2 đề Lesen khác nhau",
"✓ Đã pass 2 đề Hören khác nhau",
"✗ Schreiben: thi 1 lần, chưa pass"
],
"last_attempt_at": "2026-04-21T10:15:00.000Z"
}
],
"history": [
{
"result_id": "...",
"test_title": "Goethe-Zertifikat B1 — Lesen",
"category": "Goethe",
"level": "B1",
"language": "de",
"score": 24,
"total_points": 30,
"percentage": 80.0,
"passed": true,
"duration_seconds": 3600,
"completed_at": "2026-04-21T10:15:00.000Z"
}
]
}404 Not Found
Email không tồn tại trong hệ thống → trả { found: false }. Không phải lỗi server.
401 Unauthorized
Key sai/thiếu/đã revoke. Kiểm tra header Authorization.
Xác minh trình độ — không chỉ dựa vào 1 lần pass
Trên SkillTest, mỗi đề thi là 1 kỹ năng riêng (Lesen / Hören / Schreiben). Một học viên thi 10 lần và hên pass 1 lần — không có nghĩa là họ thật sự đạt level. API của chúng tôi tính độ tin cậy dựa vào nhiều tín hiệu, không chỉ con số passed đơn lẻ.
Thuật toán đánh giá 4 yếu tố
- Phủ kỹ năng — pass bao nhiêu kỹ năng trong level này
- Đa dạng đề — pass ≥ 2 đề khác nhau cho mỗi kỹ năng (chống học vẹt 1 đề)
- Tỉ lệ pass — passed / tổng số lần thi (chống may rủi)
- Tốc độ làm bài — phát hiện làm dưới 30% thời gian (cheating signal)
5 mức xác minh
2 cách dùng:
- Gọi
/api/v1/test-history→ fieldverificationstự động có verification cho mọi level user đã thi. - Hoặc gọi riêng
/api/v1/level-verification?email=&category=Goethe&level=A1khi chỉ cần check 1 level cụ thể.
Lưu ý: Sprechen (kỹ năng nói) hiện không tự động chấm — chưa được tính vào verification. Mức "strong" và "verified" dựa trên 3 kỹ năng còn lại.
Tham chiếu API
/api/v1/pingKiểm tra key có hợp lệ không. Dùng để debug khi mới setup.
Headers: Authorization: Bearer <key>
/api/v1/test-historyLấy lịch sử thi của 1 user qua email.
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
| string | ✓ | Email học viên cần tra cứu | |
| limit | int | – | Số lần thi trả về (1-200, mặc định 50) |
Response bao gồm field verifications — danh sách xác minh cho mọi (category, level) user đã thi.
/api/v1/level-verificationXác minh user có thật sự đạt 1 level cụ thể không. Gọn hơn /test-history nếu chỉ cần check 1 level.
| Param | Type | Bắt buộc | Mô tả |
|---|---|---|---|
| string | ✓ | Email học viên | |
| category | string | ✓ | Goethe, OSD, telc... |
| level | string | ✓ | A1, A2, B1, B2, C1, C2 |
Câu hỏi thường gặp
API có miễn phí không?
Có. Miễn phí cho các trung tâm/đơn vị đào tạo đối tác. Chúng tôi chỉ giới hạn nếu phát hiện lạm dụng (hàng triệu request/ngày).
API key có expire không?
Không tự động hết hạn. Bạn có thể yêu cầu revoke và cấp lại bất cứ lúc nào (vd khi nhân sự nghỉ việc).
Có lo ngại về quyền riêng tư của học viên không?
API chỉ trả điểm số tổng kết, không trả nội dung bài làm hay đáp án từng câu. Bạn nên thông báo cho học viên rằng dữ liệu thi được chia sẻ với trung tâm khi họ đăng ký lớp.
Nếu email học viên ở trung tâm khác với email họ dùng trên SkillTest thì sao?
API match chính xác email. Bạn có thể yêu cầu học viên xác nhận email đã dùng để thi trên SkillTest khi đăng ký lớp.
Có rate limit không?
Hiện chưa enforce limit cứng. Khuyến nghị cache kết quả 5-15 phút để tránh gọi lặp.
Tôi cần thêm endpoint khác (vd webhook khi học viên thi xong)?
Liên hệ deutschvn.info@gmail.com — chúng tôi sẽ cân nhắc thêm endpoint nếu nhiều đối tác cần.
Nhận API key cho trung tâm của bạn
Điền form, chúng tôi sẽ liên hệ trong 1-2 ngày làm việc.