Doğrulama Akışı

Oturum durumları, scope sözlüğü ve uçtan uca entegrasyon.

Oturum durumları#

Bir oturum şu durumlardan geçer:

Durum	Anlamı
`waiting`	Oturum açıldı, QR gösteriliyor.
`scanned`	Kullanıcı QR'ı okuttu.
`opened`	Kullanıcı onay ekranını açtı.
`approved`	Kullanıcı onayladı. Sonuç hazır.
`declined`	Kullanıcı reddetti.
`expired`	Süre doldu, kimse onaylamadı.
`completed`	Sonuç size teslim edildi.

approved ve completed dışındaki hiçbir durumda identity alanı dönmez.

Scope sözlüğü#

scope, kullanıcıdan istediğiniz alanların listesidir. Kullanıcı onay ekranında tam olarak bunları görür.

Tüm değerler JSON'da string olarak döner; aşağıdaki "Biçim" sütunu o string'in nasıl okunacağını söyler.

Scope	Onay ekranı	Biçim	Örnek
`openid`	Kimlik doğrulama (veri paylaşılmaz)	—	—
`identity.first_name`	Ad	string	`Ayşe`
`identity.last_name`	Soyad	string	`Yılmaz`
`identity.birth_date`	Doğum tarihi	ISO 8601 tarih: `YYYY-MM-DD`	`1990-04-17`
`identity.gender`	Cinsiyet	`m` veya `f`	`f`
`identity.nationality`	Uyruk	ISO 3166-1 alpha-2 ülke kodu	`TR`
`identity.national_id`	T.C. kimlik numarası	11 haneli string	`12345678901`
`identity.document_number`	Nüfus cüzdanı seri numarası	string	`A12B34567`
`identity.passport_number`	Pasaport numarası	string	`U01234567`
`email`	E-posta adresi	string, e-posta	`ayse@ornek.com`
`phone`	Telefon numarası	E.164	`+905551234567`
`address`	Adres	string, tek satır	`Bağdat Cad. No:1, İstanbul`
`avatar`	Profil görseli	mutlak `https` adresi	`https://cdn.globaltrust.id/…`
`age.over_18`	18 yaşından büyük mü (doğum tarihi paylaşılmaz)	`"true"` veya `"false"`	`"true"`

Biçimleri sunucu doğrulamaz#

Değerler kullanıcının kendi cihazından gelir. Sunucu bunları biçim açısından denetlemez — onay anında bir profili reddetmek, veriyi düzeltmez, yalnızca doğrulamayı başarısız kılardı. Yukarıdaki biçimler mobil uygulamanın uyduğu sözleşmedir; yine de kendi tarafınızda ayrıştırırken savunmacı davranın.

Bugün hangi alanlar gerçekten geliyor#

Sözlükteki her alan API tarafından kabul edilir, ancak hepsi henüz mobil uygulamada bir değere karşılık gelmiyor:

Durum	Alanlar
Canlıda teslim edildiği görüldü	`openid`, `identity.first_name`, `identity.last_name`, `identity.birth_date`, `identity.gender`, `identity.nationality`, `identity.national_id`, `identity.document_number`, `email`, `phone`
Henüz teslim edildiği görülmedi	`identity.passport_number`, `address`, `avatar`, `age.over_18`

Kurallar#

En az 1, en fazla 12 alan isteyebilirsiniz.
Tanımadığımız bir scope isteği reddedilir. Sessizce atlanmaz — çünkü atlansaydı, hiç gelmeyecek bir alanı bekliyor olurdunuz.
Tekrar eden alanlar teke indirilir, sıralamanız korunur.

identity. öneki bilerek vardır: değerin kimlik belgesinden geldiğini söyler. Kullanıcının kendi yazdığı bir ad ile belgeden okunan ad asla karıştırılmaz.

Yalnızca gerçekten gerekeni isteyin#

Onay ekranı ne kadar uzarsa, kullanıcı o kadar çok vazgeçer. Yaş sınırı kontrolü yapıyorsanız identity.birth_date yeterlidir; ad soyad istemeniz gerekmez.

Scope seçimi maliyeti de etkiler. Bir sorgulamanın kontör bedeli istenen alanlara göre değişir — ayrıntı için Kredi Paketleri.

Sonucu almanın üç yolu#

1. Webhook (sunucudan sunucuya — önerilen)#

Oturumu açarken webhook_url verin, sonuç hazır olduğunda size POST edelim. Bkz. Webhooks.

JSON

{
  "scope": ["identity.first_name"],
  "webhook_url": "https://sizin-siteniz.com/gti/webhook"
}

2. WebSocket (tarayıcıda anlık)#

QR'ı gösterdiğiniz sayfada oturum durumunu canlı izlemek için:

Çıktı

wss://api.globaltrust.id/v1/verification/session/{session_id}/ws

Bağlantı, durum her değiştiğinde bir mesaj gönderir. Kullanıcı telefonunda onayladığı anda sayfanız güncellenir — kullanıcı sayfayı yenilemek zorunda kalmaz.

Bu bağlantı sonucun kendisini taşımaz, yalnızca durumu. Kimlik alanlarını her zaman sunucunuzdan, gizli anahtarla okuyun.

3. Sorgulama#

Oturumu doğrudan okuyabilirsiniz:

Çıktı

GET /v1/verification/session/{session_id}
Authorization: Bearer sk_live_...

Webhook ve WebSocket'in ikisini de kullanamıyorsanız bu yol açıktır, ancak kullanıcıyı bekletirken sık sık sorgu atmak yerine makul aralıklarla (örneğin 3 saniye) deneyin ve dakikada 120 istek sınırını aşmayın.

Webhook ve WebSocket birlikte#

İkisini aynı anda kullanabilirsiniz ve çoğu entegrasyon için doğrusu budur: WebSocket kullanıcıya anında geri bildirim verir, webhook ise kullanıcı sayfayı kapatsa bile sonucun size ulaşmasını garanti eder.

Süre aşımı#

Oturumun expires_at alanı ne zaman geçersizleşeceğini söyler. Süresi dolmuş bir oturum expired olur ve onaylanamaz. Kullanıcı QR'ı geç okuttuysa yeni bir oturum açın.