Ana içeriğe geç

Doğrulama Oturumları Uç Noktası

Bir doğrulama sürecini başlatmak için aşağıdaki uç noktayı kullanın:

POST https://app.trustchex.com/api/v1/verification-sessions

API anahtarını başlıkta x-api-key olarak ekleyin.

İstek Gövdesi​

Gövdeye aşağıdaki özellikleri ekleyin:

{
    "workflowId": "<workflowId>",
    "email": "<kullanıcı email>",
    "phoneNumber": "<kullanıcı telefon>",
    "sendOTP": true,
    "locale": "<en|tr>",
    "duration": 30,
    "approvalCriteria": [
        {
            "type": "<kriter türü>",
            "condition": "<koşul>",
            "value": "<değer>",
            "rejectIfNotMet": false
        },
        ...
    ]
}

JSON Özellikleri​

  • workflowId (string, zorunlu): Doğrulama için kullanılacak iş akışının kimliği. Bir iş akışını iş akışları bölümünde oluşturabilirsiniz.
  • email (string, isteğe bağlı): Doğrulanacak kullanıcının e-posta adresi. sendOTP true olduğunda (varsayılan) email veya phoneNumber alanlarından biri sağlanmalıdır, ancak ikisi birden değil. sendOTP false olduğunda ikisi de isteğe bağlıdır (bkz. sendOTP).
  • phoneNumber (string, isteğe bağlı): Doğrulanacak kullanıcının telefon numarası. sendOTP true olduğunda (varsayılan) phoneNumber veya email alanlarından biri sağlanmalıdır, ancak ikisi birden değil. sendOTP false olduğunda ikisi de isteğe bağlıdır.
  • sendOTP (boolean, isteğe bağlı, varsayılan: true): true olarak ayarlanırsa, kullanıcının e-postası veya telefon numarası Tek Kullanımlık Şifre ile doğrulanır (bu nedenle email/phoneNumber alanlarından biri zorunludur). Kullanıcının iletişim bilgilerinin sahibi olduğunu zaten doğruladıysanız, süreci kolaylaştırmak için bunu false olarak ayarlayabilirsiniz. sendOTP: false ile email ve phoneNumber alanlarının ikisini de tamamen atlayabilirsiniz — iletişimsiz bir kimlik doğrulama. Bu, yalnızca belgeyi doğrulayıp approvalCriteria kurallarınızı uygulamanız gerektiğinde kullanışlıdır (sonuç webhook ve sorgulama ile iletilir, bildirimler ise atlanır).
  • locale (string, zorunlu): Doğrulama süreci için dil tercihi. Kabul edilebilir değerler en İngilizce ve tr Türkçe'dir.
  • duration (tamsayı, isteğe bağlı): Doğrulama oturumunun süresi dakika cinsinden. Varsayılan değer 30 dakikadır.
  • approvalCriteria (nesne dizisi, isteğe bağlı): Doğrulamanın onaylanması için karşılanması gereken koşulları belirtir. Dizideki her nesne aşağıdaki özellikleri içerir:
    • type (string): Kriter türünü tanımlar. Örnekler:
      • "DOCUMENT_NUMBER"
      • "DOCUMENT_PERSONAL_NUMBER"
      • "DOCUMENT_OWNER_NAME"
      • "DOCUMENT_OWNER_SURNAME"
    • condition (string): Uygulanacak koşulu belirtir. Olası değerler:
      • "EQUALS"
      • "NOT_EQUALS"
      • "CONTAINS"
      • "NOT_CONTAINS"
      • "STARTS_WITH"
      • "ENDS_WITH"
    • value (string): Belirtilen koşula karşılaştırılacak değeri temsil eder.
    • rejectIfNotMet (boolean, isteğe bağlı): true olarak ayarlanırsa, kriter karşılanmazsa doğrulama reddedilir. Varsayılan değer false'dur.
    • accentInsensitive (boolean, isteğe bağlı): true olarak ayarlanırsa, karşılaştırma gevşek yapılır — harf büyük/küçük durumu, aksanlar/diakritik işaretler ve fazladan boşluklar yok sayılır (Türkçe duyarlı). Örneğin kimlikteki ŞAHİN değeri, beklenen Sahin, SAHIN veya şahin değeriyle eşleşir. false olduğunda (varsayılan) eşleştirme tam yapılır (büyük/küçük harf ve aksana duyarlı). Belgedeki yazımın beklenen değerden büyük/küçük harf veya aksan açısından farklı olabileceği ad alanları için kullanışlıdır.

JavaScript Fetch Örneği​

JavaScript'in fetch kullanarak API isteğini nasıl yapacağınızın bir örneği:

const url = 'https://app.trustchex.com/api/v1/verification-sessions';
const apiKey = 'API_ANAHTARINIZ';
const requestBody = {
    email: '[email protected]',
    workflowId: 'workflow123',
    sendOTP: true,
    locale: 'en',
    duration: 30
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => {
    console.log('Success:', data);
})
.catch((error) => {
    console.error('Error:', error);
});

Başarılı Yanıt​

Başarılı bir yanıt, aşağıdaki yapıya sahip bir JSON nesnesi döndürecektir:

