KYC Entegrasyonu

Solidus KYC doğrulamasını uygulamanıza gömün. Kullanıcılar kimlik doğrulamasını bir kez tamamlar ve her yerde sunabilecekleri bir Doğrulanabilir Kimlik Bilgisi alır, bu da tekrarlayan KYC süreçlerini ortadan kaldırır.

Ön koşullar

verify.solidus.network üzerinde bir hesap
Bir API anahtarı (Verify kontrol panelinde Settings > API Keys altında bir tane üretin)

Entegrasyon Modları

Solidus Verify iki entegrasyon desenini destekler:

Mode	How it works	Best for
Barındırılan akış	Kullanıcıları Solidus tarafından barındırılan doğrulama sayfasına yönlendirin	En hızlı entegrasyon, arayüz çalışması gerekmez
API akışı	Belgeleri doğrudan API çağrılarıyla yükleyin	Özel arayüz, mobil uygulamalar, gömülü deneyimler

Temel URL

Tüm API istekleri aşağıdaki temel URL’yi kullanır:


https://verify.solidus.network/v1

Her isteği Authorization başlığında API anahtarınızla kimlik doğrulayın:


Authorization: Bearer YOUR_API_KEY

Barındırılan Akış

Adım 1: Bir Doğrulama Oturumu Oluşturun

Oturum oluşturmada bir webhook veya prefill alanı yoktur. Webhook’lar ayrı bir kaynaktır — POST /webhooks üzerinden bir uç noktayı bir kez kaydedin ve bu, gelecekteki her oturum için olayları alır (bkz. Webhook’lar kılavuzu). Solidus, oturum oluşturma sırasında ön doldurma iletişim alanları toplamaz.


const response = await fetch('https://verify.solidus.network/v1/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    // The DID of the user being verified (optional for hosted flow)
    subjectDid: 'did:solidus:testnet:7Hk3mRtQZv...',
 
    // Verification level: 1 = basic (ID + liveness), 2 = enhanced (+ address)
    level: 1,
 
    // Where to redirect after verification completes
    redirectUrl: 'https://myapp.com/verification-complete',
  }),
})
 
const session = await response.json()

Yanıt, oturum alanlarını session altında, barındırılan akışın sessionUrl’iyle birlikte iç içe yerleştirir:


{
  "session": {
    "id": "ver_2xK9mP4qR7nL",
    "organizationId": "org_3Vn9wLkDfT",
    "status": "pending",
    "level": 1,
    "sandbox": false,
    "subjectDid": "did:solidus:testnet:7Hk3mRtQZv...",
    "redirectUrl": "https://myapp.com/verification-complete",
    "sessionToken": "sess_tok_7Hk3mRtQZv...",
    "createdAt": "2026-05-07T12:00:00Z",
    "expiresAt": "2026-05-07T13:00:00Z"
  },
  "sessionUrl": "https://verify.solidus.network/v/s/sess_tok_7Hk3mRtQZv..."
}

Adım 2: Kullanıcıyı Yönlendirin

Kullanıcıyı sessionUrl’e gönderin. Belgelerini yükledikleri ve bir canlılık kontrolünü tamamladıkları Solidus doğrulama arayüzünü göreceklerdir.


// In your frontend
window.location.href = session.sessionUrl

Adım 3: Yönlendirmeyi İşleyin

Doğrulamadan sonra, kullanıcı oturum kimliğiyle bir sorgu parametresi olarak redirectUrl’inize yönlendirilir:


https://myapp.com/verification-complete?session=ver_2xK9mP4qR7nL&status=completed

Adım 4: Sonucu Kontrol Edin

Doğrulama sonucunu ve düzenlenen kimlik bilgisini almak için oturum durumunu sorgulayın.


const result = await fetch(
  'https://verify.solidus.network/v1/verifications/ver_2xK9mP4qR7nL',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  }
)
 
const verification = await result.json()

Tamamlanmış doğrulama yanıtı (session altında iç içe yerleştirilmiş, Verify API referansındaki GET /verifications/:id ile aynı şekilde):


