IDV
Giriş Yap

Akış & Kontrol Listesi

Bir doğrulama oturumu baştan sona nasıl işler?

Bu sayfa, son kullanıcı akışa girdiği andan imzalı webhook'un sisteminize ulaştığı ana kadar olan her adımı, o adımda çalışan kontrolleri ve kararın hangi sayılarla verildiğini gösterir.

Aşağıdaki tüm ağırlıklar, eşikler ve limitler platformda fiilen uygulanan değerlerdir; tenant bazında yalnızca katılaştırılabilir, gevşetilemez.

8
Akış adımı — oturum açılışından webhook teslimine
18
Ayrı belge kontrolü — 15 puanlı + 3 sert kural
5
Belge profili — her biri kendi ağırlık setiyle
3
Canlılık katmanı — aktif, pasif ML, sezgisel

Adım adım

Oturum akışı

Foto ve NFC yolları 3. adıma kadar aynıdır; 4. adımda ayrılır ve 5. adımda yeniden birleşir.

Adımları kim yürütürEntegratör sistemiSon kullanıcıIDV platformu
  1. Entegratör sistemi

    Oturum oluşturma

    Sisteminiz sunucu tarafından bir doğrulama oturumu açar. Tenant API anahtarı yalnızca bu çağrıda kullanılır ve hiçbir zaman tarayıcıya inmez. Yanıt olarak dönen session_id, dışarıya açılan tek kullanıcı tanımlayıcısıdır.

    POST /v1/sessions · X-Api-Key · durum: created

    Bu adımda çalışan kontroller

    • Hız (velocity) limiti: aynı başvuru sahibi için 24 saatte en fazla 5 oturum
    • Hız limiti: aynı IP için 24 saatte en fazla 20 oturum
    • Production oturumlarında tenant bakiye kontrolü
    • Yeniden kullanılabilir KYC: 180 günden yeni, AML uyarısız onaylı doğrulama varsa tekrar sorulmaz
  2. Son kullanıcı

    Akışın açılması

    Kullanıcı WebSDK'yı (iframe) veya mobil SDK'yı açar. SDK, API anahtarı yerine yalnızca o oturuma özel, varsayılan 15 dakika geçerli kısa ömürlü bir JWT ile çalışır. Tenant teması ve dili (TR/EN) bu adımda uygulanır.

    GET /v1/sessions/{id}/config · kısa ömürlü JWT (15 dk) · CORS izin listesi

    Bu adımda çalışan kontroller

    • Oturum geçerlilik süresi: 60 dakika (aşımında durum expired'a geçer)
    • Tenant bazlı CORS izin listesi — SDK yalnızca tanımlı origin'lerden yüklenebilir
    • Aktif modüller (belge / canlılık) oturum konfigürasyonundan okunur
  3. Son kullanıcı

    Belge seçimi ve çekim

    Kullanıcı belge tipini seçer ve kamerayla çeker. Kart kenarları otomatik algılanıp kırpılır; çok bulanık veya karanlık kareler cihazda uyarı üretir, sunucuya gitmeden tekrar çekim istenir. NFC yolunda önce MRZ kamerayla taranır — çipin kilidini açan anahtar MRZ'den türetilir.

    POST /v1/sessions/{id}/access-keys · POST /{id}/documents/images

    Bu adımda çalışan kontroller

    • Desteklenen tipler: TC kimlik kartı, pasaport, sürücü belgesi, ikamet izni, Gana kimlik kartı
    • Belge profili gerektiriyorsa arka yüz zorunludur (TD1 MRZ arka yüzdedir)
    • Cihaz tarafı kalite kapıları: netlik, parlaklık, kadraj
  4. IDV platformuFoto yolu

    Belge analizi

    Oturum document_processing durumuna geçer ve arka plan işçisi görselleri analiz eder: PP-OCR ile alan okuma, OCR-B için kalibre edilmiş ayrı bir yolla MRZ çözümü, ICAO 9303 check digit doğrulaması, ELA ve doku analizi ile manipülasyon tespiti. Her kontrol 0–100 skor üretir; profil ağırlıklarıyla tek bir belge skoruna indirgenir.

    durum: document_processing → liveness_pending | review | rejected

    Bu adımda çalışan kontroller

    • 15 puanlı kontrol (aşağıdaki tabloda profil bazlı ağırlıklarıyla)
    • 3 ağırlıksız sert kural: dosya bütünlüğü, belge geçerlilik tarihi, örnek/specimen tespiti
    • Ön ve arka yüz arasında çapraz veri tutarlılığı (MRZ ↔ basılı alanlar)
  5. IDV platformuNFC yolu

    Çip okuma ve pasif doğrulama

    eMRTD uyumlu belgelerde çipe BAC ile kurulan şifreli kanal (Secure Messaging) üzerinden erişilir; DG1 (MRZ), DG11 ve DG12 veri grupları okunur. ICAO 9303 Passive Authentication iki şeyi kanıtlar: SOD içindeki hash'ler verinin değişmediğini, Document Signer sertifikası ise verinin gerçekten devlet tarafından yazıldığını gösterir.

    POST /{id}/documents/nfc · durum: nfc_processing → liveness_pending | review

    Bu adımda çalışan kontroller

    • SOD hash bütünlüğü — her veri grubu için ayrı doğrulanır
    • Document Signer sertifika imzası, CSCA güven zinciriyle doğrulanır
    • Çip verisi ile beyan edilen belge no / doğum tarihi / son geçerlilik karşılaştırılır — uyuşmazlık manuel incelemeye düşer (çip otoritedir)
  6. IDV platformu

    AML / yaptırım taraması

    Belgeden çıkarılan isim, günlük senkronize edilen açık yaptırım listelerine karşı taranır. İsimler normalize edilir (aksan ve Türkçe karakter sadeleştirme), bulanık eşleştirme skoru %90 ve üzeri olan kayıtlar aday sayılır, doğum yılı uyuşmazlığı olan adaylar elenir.

    rapidfuzz token_sort_ratio ≥ %90 · eşleşme → durum: review

    Bu adımda çalışan kontroller

    • OFAC SDN (ABD Hazine), UN Consolidated, EU FSF listeleri
    • Doğum yılı çakışma kontrolü ile yanlış pozitif elemesi
    • Eşleşme asla otomatik red üretmez — karar insana bırakılır
  7. Son kullanıcı

    Canlılık testi ve yüz eşleştirme

    Sunucu rastgele 3–4 adımlık bir challenge sekansı üretir (en az bir göz kırpma ve bir baş hareketi garanti edilir) ve bunu tek kullanımlık bir kimlikle birlikte verir. Kullanıcı her challenge için bir kare ve bir selfie gönderir; sunucu her kareyi ilgili challenge türüne göre bağımsız doğrular, ardından selfie'yi belge fotoğrafıyla biyometrik olarak karşılaştırır.

    POST /{id}/liveness/start → /{id}/liveness/submit · challenge TTL 300 sn

    Bu adımda çalışan kontroller

    • Aktif challenge'ların tamamı geçmelidir — tolerans yok
    • Kareler arası tutarlılık: aynı kişi mi, statik tekrar var mı
    • Pasif anti-spoofing (MiniFASNet ensemble) + sezgisel LBP/FFT/YCrCb sinyalleri
    • ArcFace embedding ile belge fotoğrafı–selfie karşılaştırması
    • Onaylanan yüz pgvector'a yazılır; aynı yüz farklı kimlikle gelirse duplikat sinyali üretilir
  8. IDV platformu

    Karar ve teslim

    Tüm katmanların sonucu tek bir terminal duruma indirgenir. Karar ne olursa olsun her durum geçişi zaman damgalı olay kaydına yazılır. Sonuç, HMAC-SHA256 ile imzalanmış bir webhook ile sisteminize iletilir; ayrıca sonuç endpoint'inden her zaman okunabilir.

    webhook · X-Idv-Signature: hmac-sha256=… · GET /{id}/result

    Bu adımda çalışan kontroller

    • Terminal durumlar: approved, review, rejected, expired
    • Reddedilen oturumda kullanıcıya 3 yeniden deneme hakkı tanınır
    • Webhook teslimi başarısız olursa yeniden denenir; teslim kayıtları saklanır
    • Kişisel veriler terminal duruma geçişten 90 gün sonra otomatik silinir

Durum makinesi

Oturum durumları

Bir oturum yalnızca tanımlı geçişleri yapabilir; her geçiş audit kaydına yazılır ve geriye dönüş yoktur. Bu, aynı adımın tekrar gönderilmesiyle yapılan replay denemelerini yapısal olarak engeller.

  1. created

    Oluşturuldu

    Oturum açıldı, kullanıcı akışa henüz girmedi.

  2. document_pending

    Belge bekleniyor

    SDK açık, belge yüklemesi bekleniyor.

  3. document_processing

    Belge inceleniyor

    Görsel kontrolleri ve OCR/MRZ çözümü çalışıyor.

  4. nfc_processing

    Çip inceleniyor

    NFC yolunda çip verisi ve pasif doğrulama işleniyor.

  5. liveness_pending

    Canlılık bekleniyor

    Belge geçti, challenge sekansı bekleniyor.

  6. liveness_processing

    Canlılık inceleniyor

    Aktif/pasif katmanlar ve yüz eşleştirme çalışıyor.

  7. approved

    Onaylandı

    Tüm kontroller geçti — kimlik doğrulandı.

  8. review

    Manuel inceleme

    Otomatik karar verilemedi; operatör kararı bekleniyor.

  9. rejected

    Reddedildi

    Bir veya daha fazla kontrol kesin olarak başarısız.

  10. expired

    Süresi doldu

    Oturum 60 dakika içinde tamamlanmadı.

Belge motoru

Kontrol listesi ve ağırlıkları

Her belge tipinin kendi ağırlık seti vardır — pasaportta MRZ'nin payı en yüksekken, MRZ'si olmayan sürücü belgesinde metin okunabilirliği öne çıkar. Aşağıdaki yüzdeler, tüm kontrollerin çalıştığı durumdaki katkı paylarıdır.

Kontrol listesi ve ağırlıkları
KontrolTC KimlikPasaportSürücü B.İkamet İzniGana Kimlik
MRZ DoğrulamasıICAO 9303 makine okunabilir alan: check digit'ler ve alan tutarlılığı.19.5%27.1%—25.3%23.5%
Metin OkunabilirliğiBelgeye özgü anahtar kelime gruplarının OCR ile bulunma oranı.8.8%10.4%19.8%12.6%9.8%
Netlik / OdakLaplacian varyansı ile bulanıklık ölçümü.8.8%10.4%12.3%10.5%9.8%
Manipülasyon (ELA)Error Level Analysis: yeniden kaydedilmiş / düzenlenmiş bölge izleri.7.1%8.3%9.9%8.4%7.8%
Yüz TespitiBelgede biyometrik portrenin varlığı ve konumu.7.1%8.3%9.9%8.4%7.8%
Ekran/Baskı TespitiFFT periyodik tepe analizi ile moiré deseni — ekrandan çekim.7.1%8.3%9.9%8.4%7.8%
Belge ÇerçevesiID-1 dikdörtgen kenar tespiti ve 1.586:1 en-boy oranı.5.3%6.3%7.4%6.3%5.9%
Parlaklık & ParlamaAşırı karanlık, yanmış veya flaş parlamalı kareler.4.4%5.2%6.2%5.3%4.9%
Yerel Doku TutarlılığıBölgesel doku sapması — alan bazlı montaj tespiti.4.4%5.2%6.2%5.3%4.9%
ÇözünürlükMinimum 600×400 piksel okunabilirlik tabanı.2.7%3.1%3.7%3.2%2.9%
TC Kimlik No AlgoritmasıTC Kimlik numarasının matematiksel checksum doğrulaması.8.0%—14.8%——
Gana Kimlik No (PIN)GHA-XXXXXXXXX-X formatı ve MRZ ile çapraz kontrolü.————8.8%
Renk İmzasıTC Kimlik kartının firuze/pembe baskı renk imzası.7.1%————
Mikro YazıArka yüzdeki tekrarlayan ince baskı deseninin varlığı.4.4%————
Veri TutarlılığıMRZ alanları ile ön yüzdeki basılı alanların çapraz karşılaştırması.5.3%7.3%—6.3%5.9%

Bir kontrol yapılamadıysa (örneğin arka yüz yoksa MRZ) skora hiç girmez; kalan kontrollerin payları kendi aralarında yeniden ölçeklenir. Böylece eksik veri, düşük skor gibi davranmaz.

Ağırlıksız sert kurallar

Bu üç kontrol puana girmez; sonucu doğrudan belirler. Skor 100 bile olsa bunlardan biri başarısızsa oturum otomatik onay almaz.

  • Dosya Bütünlüğü

    Bozuk, boş veya 5 KB'tan küçük dosya — diğer kontroller çalıştırılmaz.

  • Belge Geçerliliği

    MRZ'den doğrulanmış son geçerlilik tarihi geçmişse kesin ret.

  • Örnek/Specimen Tespiti

    Numune belge işaretleri ve bilinen örnek belge numaraları.

Puanlama

Karar nasıl veriliyor?

Her kontrol 0–100 arası bir skor üretir. Belge skoru, çalışan kontrollerin ağırlıklı ortalamasıdır ve üç karar bandından birine düşer.

Belge skoru

Σ (kontrol skoru × ağırlık) ÷ Σ (ağırlık)

Eşikler tenant bazında yükseltilebilir, düşürülemez — kural motoru her değeri global tabana clamp'ler.

  • ≥ 70Otomatik devamBelge geçti; akış canlılık adımına ilerler (belge-only modülde doğrudan onay).
  • 45 – 69Manuel incelemeBelge algılandı ama tam doğrulanamadı; operatör kararına düşer.
  • < 45Otomatik redKontroller belgenin geçerliliğini desteklemiyor.

Skoru ezen sert kurallar

Bu durumlarda ağırlıklı skor ne olursa olsun karar aşağıdaki gibidir.

  • Yüz var, metin yok → red

    Belge yerine selfie yükleyen kullanıcıyı yakalar. MRZ doğrulandıysa bu kural devre dışı kalır (gerçek kart yanlışlıkla reddedilmesin).

  • Hiç belge kanıtı yok → red

    Yüz, okunabilir metin ve MRZ üçü de yoksa bu bir kimlik belgesi değildir; inceleme bandındaki skor bile redde çevrilir.

  • Belge süresi dolmuş → red

    Son geçerlilik tarihi MRZ check digit'i ile doğrulanmış ve geçmişse kesin ret.

  • Örnek/specimen belge → red

    Kesin numune işareti redde; zayıf/belirsiz işaret otomatik onay yerine manuel incelemeye gider.

  • Kimlik no çapraz kontrolü başarısız → inceleme

    İki farklı kartın yüzlerinin birleştirilmesi (montaj) saldırısı yalnızca çapraz karşılaştırmayla görünür; otomatik onay engellenir, karar insana gider.

  • AML eşleşmesi → inceleme

    Yaptırım listesi eşleşmesi hiçbir koşulda otomatik red üretmez.

  • Duplikat yüz → inceleme

    Aynı yüz daha önce farklı bir kimlikle onaylanmışsa oturum insana yönlendirilir.

  • Çip/beyan uyuşmazlığı → inceleme

    NFC çipindeki değer beyan edilenden farklıysa çip otorite kabul edilir ve oturum incelemeye düşer.

Canlılık

Üç katmanlı canlılık güvencesi

Katmanlar birbirini tamamlar: aktif katman kullanıcının gerçekten orada olduğunu, pasif katman kameranın karşısındakinin ekran veya baskı olmadığını, sezgisel katman ise bu ikisinin kaçırdığı artefaktları arar.

  1. 1

    Aktif challenge

    Sunucu rastgele bir sekans üretir (göz kırpma, baş çevirme). Her kare ilgili challenge türüne göre sunucuda bağımsız doğrulanır — istemcinin 'geçti' demesi yeterli değildir.

    MediaPipeHaar cascadeBaş pose

  2. 2

    Pasif anti-spoofing

    MiniFASNet ensemble: baskı, ekran replay ve moiré artefaktlarına duyarlı iki bağımsız model, tek bir gerçeklik olasılığı üretir.

    MiniFASNetV2MiniFASNetV1SEONNX

  3. 3

    Sezgisel sinyaller

    Doku, frekans ve renk uzayı sezgileri (LBP / FFT / YCrCb) ile kareler arası tutarlılık ve optik akış tabanlı hareket analizi ikincil sinyal olarak değerlendirilir.

    LBPFFTOptical flow

Canlılık güven skoru

(pasif skor × 0.35 + yüz eşleşme × 0.65) × 100

Ağırlığın üçte ikisi yüz eşleşmesinde: gerçek bir yüz, belgedeki kişiye ait değilse yüksek pasif skor oturumu kurtarmaz. Bu skor tek başına da yeterli değildir — yanındaki kapıların tamamı ayrıca geçilmelidir.

Geçmesi gereken kapılar

Aktif challenge
tamamıEksik veya başarısız tek kare bile oturumu düşürür; kullanıcı yeniden deneyebilir.
Pasif skor tabanı
≥ 0.40Ensemble gerçeklik olasılığının alt sınırı.
Anti-spoof kapısı
≥ 0.55Ensemble 'gerçek yüz' olasılığı eşiği.
Güven skoru
≥ 60Birleşik canlılık güven skoru alt sınırı (tenant yükseltebilir).
Challenge süresi
300 snTek kullanımlık challenge kimliğinin geçerlilik süresi — replay penceresini kapatır.

Yüz eşleştirme ve duplikat tespiti

Belge fotoğrafı ve selfie, ArcFace embedding'leri üzerinden karşılaştırılır. Onaylanan her yüz vektör veritabanına yazılır; böylece aynı yüzün farklı kimliklerle tekrar kayıt olması yakalanır.

  • 0.55

    Eşleşme eşiği

    Belge fotoğrafı ile selfie arasındaki kosinüs benzerliği alt sınırı.

  • 0.60

    Kalite kapısı

    SCRFD tespit skoru — bulanık veya kısmi yüzlerden embedding üretilmez.

  • 0.75

    Duplikat eşiği

    Normalize kosinüs; üstü 'aynı kişi' şüphesidir ve manuel incelemeye düşer.

AML

Yaptırım listesi taraması

Tarama yalnızca kamuya açık listelerle yapılır; kimlik verisi üçüncü taraf ticari bir veri satıcısına gönderilmez. Listeler günlük bir cron ile indirilip yerel veritabanına yazılır.

  • OFAC SDN

    ABD Hazine Bakanlığı — Specially Designated Nationals listesi (CSV).

  • UN Consolidated

    Birleşmiş Milletler konsolide yaptırım listesi (XML).

  • EU FSF

    Avrupa Birliği Financial Sanctions Files (CSV).

  • PEP (opsiyonel)

    Operatörün sağladığı siyasi nüfuz sahibi kişiler veri kaynağı — tanımlı değilse atlanır.

Eşleştirme nasıl çalışır

  1. 1İsim normalize edilir: aksanlar ve Türkçe karakterler sadeleştirilir, yalnız A–Z ve tek boşluk bırakılır.
  2. 2rapidfuzz token_sort_ratio ile bulanık eşleştirme yapılır; kelime sırası farkı eşleşmeyi bozmaz.
  3. 3Skor %90 ve üzerindeki kayıtlar aday olarak alınır.
  4. 4Adayın doğum yılı, belgeden okunan doğum yılıyla çelişiyorsa eşleşme elenir (yanlış pozitif filtresi).
  5. 5Kalan eşleşme varsa oturum manuel incelemeye düşer ve eşleşme detayları kayda yazılır.

Bir eşleşme hiçbir koşulda otomatik red üretmez. Yaptırım listelerinde aynı ada sahip kişiler bulunabildiği için nihai karar her zaman insana bırakılır.

Kötüye kullanım koruması

Limitler ve süreler

Tümü ortam bazında ayrı sayılır — sandbox testleri production limitini tüketmez.

5 / 24 sa
Oturum / başvuru sahibi
Aynı applicant_external_id ile açılabilecek günlük oturum sayısı.
20 / 24 sa
Oturum / IP
Aynı IP adresinden açılabilecek günlük oturum sayısı.
3
Yeniden deneme
Reddedilen bir oturumda kullanıcıya tanınan tekrar hakkı; aşımı 409 döner.
60 dk
Oturum ömrü
Tamamlanmayan oturum bu süre sonunda expired olur.
15 dk
SDK jetonu
WebSDK/mobil SDK'nın kullandığı kısa ömürlü JWT süresi.
180 gün
KYC yeniden kullanımı
Bu süreden yeni onaylı doğrulama tekrar istenmez (AML uyarısı yoksa).
90 gün
PII saklama
Terminal duruma geçişten sonra kişisel verinin otomatik silinme süresi.

Teslim

Sonucun sisteminize iletilmesi

Her durum değişikliği için ayrı bir olay üretilir. Webhook'lar HMAC-SHA256 ile imzalanır; teslim edilemezse yeniden denenir ve tüm teslim denemeleri kayıt altındadır.

  • document.verifiedBelge (veya çip) doğrulandı, akış canlılık adımına geçti.
  • document.review_requiredBelge otomatik doğrulanamadı veya AML eşleşmesi var — operatör kararı bekleniyor.
  • document.rejectedBelge kontrolleri kesin olarak başarısız.
  • liveness.failedCanlılık katmanlarından biri geçilemedi.
  • session.manual_reviewCanlılık geçti ancak duplikat yüz şüphesi var.
  • session.approvedTüm kontroller geçti — kimlik doğrulandı.

# webhook

X-Idv-Signature: hmac-sha256=9d41…

{ "event_type": "session.approved",

"session_id": "s_7f3a…",

"status": "approved",

"environment": "production" }

Webhook'a ek olarak sonuç her zaman GET /v1/sessions/{id}/result ile okunabilir; webhook kaçırıldığında akış tıkanmaz.

Önemli not

Bu sayfa platformun mevcut davranışını tarif eder. Eşikler ve limitler tenant sözleşmenizde daha katı değerlerle yapılandırılabilir; gevşetilmesi mümkün değildir.