{
    "id": "<verificationSessionId>",
    "identificationId": "<identificationId>",
    "sessionCode": "AB12CD34",
    "deepLink": "trustchex://app-url/https://app.trustchex.com/verification-session/<verificationSessionId>",
    "qrCodeLink": "https://app.trustchex.com/api/v1/verification-sessions/<verificationSessionId>/qr-code",
    "sessionPageLink": "https://app.trustchex.com/public/verification-sessions/<verificationSessionId>"
}

Yanıt Özellikleri​

  • id (UUID): Doğrulama oturumunun benzersiz tanımlayıcısı.
  • identificationId (UUID): Kimlik doğrulama sürecinin benzersiz tanımlayıcısı.
  • sessionCode (string): Kullanıcıların doğrulama oturumlarına erişmek için mobil uygulamaya girebilecekleri 8 karakterli alfanümerik bir kod. Bu, QR kodlarını taramaya veya derin bağlantıları kullanmaya alternatif sağlar.
  • deepLink (string): Doğrulama oturumu için bir derin bağlantı URL'si.
  • qrCodeLink (string): Doğrulama oturumu için QR koduna bir URL.
  • sessionPageLink (string): Kullanıcının mobil uygulama bağlantılarını ve bir QR kodu veya derin bağlantıyı birlikte bulabileceği doğrulama oturumu sayfasına bir URL.

API, kullanıcıların mobil uygulamadaki doğrulama oturumlarına erişmeleri için üç yöntem sağlar:

1. Oturum Kodu (Kolaylık için önerilir)​

sessionCode, kullanıcıların mobil uygulamaya manuel olarak girebilecekleri 8 karakterlik alfanümerik bir koddur (örn. AB12CD34). Bu yöntem:

  • İletişim kurmak kolaydır (e-posta veya SMS yoluyla)
  • Tarama özelliği gerektirmez
  • Tüm kanallarda çalışır

Kullanım örneği:

Doğrulama oturum kodunuz: AB12CD34
Lütfen Trustchex uygulamasını açın ve doğrulamaya başlamak için bu kodu girin.

2. Derin Bağlantı​

Kullanıcıyı bağlantıya tıklayarak doğrudan mobil uygulamaya göndermek için deepLink kullanılabilir. En iyi kullanım alanları:

  • E-posta iletişimleri
  • SMS mesajları
  • Web'den uygulamaya geçişler

3. QR Kod Bağlantısı​

Kullanıcıyı mobil uygulamaya yönlendirmek için tarayabileceği bir QR kodu oluşturmak için qrCodeLink kullanılabilir. En iyi kullanım alanları:

  • Masaüstünden mobil akışlar
  • Fiziksel belgeler veya ekranlar
  • Kullanıcıların farklı bir cihazda olduğu web sayfaları

qrCodeLink, QR kodunu gösterime hazır bir görüntü olarak döndüren özel bir uç noktayı işaret eder:

GET https://app.trustchex.com/api/v1/verification-sessions/<verificationSessionId>/qr-code
  • Yanıt: Oturumun derin bağlantısını içeren 250×250 boyutunda bir PNG görüntü (Content-Type: image/png). Doğrudan gömebilir (örneğin <img src="<qrCodeLink>" />) veya indirip saklayabilirsiniz.
  • İstek gövdesi gerekmez; yoldaki oturum kimliği tek parametredir.
  • Oturum kimliği eksikse 400 Bad Request döner.

Genellikle oturum oluşturduğunuzda dönen qrCodeLink değerini kullanmanız yeterlidir; bu URL'yi kendiniz oluşturmanıza gerek yoktur.

Hata Yönetimi​

İstekle ilgili bir hata varsa, API uygun bir HTTP durum kodu ve hata ayrıntılarını içeren bir JSON nesnesi döndürecektir.

  • 400 Bad Request: İstek gövdesi geçersiz veya gerekli alanlar eksik.
  • 401 Unauthorized: API anahtarı eksik veya geçersiz.
  • 500 Internal Server Error: Sunucuda bir hata oluştu.

Bu hataları uygulamanızda uygun şekilde yönettiğinizden emin olun.

Mobil Uygulama Oturum Arama (Alternatif Erişim Yöntemi)​

Mobil uygulama, e-posta/telefon doğrulaması gerektirmek yerine oturum kodunu kullanarak doğrulama oturumlarını arayabilir.

Uç Nokta​

GET https://app.trustchex.com/api/app/mobile/verification-sessions?sessionCode={kod}

Sorgu Parametreleri​

  • sessionCode (string, zorunlu): Kullanıcıya sağlanan 8 karakterlik alfanümerik oturum kodu.

Örnek İstek​

const sessionCode = 'AB12CD34';
const url = `https://app.trustchex.com/api/app/mobile/verification-sessions?sessionCode=${sessionCode}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Oturum bulundu:', data);
})
.catch((error) => {
    console.error('Hata:', error);
});

Başarılı Yanıt​

{
    "id": "<verificationSessionId>"
}

Hata Yanıtları​

  • 400 Bad Request: Oturum kodu eksik veya geçersiz formatta.
  • 404 Not Found: Sağlanan kodla aktif bir doğrulama oturumu bulunamadı.

Notlar​

  • Oturum kodları büyük/küçük harf duyarsızdır (otomatik olarak büyük harfe dönüştürülür)
  • Yalnızca aktif oturumlar (süresi dolmamış veya tamamlanmamış) bulunabilir
  • Bu, kullanıcı başına birden fazla oturum sağlayarak önceki e-posta/telefon tabanlı aramayı değiştirir