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.

Scope	Onay ekranındaki karşılığı
`identity.first_name`	Ad
`identity.last_name`	Soyad
`identity.birth_date`	Doğum tarihi
`identity.nationality`	Uyruk
`identity.document_number`	Belge numarası
`email`	E-posta adresi
`phone`	Telefon numarası
`address`	Adres

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.

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.