Yoklama Okul Entegrasyon API'si — Referans Spesifikasyon v1.0

Amaç: Okulların ve üniversitelerin kendi Öğrenci Bilgi Sistemlerinde (ÖBS/OBS/UBYS/LMS) implement edeceği standart bir arayüz. Bu arayüz mevcutsa, Yoklama uygulaması Playwright, headless Chrome, ekran kazıma (screen scraping) veya öğretmen şifresi saklama gibi yöntemlere hiç ihtiyaç duymaz.

Durum: Taslak · Tarih: 01.09.2026 · Lisans: CC BY 4.0 (serbestçe kullanılabilir, atıfla)

1. Neden bu spesifikasyon var

Türkiye'de eğitim verisi birlikte çalışabilirliği konusunda hiçbir ulusal standart yoktur. Yapılan tarama:

Uluslararası standartlar da yoklamayı çözmüyor:

Bu spesifikasyonun konumu: OneRoster v1.2 Rostering'in veri modelini taban alır (olgun, ücretsiz, uluslararası ihracatı kolaylaştırır) ve Ed-Fi'nin StudentSectionAttendanceEvent yapısından esinlenen bir yoklama katmanı ekler — çünkü OneRoster'da o katman yoktur. Türkiye bağlamına özgü alanlar (öğrenci numarası, dönem yapısı, birim hiyerarşisi) eklenmiştir.

2. Tasarım ilkeleri

1. Öğretmen şifresi asla istenmez, asla saklanmaz. Yetkilendirme OAuth 2.0 Client Credentials ile kurumdan gelir; iptal edilebilir ve denetlenebilir.
2. Okuma ağırlıklı. Sadece yoklama yazılır. Öğrenci, ders, program verisi salt okunurdur — yanlışlıkla kurumsal veri bozulamaz.
3. Idempotent. Aynı yoklama iki kez gönderilirse çift kayıt oluşmaz.
4. Artımlı. ?since= ile yalnızca değişenler çekilir; ETag desteklenir.
5. Kademeli uyum. Kurum her şeyi implement etmek zorunda değil; /.well-known/yoklama-configuration ile hangi yetenekleri desteklediğini beyan eder. Yoklama yazma desteklenmiyorsa uygulama dışa aktarma (export) moduna düşer.
6. Veri minimizasyonu. TCKN gibi hassas alanlar opsiyoneldir ve istenmez. Kimlik eşleştirme için öğrenci numarası yeterlidir. Hiçbir biyometrik alan yoktur ve olmayacaktır.
7. Türkçe dostu. UTF-8 zorunlu; tarih/saat ISO 8601, saat dilimi Europe/Istanbul varsayılan ama açık belirtilir.

3. Kimlik doğrulama

OAuth 2.0 Client Credentials (RFC 6749 §4.4).

POST /yoklama-api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=yoklama-app-abc123
&client_secret=•••
&scope=roster.readonly attendance.write

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "roster.readonly attendance.write"
}

Kapsamlar (scopes)

