PBS Teknik Şartname

Bu sayfadaki değerler PBS sunucu kodundan alınmıştır. Ayarlanabilir değerlerde varsayılan ve izin verilen aralık birlikte yazılır.

Mimari

Çalışma biçimi: Çok kiracılı bulut yazılımı. Her kurumun verisi ayrı kiracı kaydıyla tutulur; bir kurum başka kurumun verisini göremez.
Arayüzler: Yönetim paneli (web), kiosk ekranı (web, tablet ya da bilgisayar tarayıcısı), telefon tarayıcısından okutma ve iOS/Android uygulaması (hazırlanıyor).
API adresi: https://api.ankarayazilim.org/v1/saas/pbs
Yanıt biçimi: JSON. Başarıda success: true ve data, hatada success: false ve error { code, message }.
Kimlik doğrulama: Ankara Yazılım hesabı. Panel oturum çerezi, mobil uygulama Bearer jetonu kullanır. Kiosk uçları kiosk cihaz anahtarını X-PBS-Kiosk-Key başlığında taşır.
Panel: https://panel.ankarayazilim.org/panel/w/pbs

İçerik: 32 bayt rastgele jeton, işyeri kimliği, bitiş zamanı ve 16 bayt rastgele nonce. Yük HMAC-SHA256 ile imzalanır.
Ömür: 30 saniye. İstemci ile sunucu saati arasında en çok 5 saniye fark tolere edilir.
Tek kullanım: Sunucu yalnızca jetonun SHA-256 özetini saklar. Okutulduğunda kayıt kullanıldı olarak işaretlenir; aynı karekod ikinci kez kabul edilmez (QR_USED).
Kiosk cihaz anahtarı: 24 bayt rastgele anahtar. Sunucuda yalnızca SHA-256 özeti tutulur; anahtar oluşturulurken bir kez gösterilir. Cihaz iptal edilince okunmamış karekodlar geçersiz olur.
İstek sınırı: Karekod ucu kiosk anahtarı başına saniyede 1 istek kabul eder.

Şifreleme: AES-256-GCM ile şifrelenir, ayrıca HMAC-SHA256 ile imzalanır. İçinde kiracı, kullanıcı ve zaman penceresi bulunur.
Pencere: 15 saniye. Sunucu bir pencere öncesini ve bir pencere sonrasını tolere eder.
Tek kullanım: Her pencere kişi başına bir kez kullanılabilir. Aynı penceredeki ikinci okutma QR_REPLAY ile reddedilir; ekran görüntüsü işe yaramaz.

Kart türleri: 125 kHz RFID, Mifare Classic, DESFire, NFC telefon ve statik karekod kartı.
UID saklama: Kart numarası düz metin saklanmaz. Sunucudaki gizli anahtardan her kuruma özel bir anahtar türetilir ve UID bu anahtarla HMAC-SHA256 özetine çevrilir. Ekranda yalnızca son 4 hane görünür.
Okuyucu: USB masaüstü okuyucu (klavye gibi çalışan tür), NFC özellikli Android/iOS cihaz ya da donanım terminali. Terminaller device-ingest ucuna employeeNumber veya cardUid gönderir.
Kart ucu hata kodları: KART_UID_GECERSIZ, KART_TANIMSIZ, KART_PASIF, KART_SURESI_DOLDU, COOLDOWN, METHOD_DISABLED, ON_LEAVE.
İstek sınırı: Kiosk anahtarı başına 10 saniyede en çok 20 kart okuma.

Aşağıdaki değerlerin tamamı kurum yöneticisi tarafından Ayarlar ekranından değiştirilir. Yeni açılan kurumlarda varsayılanlar geçerlidir.

Kural	Varsayılan	Aralık
Sunucu saati	Her zaman açık	Kayıt saatini sunucu yazar
Sıkı doğrulama	Açık	Açık / kapalı
Telefon eşleme (cihaz bağlama)	Açık	Açık / kapalı
Sahte konum engeli	Açık	Açık / kapalı
Şüpheli okutmayı engelle	Kapalı	Açık / kapalı
Bekleme süresi (art arda okutma)	60 saniye	30 – 3600 saniye
Konum doğruluk üst sınırı	100 metre	20 – 500 metre
Çevrimdışı okutma kabul süresi	72 saat	0 – 168 saat (0 = kapalı)
Geç kalma toleransı	5 dakika	0 – 60 dakika
İşyeri konum çiti yarıçapı	100 metre	En az 10 metre

