API Dokümantasyonu

QR Yoklama sisteminin tüm REST API endpointleri, istek/yanıt örnekleri ve hata kodları.

Base URL

{{ url('/api') }}

Genel Bilgiler

Tüm istekler Content-Type: application/json ve Accept: application/json headerları ile gönderilmelidir.

Tarih/saat alanları ISO 8601 formatındadır.

Sayfalandırma destekleyen endpointlerde ?page=2 parametresi kullanılabilir.

Kimlik Doğrulama

Korunmuş endpointler için Authorization: Bearer {TOKEN} headeri gereklidir.

Token, /auth/login endpointinden alınır. Her token tek bir cihaz için geçerlidir.

Yetkisiz erişimde 401 Unauthenticated, yetersiz roldeyse 403 Forbidden döner.

Yoklama Hata Kodları

POST /student/verify endpointinin döndürebileceği hata kodları:

INVALID_QR

QR kod geçersiz, veritabanında eşleşen oturum yok

SESSION_EXPIRED

Yoklama oturumunun süresi dolmuş

QR_EXPIRED

QR kodun yenilenme süresi geçmiş, yeni QR bekleniyor

NOT_ENROLLED

Öğrenci bu derse kayıtlı değil

ALREADY_RECORDED

Bu oturumda zaten yoklama kaydı var

FAKE_GPS_DETECTED

Sahte konum (mock location) tespit edildi

GPS_OUT_OF_RANGE

Öğrenci tanımlanan konum yarıçapı dışında

{{-- ============================================== --}} {{-- AUTH ENDPOINTS --}} {{-- ============================================== --}}

Auth

POST /auth/login Public

Kullanıcı girişi yapar ve API tokeni döndürür.

İstek Parametreleri

Alan	Tip	Açıklama
email Zorunlu	string	Kullanıcı e-posta adresi
password Zorunlu	string	Kullanıcı şifresi
device_id Opsiyonel	string	Cihaz benzersiz kimlik numarası

Yanıt 200

{
    "message": "Giriş başarılı.",
    "user": {
        "id": 2,
        "name": "Ahmet",
        "surname": "Yilmaz",
        "email": "ahmet.yilmaz@yoklama.edu.tr",
        "student_number": null,
        "role": "instructor"
    },
    "token": "1|abc123..."
}

POST /auth/logout Auth

Mevcut tokeni siler ve oturumu sonlandırır.

Yanıt 200

{
    "message": "Çıkış başarılı."
}

GET /auth/profile Auth

Giriş yapmış kullanıcının profil bilgilerini döndürür.

Yanıt 200

{
    "user": {
        "id": 4,
        "name": "Mehmet",
        "surname": "Kaya",
        "full_name": "Mehmet Kaya",
        "email": "mehmet.kaya@stu.yoklama.edu.tr",
        "student_number": "2021001",
        "role": "student"
    }
}

PUT /auth/password Auth

Kullanıcının şifresini günceller.

Alan	Tip	Açıklama
current_password Zorunlu	string	Mevcut şifre
password Zorunlu	string	Yeni şifre (min: 8)
password_confirmation Zorunlu	string	Yeni şifre tekrarı

{{-- ============================================== --}} {{-- STUDENT ENDPOINTS --}} {{-- ============================================== --}}

Öğrenci

Öğrenci rolüne sahip kullanıcılar için endpointler.

GET /student/active-sessions Student

Öğrencinin kayıtlı olduğu derslerdeki aktif yoklama oturumlarını listeler. Aktif oturum yoksa bilgi mesajı döner.

Yanıt 200

{
    "sessions": [
        {
            "session_id": 1,
            "course_code": "BIL101",
            "course_name": "Bilgisayar Bilimine Giris",
            "started_at": "14:30",
            "expires_at": "15:00",
            "remaining_minutes": 22.5
        }
    ]
}

POST /student/verify Student

QR kod ve GPS konum ile çift katmanlı yoklama doğrulaması yapar. Sistemin en kritik endpointidir.

İstek Parametreleri

Alan	Tip	Açıklama
qr_token Zorunlu	string	QR koddan okunan token (max: 128)
latitude Zorunlu	number	Öğrencinin enlemi (-90 ile 90)
longitude Zorunlu	number	Öğrencinin boylamı (-180 ile 180)
device_info Opsiyonel	object	Cihaz bilgileri (fake GPS tespiti için)
device_info.is_mock_location	boolean	Android mock location durumu
device_info.gps_accuracy	number	GPS doğruluk değeri (metre)
device_info.platform	string	"android" veya "ios"

Başarılı Yanıt 200

{
    "success": true,
    "message": "Yoklama kaydınız başarıyla alındı.",
    "record": {
        "course": "Bilgisayar Bilimine Giris",
        "verified_at": "14:32:15",
        "qr_verified": true,
        "gps_verified": true,
        "result": "present"
    }
}

Başarısız Yanıt 400 (GPS)

{
    "success": false,
    "message": "Konum sınıf dışında. Mesafe: 589 metre (izin verilen: 50 metre)",
    "error_code": "GPS_OUT_OF_RANGE",
    "record": {
        "qr_verified": true,
        "gps_verified": false,
        "distance_meters": 589.03,
        "allowed_radius": 50,
        "result": "failed_gps"
    }
}

GET /student/records?course_id=1 Student

Öğrencinin geçmiş yoklama kayıtlarını listeler. Opsiyonel course_id parametresi ile ders bazlı filtreleme yapılabilir.

GET /student/summary Student