Güvenlik gereksinimleri: TLS 1.2+ zorunlu. client_secret en az 32 bayt entropi. Kurum, istemciyi hangi birimler/dersler için yetkilendirdiğini kendi tarafında sınırlayabilir (token'ın kapsamı kurumun politikasıdır).

4. Ortak kurallar

Base path: https://<kurum-alan-adi>/yoklama-api/v1

Sayfalama: ?limit=100&offset=0. Varsayılan limit=100, maksimum 1000. Yanıt başlığı X-Total-Count.

Artımlı çekim: ?since=2026-09-01T00:00:00+03:00 — bu tarihten sonra dateLastModified değeri değişen kayıtlar.

Önbellek: Sunucu ETag döner; istemci If-None-Match gönderir; değişmediyse 304 Not Modified.

Silme yerine pasifleştirme: Kayıtlar silinmez; status alanı active → tobedeleted olur. Böylece istemci neyin kaybolduğunu anlar.

Hata formatı: RFC 9457 Problem Details.

{
  "type": "https://yoklama.example/errors/invalid-section",
  "title": "Şube bulunamadı",
  "status": 404,
  "detail": "sourcedId 'SEC-2026-BIL101-A' ile şube bulunamadı.",
  "instance": "/yoklama-api/v1/sections/SEC-2026-BIL101-A"
}

Hız sınırlama: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; aşımda 429 + Retry-After.

Ortak alanlar: Her kaynak sourcedId (kurumun kendi benzersiz kimliği, string), status, dateLastModified taşır.

5. Yetenek keşfi

GET /.well-known/yoklama-configuration

{
  "specVersion": "1.0",
  "institution": { "name": "Örnek Üniversitesi", "sourcedId": "ORG-001" },
  "endpoints": { "base": "https://obs.ornek.edu.tr/yoklama-api/v1",
                 "token": "https://obs.ornek.edu.tr/yoklama-api/v1/oauth/token" },
  "capabilities": {
    "roster.read": true,
    "schedules.read": true,
    "classrooms.read": true,
    "attendance.write": true,
    "attendance.read": true,
    "attendance.sessionModel": "sweeps",
    "delta.since": true,
    "etag": true
  },
  "attendanceStatuses": ["present", "absent", "late", "excused", "partial"],
  "timezone": "Europe/Istanbul",
  "contact": "[email protected]"
}

İstemci bu belgeye göre davranışını ayarlar. attendance.write: false ise uygulama yoklamayı kendi veritabanında tutar ve kuruma Excel/CSV dışa aktarma sunar.

6. Okuma uçları

6.1 Kurumlar — GET /orgs

Okul, fakülte, bölüm hiyerarşisi.

{
  "orgs": [
    { "sourcedId": "ORG-001", "status": "active",
      "dateLastModified": "2026-08-15T10:00:00+03:00",
      "name": "Örnek Üniversitesi", "type": "institution",
      "identifier": "12345", "parentSourcedId": null },
    { "sourcedId": "ORG-010", "status": "active",
      "dateLastModified": "2026-08-15T10:00:00+03:00",
      "name": "Mühendislik Fakültesi", "type": "faculty",
      "parentSourcedId": "ORG-001" },
    { "sourcedId": "ORG-011", "status": "active",
      "dateLastModified": "2026-08-15T10:00:00+03:00",
      "name": "Bilgisayar Mühendisliği", "type": "department",
      "parentSourcedId": "ORG-010" }
  ]
}

type: institution · faculty · department · school · program

6.2 Dönemler — GET /terms

{
  "terms": [
    { "sourcedId": "TERM-2026-GUZ", "status": "active",
      "dateLastModified": "2026-07-01T09:00:00+03:00",
      "title": "2026-2027 Güz Dönemi", "type": "semester",
      "startDate": "2026-09-21", "endDate": "2027-01-16",
      "schoolYear": "2026-2027", "orgSourcedId": "ORG-001" }
  ]
}

type: semester · term · schoolYear · summerSchool

6.3 Dersler (katalog) — GET /courses

{
  "courses": [
    { "sourcedId": "CRS-BIL101", "status": "active",
      "dateLastModified": "2026-07-01T09:00:00+03:00",
      "title": "Programlamaya Giriş", "courseCode": "BIL101",
      "orgSourcedId": "ORG-011",
      "credits": 5, "ects": 6, "theoreticalHours": 3, "practicalHours": 2 }
  ]
}

6.4 Şubeler / ders açılışları — GET /sections

Bir dersin belirli bir dönemde açılan örneği. Yoklamanın bağlandığı temel varlık budur.

{
  "sections": [
    { "sourcedId": "SEC-2026G-BIL101-A", "status": "active",
      "dateLastModified": "2026-08-20T14:30:00+03:00",
      "title": "Programlamaya Giriş - A Şubesi", "sectionCode": "A",
      "courseSourcedId": "CRS-BIL101", "termSourcedId": "TERM-2026-GUZ",
      "orgSourcedId": "ORG-011",
      "language": "tr", "deliveryMode": "faceToFace",
      "maxEnrollment": 120,
      "attendanceRequired": true,
      "attendanceThreshold": 0.70 }
  ]
}

⚠️ attendanceThreshold kritik alan. YÖK Uzaktan Öğretim Usul ve Esasları (26.12.2024) m.11 devam kuralını tamamen birim kurullarına bırakıyor — sabit bir ulusal eşik yoktur. Kurum kendi eşiğini burada bildirir; istemci onu kullanır. Alan yoksa istemci kendi politikasını uygular.

deliveryMode: faceToFace · online · hybrid

6.5 Derslikler — GET /classrooms

{
  "classrooms": [
    { "sourcedId": "ROOM-M301", "status": "active",
      "dateLastModified": "2026-06-01T09:00:00+03:00",
      "name": "M-301", "building": "Mühendislik Binası",
      "capacity": 120, "type": "amphitheater",
      "orgSourcedId": "ORG-010" }
  ]
}

type: classroom · amphitheater · laboratory · studio · online

6.6 Kullanıcılar — GET /users

{
  "users": [
    { "sourcedId": "USR-20261234", "status": "active",
      "dateLastModified": "2026-08-25T11:00:00+03:00",
      "role": "student", "username": "20261234",
      "givenName": "Ayşe", "familyName": "Yılmaz",
      "identifier": "20261234",
      "email": "[email protected]",
      "orgSourcedIds": ["ORG-011"],
      "grade": 1, "enrollmentStatus": "active" },
    { "sourcedId": "USR-T-4471", "status": "active",
      "dateLastModified": "2026-08-01T08:00:00+03:00",
      "role": "teacher", "username": "akurt",
      "givenName": "Atakan", "familyName": "Kurt",
      "identifier": "4471",
      "email": "[email protected]",
      "orgSourcedIds": ["ORG-011"],
      "title": "Prof. Dr." }
  ]
}

role: student · teacher · administrator · guardian

Veri minimizasyonu: nationalId (TCKN) alanı spesifikasyonda tanımlı değildir ve istenmez. Öğrenci numarası (identifier) eşleştirme için yeterlidir. Kurum kendi tarafında ek alan döndürürse istemci bunları yok sayar ve saklamaz.

18 yaş altı öğrenciler için guardianSourcedIds alanı opsiyoneldir (veli rızası akışı gerekiyorsa).

6.7 Kayıtlar — GET /enrollments

Kimin hangi şubede hangi rolle bulunduğu.

{
  "enrollments": [
    { "sourcedId": "ENR-001", "status": "active",
      "dateLastModified": "2026-09-01T08:00:00+03:00",
      "sectionSourcedId": "SEC-2026G-BIL101-A",
      "userSourcedId": "USR-20261234",
      "role": "student", "primary": true,
      "beginDate": "2026-09-21", "endDate": "2027-01-16" }
  ]
}

Kısayol: GET /sections/{sourcedId}/students ve GET /sections/{sourcedId}/teachers — tek çağrıda öğrenci/öğretmen listesi. Uygulamanın en sık kullanacağı uçtur.

Öğretmenin kendi dersleri: GET /teachers/{sourcedId}/sections?term=TERM-2026-GUZ — öğretmen uygulamaya girdiğinde o dönemki derslerini görmesi için.

6.8 Haftalık program — GET /schedules

{
  "schedules": [
    { "sourcedId": "SCH-8891", "status": "active",
      "dateLastModified": "2026-08-28T16:00:00+03:00",
      "sectionSourcedId": "SEC-2026G-BIL101-A",
      "classroomSourcedId": "ROOM-M301",
      "dayOfWeek": 1,
      "startTime": "09:00", "endTime": "11:50",
      "recurrence": "weekly",
      "validFrom": "2026-09-21", "validUntil": "2027-01-16",
      "teacherSourcedIds": ["USR-T-4471"] }
  ]
}

dayOfWeek: 1 = Pazartesi … 7 = Pazar (ISO 8601). recurrence: weekly · biweekly · once

İstisnalar: GET /schedules/exceptions?since= — resmî tatil, telafi dersi, derslik değişikliği.

{
  "exceptions": [
    { "sourcedId": "EXC-0031", "scheduleSourcedId": "SCH-8891",
      "date": "2026-10-29", "type": "cancelled", "reason": "Resmî tatil" },
    { "sourcedId": "EXC-0032", "scheduleSourcedId": "SCH-8891",
      "date": "2026-11-05", "type": "makeup",
      "startTime": "13:00", "endTime": "15:50",
      "classroomSourcedId": "ROOM-M205", "reason": "Telafi dersi" }
  ]
}

7. Yoklama yazma uçları

7.1 Oturum oluşturma — POST /attendance/sessions

Bir ders saati için yoklama oturumu.

{
  "sourcedId": "SES-2026-09-22-BIL101A",
  "sectionSourcedId": "SEC-2026G-BIL101-A",
  "classroomSourcedId": "ROOM-M301",
  "scheduleSourcedId": "SCH-8891",
  "teacherSourcedId": "USR-T-4471",
  "date": "2026-09-22",
  "startedAt": "2026-09-22T09:05:12+03:00",
  "endedAt": "2026-09-22T11:47:03+03:00",
  "sweepCount": 3,
  "method": "face-1to1",
  "source": "yoklama-app",
  "notes": null
}

method: face-1to1 · proximity · qr · pin · manual · mixed

Idempotency: sourcedId istemci tarafından üretilir ve deterministiktir. Aynı sourcedId ile ikinci POST → 200 OK (mevcut kayıt döner), yeni kayıt oluşmaz. İstemci ayrıca Idempotency-Key başlığı gönderebilir.

Yanıt: 201 Created + Location başlığı.

7.2 Yoklama kaydı — POST /attendance/records

Toplu (batch) gönderim. Maksimum 500 kayıt / istek.

{
  "sessionSourcedId": "SES-2026-09-22-BIL101A",
  "records": [
    { "userSourcedId": "USR-20261234",
      "status": "present",
      "presenceRatio": 1.0,
      "sweepResults": [true, true, true],
      "method": "face-1to1",
      "verifiedAt": "2026-09-22T09:07:44+03:00",
      "flags": [] },
    { "userSourcedId": "USR-20261235",
      "status": "partial",
      "presenceRatio": 0.67,
      "sweepResults": [true, true, false],
      "method": "face-1to1",
      "verifiedAt": "2026-09-22T09:08:02+03:00",
      "flags": ["ERKEN_AYRILDI"] },
    { "userSourcedId": "USR-20261236",
      "status": "absent",
      "presenceRatio": 0.0,
      "sweepResults": [false, false, false],
      "method": null,
      "verifiedAt": null,
      "flags": [] },
    { "userSourcedId": "USR-20261237",
      "status": "present",
      "presenceRatio": 1.0,
      "sweepResults": [true, true, true],
      "method": "manual",
      "verifiedAt": "2026-09-22T09:15:00+03:00",
      "flags": ["MANUEL"],
      "note": "Telefon şarjı bitti, öğretmen onayı" }
  ]
}

status: present · absent · late · excused · partial

⚠️ Biyometrik veri yoktur ve olmayacaktır. Yüz şablonu, yüz görüntüsü, canlılık ham verisi veya benzeri hiçbir alan bu API'de tanımlı değildir. Gönderilen tek şey karardır. Bu, KVKK m.4/2-ç veri minimizasyonu ilkesinin doğrudan uygulanmasıdır.

Idempotent upsert: Anahtar (sessionSourcedId, userSourcedId). Aynı çift yeniden gönderilirse kayıt güncellenir, çift kayıt oluşmaz.

Kısmi başarı yanıtı: 207 Multi-Status

{
  "accepted": 118,
  "rejected": 2,
  "errors": [
    { "userSourcedId": "USR-99999999",
      "code": "user_not_enrolled",
      "message": "Kullanıcı bu şubeye kayıtlı değil." }
  ]
}

7.3 Oturum kapatma — PATCH /attendance/sessions/{sourcedId}

{ "endedAt": "2026-09-22T11:47:03+03:00", "status": "finalized" }

status: open · finalized · voided

Değiştirilebilirlik: Kurum, kapatılmış bir oturumun ne kadar süre düzeltilebileceğini kendi politikasıyla belirler. İstemci 409 Conflict alırsa düzeltmeyi kendi tarafında tutar ve öğretmeni uyarır.

7.4 Okuma / mutabakat — GET /attendance/records

?sectionSourcedId=…&from=2026-09-21&to=2027-01-16

Uygulama kendi kayıtlarıyla ÖBS'yi karşılaştırıp fark raporu üretir. Bir yoklama sisteminin en çok güven kazandıran özelliği budur.

8. Kademeli uyum yolu

Kurumlar her şeyi bir anda yapmak zorunda değildir:

Uygulama Seviye 0'da da tam işlevseldir. Bu, spesifikasyonun benimsenmesini kolaylaştırır — kurum riski görmeden yatırım yapmak zorunda kalmaz.

9. CSV/Excel yedek formatı (Seviye 0)

API yoksa. Bu bir yedek plan değil, temel özelliktir — vakaların çoğunda tek çalışan yol bu olacaktır.

Tam mod (OneRoster CSV uyumlu):

orgs.csv         sourcedId, name, type, parentSourcedId
terms.csv        sourcedId, title, type, startDate, endDate, schoolYear
courses.csv      sourcedId, title, courseCode, orgSourcedId
sections.csv     sourcedId, title, sectionCode, courseSourcedId, termSourcedId
classrooms.csv   sourcedId, name, building, capacity, type
users.csv        sourcedId, username, givenName, familyName, role, identifier, email
enrollments.csv  sourcedId, sectionSourcedId, userSourcedId, role, primary
schedules.csv    sourcedId, sectionSourcedId, classroomSourcedId, dayOfWeek, startTime, endTime

Basit mod — tek dosya, çoğu okulun ÖBS'sinden doğrudan alabileceği:

ogrenci_no, ad, soyad, ders_kodu, sube, donem

Import gereksinimleri:

• Sütun eşleme sihirbazı — sabit format dayatılmaz, kullanıcı hangi sütunun ne olduğunu seçer
• UTF-8 ve Windows-1254 desteği; Türkçe karakter testi (ı, İ, ş, Ş, ğ, Ğ, ö, Ö, ç, Ç, ü, Ü)
• Kuru çalıştırma (dry-run) önizlemesi — kaç kayıt eklenecek/güncellenecek/hatalı
• Idempotent upsert — aynı dosya iki kez yüklenirse çift kayıt olmaz
• Satır bazlı, indirilebilir hata raporu — "43. satır: öğrenci no boş"
• Silme asla otomatik olmaz — dosyada olmayan öğrenci pasife alınır, silinmez
• Yoklama ÇIKIŞI — Excel/PDF/CSV export, okulun kendi ÖBS'sine elle girmesi için. K-12'de en çok kullanılacak özellik budur.

10. Mevcut sistemlere eşleme

Kurum bu spesifikasyonu implement etmeden de bağlanabilir; uygulama şu adaptörleri içerir:

⛔ e-Okul / MEBBİS — mutlak kırmızı çizgi

MEB Bilgi İşlem Genel Müdürlüğü'nün 29.06.2026 tarih ve 162807709 sayılı yazısı, Bakanlık sistemlerinde yetkisiz üçüncü parti yazılım, bot, makro, otomasyon aracı, tarayıcı eklentisi veya veri çekme aracı kullanımını yasaklıyor ve "sistem log kayıtları üzerinden tek tek belirlenerek hem idari hem adli soruşturma açılacaktır" diyor.

K-12 için tek meşru mimari: okul yetkilisinin kendi yetkisiyle e-Okul'dan indirdiği Excel/PDF çıktısından manuel import; yoklama uygulamada tutulur; öğretmen sonucu e-Okul'a kendisi girer. Ürün asla "e-Okul'a otomatik yazar" diye tanıtılmayacaktır.

⚠️ Bu yazının birincil metnine erişilemedi; çoklu eğitim haber kaynağı tutarlı biçimde raporluyor. Tarih ve sayı teyit edilmeli — ama fiilî yasak yönünde tereddüt yok.

11. Neden sunucuda şifre saklamıyoruz

Alternatif tasarım "öğretmen ÖBS şifresini uygulamaya girer, biz onun adına giriş yaparız" idi. Reddedildi:

1. Geri döndürülebilir şifreleme zorunluluğu. Şifreyi ÖBS'ye tekrar sunmak gerektiği için hash'lenemez; anahtar sistemde bulunmak zorunda. Anahtar ele geçerse tüm öğretmen şifreleri açık metne döner.
2. Şifre tekrar kullanımı. Öğretmenin ÖBS şifresi büyük olasılıkla e-posta, e-Devlet veya banka şifresiyle aynı/benzerdir. Bizdeki bir ihlal, e-Devlet hesap ele geçirme zincirine dönüşür.
3. TCK 243/244. Devlet üniversiteleri ve MEB kamu kurumudur → m.244/3 ceza yarı oranında artırılır. Öğretmenin şifresini vermesi, size kurumdan yetki vermez; yetki sistemin sahibi kurumdan gelir.
4. Sektörel emsal. Bu tartışma finans sektöründe yaşandı ve kaybedildi: CFPB'nin 1033 kuralı screen scraping'i "still common but risky practice" diyerek hedef aldı; PSD2 aynısını düzenlenmiş API erişimiyle değiştirdi. Eğitim sektörünün finanstan daha az hassas olduğunu varsaymayın — burada reşit olmayan çocukların verilerinden bahsediyoruz.

⚠️ TCK madde metinleri birincil kaynaktan doğrulanmadı; ceza hukuku değerlendirmesi için hukukçu görüşü alınmalıdır.

Cihazda saklama farklı bir şeydir

Yukarıdaki gerekçelerin tamamı sunucuda merkezî kimlik bilgisi saklamaya ilişkindir. Kısıtlı bir seviyede (bkz. ADR-003) uygulama, öğretmenin ÖBS şifresini yalnızca kendi cihazında, Keystore/Keychain destekli güvenli depoda, kullanımı biyometrik/cihaz kilidine bağlı olarak ve isteğe bağlı biçimde saklayabilir — tarayıcıların parola yöneticileriyle aynı model.

Fark belirleyicidir: patlama yarıçapı N okul × M öğretmen değil, tek bir cihazdır; sunucu ihlali şifre ihlali değildir; anahtar merkezî bir tek hata noktası oluşturmaz.

Bu API'yi implement eden kurumlarda bu konu hiç gündeme gelmez — OAuth 2.0 Client Credentials ile hiçbir kullanıcı şifresi işin içine girmez. Referans API'nin varlık sebeplerinden biri budur.

12. Uyum kontrol listesi (kurumlar için)

• [ ] /.well-known/yoklama-configuration yayında, yetenekler doğru beyan edilmiş
• [ ] OAuth 2.0 Client Credentials çalışıyor, kapsamlar ayrık
• [ ] TLS 1.2+, geçerli sertifika
• [ ] /users, /sections, /enrollments doğru veri dönüyor
• [ ] Türkçe karakterler UTF-8 olarak doğru dönüyor
• [ ] ?since= artımlı çekim çalışıyor
• [ ] ETag / If-None-Match destekleniyor
• [ ] Sayfalama ve X-Total-Count doğru
• [ ] Hatalar RFC 9457 formatında
• [ ] POST /attendance/records idempotent (aynı istek iki kez → tek kayıt)
• [ ] 207 Multi-Status kısmi başarı doğru raporlanıyor
• [ ] Hız sınırlama başlıkları mevcut
• [ ] Veri işleyen sözleşmesi imzalandı, KVKK rolleri netleştirildi

Referans implementasyon ve test paketi: services/api/reference/ (planlanmış — Faz 1)

13. Sürüm politikası

Semantic versioning. Kırıcı değişiklikler yalnızca ana sürümde ve yeni base path ile (/yoklama-api/v2). v1 en az 24 ay desteklenir. Yeni opsiyonel alan eklemek kırıcı değildir; istemciler bilmedikleri alanları yok saymalıdır.

14. Katkı ve geri bildirim

Bu spesifikasyon akademik bir projenin çıktısıdır ve CC BY 4.0 ile serbestçe kullanılabilir. Türkiye'de eğitim verisi birlikte çalışabilirliği için bir başlangıç noktası olması amaçlanmıştır. Kurumların, ÖBS sağlayıcılarının ve diğer yoklama ürünlerinin kullanmasında sakınca yoktur — aksine hedeflenen budur.

Makine tarafından okunabilir tanım: openapi.yaml

Bu sayfa depodaki docs/api/README.md dosyasından scripts/belgeleri-uret.py ile üretilir. Elle düzenlenmez; değişiklik kaynağa yapılır.