Konum çiti: Telefon konumu ile işyeri koordinatı arasındaki mesafe Haversine formülüyle (yer yarıçapı 6.371 km) hesaplanır. Konum doğruluğu ayarlanan üst sınırdan kötüyse okutma reddedilir; aksi halde doğruluk payı çembere eklenir.
Telefon eşleme: İlk mobil okutma telefonu kullanıcıya bağlar. Farklı telefon DEVICE_NOT_BOUND ile reddedilir. Tarayıcıdan okutma eşleme açıkken DEVICE_REQUIRED ile reddedilir. Sıfırlamayı yönetici yapar.
Sahte konum: Uygulama konumun sahte olduğunu bildirirse GEO_MOCKED döner ve kayıt oluşmaz.
Şüpheli okutma işaretleri: Ortak cihaz parmak izi, aynı kioskta kısa sürede birden çok kişinin okutması ve imkânsız yolculuk (en az 500 metre, en az 60 saniye, 120 km/sa üstü hız). İşaretler kayda yazılır; “şüpheli okutmayı engelle” açıksa FRAUD_BLOCKED ile reddedilir.
Diğer kontroller: İşyeri bazında izinli IP listesi, onaylı izindeki personelin okutmasını engelleme (ON_LEAVE) ve okutma yöntemi anahtarları: mobil, kiosk tarama, kiosk gösterim, kart. En az bir yöntem açık kalmalıdır.

Yetki kontrolü sunucuda yapılır. Yetkisiz istek HTTP 403 ve FORBIDDEN ile reddedilir; ekranın gizlenmesine güvenilmez.

Yetki	Kurum Yöneticisiyonetici	Kart Sorumlusukart_sorumlusu	Birim Yöneticisibirim_yetkilisi	Denetçi (salt okuma)salt_okuma	Personelpersonel
Ayarlarpbs.settings.manage	Var	–	–	–	–
Personel yönetimipbs.employees.manage	Var	–	–	–	–
Personel listesi (temel)pbs.employees.read_basic	Var	Var	–	–	–
İşyerleripbs.sites.manage	Var	–	–	–	–
Kiosk cihazlarıpbs.kiosk.manage	Var	–	–	–	–
Kartlarpbs.cards.manage	Var	Var	–	–	–
Telefon eşleme sıfırlamapbs.devices.manage	Var	–	–	–	–
Vardiyapbs.shifts.manage	Var	–	–	–	–
Anlık durumpbs.live.read	Var	–	Var	Var	–
Tüm devam kayıtlarıpbs.attendance.read_all	Var	–	Var	Var	–
Kayıt düzeltmepbs.attendance.correct	Var	–	–	–	–
İzin onayıpbs.leave.approve	Var	–	Var	–	–
Eksik okutma onayıpbs.missed_punch.approve	Var	–	Var	–	–
Raporlarpbs.reports.read	Var	–	Var	Var	–
Puantajpbs.timesheet.read	Var	–	–	Var	–
Kendi giriş çıkışıpbs.punch.self	Var	Var	Var	–	Var
Kapsam	Tüm kurum	Tüm kurum	Kendi birim(ler)i; birimi yoksa tüm kurum	Tüm kurum	Yalnızca kendi kayıtları

Puantaj uyarıları: Yıllık fazla mesai sınırı 270 saat; yılbaşından bugüne toplam sınırın %90’ına ulaşınca uyarı verilir. Ardışık iş günleri arasında 11 saatten kısa dinlenme (ayarlanabilir: 1 – 24 saat) ihlal olarak işaretlenir.
Dışa aktarma: Devam raporu (günlük ve haftalık) CSV ve XLSX. Puantaj XLSX ve bordro aktarım satırları. Her dışa aktarma denetim kaydına yazılır.
İçe aktarma: Personel listesi CSV veya XLSX ile yüklenir; tek seferde en çok 500 satır.
Talepler: İzin ve eksik okutma talepleri personelden açılır, yetkili rol onaylar ya da reddeder.

REST API: https://api.ankarayazilim.org/v1/saas/pbs/* uçları panelin kullandığı uçlarla aynıdır. Kapsam kullanıcının rolüne göre belirlenir.
Webhook: Olaylar kurumun belirlediği adrese gönderilir. İstek gövdesi HMAC-SHA256 ile imzalanır ve imza x-pbs-signature başlığında sha256=… biçiminde gelir.Webhook ayrıntıları
Donanım terminali: Kiosk anahtarıyla device-ingest ucuna personel numarası ya da kart UID’si gönderilir.

Denetim kaydı: Elle düzeltme, onay ve ayar değişiklikleri denetim kaydına kimin ne zaman yaptığıyla yazılır.
Veri sahibi talepleri: Personel uygulamadan bilgi, düzeltme, silme ve itiraz talebi açar. Talep durumu açık, işlemde, tamamlandı ya da reddedildi olarak izlenir; yanıt süresi 30 gündür. Personel kendi verisinin dışa aktarımını da alabilir.
Saklama: Devam kayıtları varsayılan olarak 5 yıl saklanır; süre 1 ile 10 yıl arasında ayarlanır. Süresi dolan kayıtlar toplu işle silinir.
Aydınlatma metni: Kurum oluşturulurken KVKK aydınlatma metni onayı zorunludur.KVKK Aydınlatma Metni

Başlangıç: 10 aktif personele kadar ücretsiz. Kurum oluşturulurken tanımlanır.
Kurum sayısı: Bir hesapla en fazla 3 kurum oluşturulabilir.
Kapsam dışı: PBS bordro hesaplamaz; puantajı hazırlar ve bordro programına aktarılmak üzere dışa verir.

Şartnamenizdeki bir maddeyi bu sayfada bulamadıysanız bize yazın; koddaki karşılığını birlikte kontrol edelim.