Öğrencinin tüm derslerindeki katılım özetini döndürür: toplam oturum, katılım, devamsızlık ve katılım oranı.

Yanıt 200

{
    "summary": [
        {
            "course_code": "BIL101",
            "course_name": "Bilgisayar Bilimine Giris",
            "total_sessions": 12,
            "attended": 10,
            "absent": 2,
            "attendance_rate": 83.3
        }
    ]
}

{{-- ============================================== --}} {{-- INSTRUCTOR ENDPOINTS --}} {{-- ============================================== --}}

Öğretim Elemanı

Yoklama yönetimi, canlı takip ve raporlama endpointleri.

GET /instructor/courses Instructor

Öğretim elemanının aktif derslerini öğrenci sayısıyla birlikte listeler.

POST /instructor/session/start Instructor

Yeni bir yoklama oturumu başlatır. Dinamik QR token otomatik üretilir.

İstek Parametreleri

Alan	Tip	Açıklama
course_id Zorunlu	integer	Ders ID
latitude Zorunlu	number	Yoklama konum enlemi
longitude Zorunlu	number	Yoklama konum boylami
duration_minutes Zorunlu	integer	Oturum süresi (5-360 dk)
classroom_id Opsiyonel	integer	Derslik ID (seçimliyse konumu override eder)
radius_meters Opsiyonel	integer	Kabul yarıçapı metre (varsayılan: 50)
qr_refresh_seconds Opsiyonel	integer	QR yenilenme süresi (varsayılan: 30sn)

Yanıt 201

{
    "message": "Yoklama oturumu başlatıldı.",
    "session": {
        "id": 1,
        "qr_token": "QvlpFZ0ob3xAJ0sM2uApLD...",
        "qr_refresh_seconds": 30,
        "started_at": "2026-03-23T14:30:00+00:00",
        "expires_at": "2026-03-23T15:00:00+00:00",
        "latitude": "39.9255330",
        "longitude": "32.8662870",
        "radius_meters": 50
    }
}

POST /instructor/session/{id}/refresh-qr Instructor

Aktif oturumun QR tokenini manuel olarak yeniler. Yeni token ve geçerlilik süresi döner.

POST /instructor/session/{id}/stop Instructor

Yoklama oturumunu sonlandırır. Katılım özeti döner.

Yanıt 200

{
    "message": "Yoklama oturumu sonlandırıldı.",
    "summary": {
        "present": 8,
        "absent": 2,
        "total": 10
    }
}

GET /instructor/session/{id}/live Instructor

Yoklama sırasında anlık katılım durumunu döndürür. Öğrenci listesi, doğrulama durumları ve mesafe bilgilerini içerir.

Yanıt 200

{
    "session_id": 1,
    "status": "active",
    "is_active": true,
    "present_count": 1,
    "absent_count": 9,
    "total_students": 10,
    "records": [
        {
            "student_number": "2021001",
            "name": "Mehmet",
            "surname": "Kaya",
            "verified_at": "14:32:15",
            "qr_verified": true,
            "gps_verified": true,
            "result": "present",
            "distance_meters": "0.82"
        }
    ]
}

GET /instructor/reports/sessions?course_id=1&date_from=2026-03-01&date_to=2026-03-31 Instructor

Geçmiş yoklama oturumlarını ders ve tarih aralığı bazında listeler.

GET /instructor/reports/export?course_id=1 Instructor

Yoklama kayıtlarını Excel (.xlsx) dosyası olarak indirir. Sütunlar: Öğrenci No, Ad, Soyad, Ders, Tarih, Saat, QR Durumu, GPS Durumu, Sonuç, Mesafe, Devamsızlık Oranı, Toplam Katılım, Öğretmen Notu.

Alan	Tip	Açıklama
course_id Zorunlu	integer	Ders ID
date_from Opsiyonel	date	Başlangıç tarihi (YYYY-MM-DD)
date_to Opsiyonel	date	Bitiş tarihi (YYYY-MM-DD)

{{-- ============================================== --}} {{-- ADMIN ENDPOINTS --}} {{-- ============================================== --}}

Admin

Sistem yönetimi: kullanıcı, ders, derslik oluşturma ve log görüntüleme.

GET /admin/users?role=student&search=mehmet Admin

Kullanıcılar listelenir (sayfalandırılmış). role ve search parametreleri ile filtrelenir.

POST /admin/users Admin

Yeni kullanıcı oluşturur (öğrenci, öğretim elemanı veya admin).

Alan	Tip	Açıklama
name Zorunlu	string	Ad
surname Zorunlu	string	Soyad
email Zorunlu	string	E-posta (benzersiz)
password Zorunlu	string	Şifre (min: 8)
role Zorunlu	string	student \| instructor \| admin
student_number Opsiyonel	string	Öğrenci numarası (benzersiz)

POST /admin/courses Admin

Yeni ders oluşturur. Ayrıca POST /admin/courses/assign-student ve POST /admin/courses/assign-instructor endpointleri ile kullanıcılar derslere atanır.

POST /admin/classrooms Admin

Yeni derslik oluşturur. Enlem, boylam ve varsayılan kabul yarıçapı tanımlanır.

Alan	Tip	Açıklama
name Zorunlu	string	Derslik adı (örn: D-201)
building Opsiyonel	string	Bina adı
floor Opsiyonel	string	Kat
latitude Zorunlu	number	Enlem
longitude Zorunlu	number	Boylam
radius_meters Opsiyonel	integer	Kabul yarıçapı (varsayılan: 50m)