{
  "session": {
    "id": "ver_2xK9mP4qR7nL",
    "status": "completed",
    "level": 1,
    "subjectDid": "did:solidus:testnet:7Hk3mRtQZv...",
    "documents": [
      {
        "type": "passport",
        "side": "front",
        "status": "verified",
        "extractedData": {
          "firstName": "Jane",
          "lastName": "Doe",
          "dateOfBirth": "1990-03-15",
          "documentNumber": "***redacted***",
          "nationality": "US"
        }
      }
    ],
    "liveness": { "status": "passed", "score": 0.97, "completedAt": "2026-05-07T12:05:00Z" },
    "credentialId": "vc_3Kn8rTpXm2",
    "completedAt": "2026-05-07T12:05:30Z",
    "createdAt": "2026-05-07T12:00:00Z"
  }
}

Düzenlenen kimlik bilgisini SDK’dan veya zincirden credentialId’sine göre ayrıca alın — yukarıdaki oturum yanıtı tam kimlik bilgisi nesnesini gömmez.

API Akışı

Arayüz üzerinde tam kontrole sahip olmak istediğinizde API akışını kullanın. Belgeleri kullanıcıdan toplar ve doğrudan yüklersiniz.

Adım 1: Bir Oturum Oluşturun

Barındırılan akışla aynı, ancak redirectUrl’i atlayın:


const response = await fetch('https://verify.solidus.network/v1/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    subjectDid: 'did:solidus:testnet:7Hk3mRtQZv...',
    level: 1,
  }),
})
 
const { session } = await response.json()
const sessionId = session.id

Adım 2: Belgeleri Yükleyin

Kimlik belgelerini oturuma yükleyin. Her yüklemede side ve type alanları gerekir — bir document_front/document_back/selfie tür sabit listesi yoktur. İşlemeyi tetiklemek için son belge yüklemesini final: 'true' olarak işaretleyin (ayrı bir gönderme adımı yoktur — bkz. Adım 3).


// Upload the front of an identity document
const frontUpload = new FormData()
frontUpload.append('file', frontImageFile)
frontUpload.append('side', 'front')
frontUpload.append('type', 'passport') // or driving_license | national_id | residence_permit
frontUpload.append('final', 'false')
 
await fetch(
  \`https://verify.solidus.network/v1/verifications/${sessionId}/documents\`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    body: frontUpload,
  }
)
 
// Upload the back of the document (required for ID cards and driver's licenses).
// final: 'true' marks the document step complete and triggers processing.
const backUpload = new FormData()
backUpload.append('file', backImageFile)
backUpload.append('side', 'back')
backUpload.append('type', 'passport')
backUpload.append('final', 'true')
 
await fetch(
  \`https://verify.solidus.network/v1/verifications/${sessionId}/documents\`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    body: backUpload,
  }
)

Belge yükleme alanları:

Field	Type	Required	Description
`side`	`front` \| `back`	Evet	Belgenin hangi tarafı
`type`	`passport` \| `driving_license` \| `national_id` \| `residence_permit`	Evet	Belge türü
`final`	`'true'` \| `'false'`	Hayır	`'true'` ise, belge adımını tamamlanmış olarak işaretler ve işlemeyi tetikler

Canlılık (yüz eşleştirme) ayrı bir akıştır — GET /verifications/:id/liveness-challenge ile bir meydan okuma isteyin, ardından yanıt karelerini POST /verifications/:id/liveness ile yükleyin. Bir selfie belge türü veya proof_of_address belge türü yoktur.

Adım 3: İşleme Otomatik Olarak Başlar

Bir /submit uç noktası yoktur. Son gerekli belgeyi final: 'true' ile yüklemek (Adım 2) işlemeyi doğrudan tetikler — Adım 4’te gösterildiği gibi yoklayın veya bir webhook bekleyin.

Adım 4: Sonuçları Alın

Sonuçlar webhook veya yoklama yoluyla gelir. Webhook kurulumu için Webhook’lar kılavuzuna bakın. Yoklamak için:


let status = 'processing'
 
while (status === 'processing') {
  const res = await fetch(
    \`https://verify.solidus.network/v1/verifications/${sessionId}\`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    }
  )
  const data = await res.json()
  status = data.session.status
 
  if (status === 'processing') {
    await new Promise((r) => setTimeout(r, 3000))
  }
}

Webhook Olayları

Doğrulama durumu değişiklikleri hakkında gerçek zamanlı bildirimler almak için webhook’ları yapılandırın.

Event	Description
`verification.completed`	Doğrulama başarıyla tamamlandı, kimlik bilgisi düzenlendi
`verification.failed`	Doğrulama başarısız oldu (belge sorunları, yüz uyuşmazlığı vb.)
`verification.expired`	Kullanıcı doğrulamayı tamamlamadan oturum sona erdi
`credential.issued`	Yeni bir Doğrulanabilir Kimlik Bilgisi düzenlendi
`credential.revoked`	Mevcut bir kimlik bilgisi iptal edildi

Varsayılan olaylar (uç noktayı oluştururken events atlanırsa): verification.completed, credential.issued.

Webhook yükü örneği:


{
  "id": "evt_8nR3kL5mQ2",
  "type": "verification.completed",
  "createdAt": "2026-05-07T12:05:30Z",
  "data": {
    "verificationId": "ver_2xK9mP4qR7nL",
    "status": "completed",
    "subjectDid": "did:solidus:testnet:7Hk3mRtQZv...",
    "level": 1,
    "credentialId": "urn:uuid:credential-id-here"
  }
}

İmza doğrulama ve teslimat işleme hakkında tam ayrıntılar için Webhook’lar kılavuzuna bakın.

Sandbox Modu

Gerçek kimlik belgeleri olmadan tam akışı test etmek için geliştirme sırasında sandbox modunu kullanın.

Bir oturum oluştururken sandbox: true ayarlayın. Sonucu sandboxOutcome ile kontrol edin:


const response = await fetch('https://verify.solidus.network/v1/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    subjectDid: 'did:solidus:testnet:7Hk3mRtQZv...',
    level: 1,
    sandbox: true,
    sandboxOutcome: 'pass', // 'pass', 'fail', 'timeout', or 'document_rejected'
    redirectUrl: 'https://localhost:3000/verification-complete',
  }),
})

Sandbox oturumları:

Gerçek belge analizini atlar
Saniyeler içinde tamamlanır
Test kimlik bilgileri düzenler (üretim için geçerli değil)
Aynı tüm API uç noktalarını ve webhook’ları destekler

Mevcut sandbox sonuçları:

Outcome	Behavior
`pass`	Doğrulama başarılı olur, test kimlik bilgisi düzenlenir
`fail`	Doğrulama simüle edilmiş belge sorunlarıyla başarısız olur
`timeout`	Hata işlemeyi test etmek için bir işleme zaman aşımını simüle eder
`document_rejected`	Hata işlemeyi test etmek için reddedilen bir belgeyi simüle eder

Doğrulama Durumları

Bir oturum bu durumlardan geçer:


pending ──> processing ──> completed
                  │
                  ├──> failed
                  │
                  └──> expired

Status	Description
`pending`	Oturum oluşturuldu, kullanıcının başlaması bekleniyor
`processing`	Belgeler yüklendi, doğrulama devam ediyor
`completed`	Doğrulama geçti, kimlik bilgisi düzenlendi
`failed`	Doğrulama başarısız oldu
`expired`	Oturum süresi doldu (varsayılan: 1 saat)

Hata İşleme

API, hata ayrıntılarıyla birlikte standart HTTP durum kodları döndürür:


{
  "error": {
    "code": "invalid_document",
    "message": "The uploaded document could not be read. Please upload a clear photo.",
    "details": {
      "documentType": "document_front",
      "reason": "blur_detected"
    }
  }
}

Yaygın hata kodları:

Code	Description
`invalid_document`	Belge görüntüsü bulanık, kırpılmış veya okunamaz
`face_mismatch`	Selfie belge fotoğrafıyla eşleşmiyor
`document_expired`	Kimlik belgesinin süresi dolmuş
`unsupported_document`	Belge türü veya ülke desteklenmiyor
`session_expired`	Doğrulama oturumunun süresi doldu
`rate_limit_exceeded`	Çok fazla istek (sınır: dakikada 100 istek)

Sonraki Adımlar

Webhook’lar — webhook uç noktalarını kurun ve yönetin
Kimlik Bilgisi Akışı — tam kimlik bilgisi yaşam döngüsünü anlayın
Express.js Ara Katmanı — API’nizde kimlik bilgilerini doğrulayın