# Findeks Kredi Uygunluğu

Findeks, araç kiralama hizmetleri için müşteri uygunluğunu doğrulamak amacıyla kullanılan bir kredi skorlama sistemidir.
Bu entegrasyon, kiralama rezervasyonlarını tamamlamadan önce müşteri kredibilitesini değerlendirmeye yardımcı olur ve
hem acenteler hem de kiralama şirketleri için finansal riskleri azaltır.

## Genel Bakış

Findeks entegrasyonu aşağıdaki kapsamlı kredi doğrulama iş akışını sağlar:

- **Kredi Uygunluk Kontrolü**: Müşteri kredi durumunun hızlı doğrulanması
- **Telefon Numarası Doğrulaması**: Müşterinin kayıtlı telefon numaralarını kullanarak çok adımlı kimlik doğrulaması
- **Kredi Raporu Oluşturma**: Nitelikli müşteriler için detaylı kredi değerlendirmesi
- **PIN Tabanlı Güvenlik**: Güvenli kredi raporlaması için SMS tabanlı doğrulama


## Entegrasyon İş Akışı

Tamamlanmış Findeks doğrulama süreci aşağıdaki adımları takip eder:

```
1. İlk Kontrol        → /findeks/check
2. Telefon Listesi Al → /findeks/phone-list (gerekirse)
3. Rapor Oluştur     → /findeks/report (Bilinmeyen durumsa)
4. PIN Onayı         → /findeks/pin-confirm
5. PIN Yenile        → /findeks/pin-renew (süresi dolmuşsa)
6. Son Doğrulama     → /findeks/check (durumu yeniden kontrol et)
```

### İş Akışı Karar Ağacı

- **Positive/Positive With Young Driver** → Kiralama onaylansın
- **Negative** → Kiralama reddedilsin
- **Unknown** → Telefon doğrulaması ve rapor oluşturma ile devam edilsin


## Kimlik Doğrulama

Tüm Findeks endpointleri bearer token kimlik doğrulaması gerektirir:

```
Authorization: Bearer ERİŞİM_JETONUNUZ
```

## API Endpointleri

### Kredi Uygunluğunu Kontrol Et

Bir müşteri için ilk kredi uygunluk kontrolü yapar.

#### Endpoint

```
POST /findeks/check
```

#### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `identityNumber` | string | Evet | Müşterinin T.C. kimlik numarası |
| `integrationCode` | string | Evet | Arama sonucundan entegrasyon takip kodu |


#### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/check \
  -H "Authorization: Bearer ERİŞİM_JETONUNUZ" \
  -H "Content-Type: application/json" \
  -d '{
    "identityNumber": "11223344556",
    "integrationCode": "integrationCode123"
  }'
```

#### Yanıt

**Başarılı Yanıt (200 OK):**

```json
{
  "status": "Positive"
}
```

**Olası Durum Değerleri:**

- `"Positive"` - Müşteri kiralama için onaylandı
- `"Negative"` - Müşteri kiralama için reddedildi
- `"Unknown"` - Ek doğrulama gerekli
- `"Positive With Young Driver"` - Genç sürücü koşullarıyla onaylandı


**Hata Yanıtları:**

- `400 Bad Request` - Geçersiz istek formatı veya doğrulama hatası
- `401 Unauthorized` - Geçersiz veya eksik erişim jetonu
- `500 Internal Server Error` - Sunucu hatası


### Müşteri Telefon Listesini Al

Doğrulama sürecinde kullanmak üzere bir müşterinin kayıtlı telefon numaralarını alır.

#### Endpoint

```
POST /findeks/phone-list
```

#### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `identityNumber` | string | Evet | Müşterinin T.C. kimlik numarası |
| `integrationCode` | string | Evet | Arama sonucundan entegrasyon takip kodu |


#### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/phone-list \
  -H "Authorization: Bearer ERİŞİM_JETONUNUZ" \
  -H "Content-Type: application/json" \
  -d '{
    "identityNumber": "11223344556",
    "integrationCode": "integrationCode123"
  }'
```

#### Yanıt

**Başarılı Yanıt (200 OK):**

```json
{
  "phoneList": [
    {
      "key": 711957237,
      "phone": "533*****36"
    },
    {
      "key": 711957238,
      "phone": "505*****42"
    }
  ]
}
```

**Yanıt Alanları:**

- `key` - Telefon numarası için benzersiz tanımlayıcı (rapor oluşturmada kullanılır)
- `phone` - Gizlilik koruması için maskelenmiş telefon numarası


### Kredi Raporu Oluştur

Tamamlanmış müşteri bilgilerini kullanarak detaylı Findeks kredi raporu oluşturur.

#### Endpoint

```
POST /findeks/report
```

#### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `identityNumber` | string | Evet | Müşterinin T.C. kimlik numarası |
| `birthDate` | string (date) | Evet | Müşterinin doğum tarihi (YYYY-MM-DD) |
| `driverLicenseDate` | string (date) | Evet | Ehliyet veriliş tarihi (YYYY-MM-DD) |
| `phone` | string | Evet | Müşterinin telefon numarası (E.164 formatında) |
| `phoneKey` | integer | Evet | Telefon listesi yanıtından telefon anahtarı |
| `integrationCode` | string | Evet | Arama sonucundan entegrasyon takip kodu |


#### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/report \
  -H "Authorization: Bearer ERİŞİM_JETONUNUZ" \
  -H "Content-Type: application/json" \
  -d '{
    "identityNumber": "45473452",
    "birthDate": "1994-01-15",
    "driverLicenseDate": "2012-03-20",
    "phone": "+905554443322",
    "phoneKey": 123,
    "integrationCode": "integrationCode123"
  }'
```

#### Yanıt

**Başarılı Yanıt (200 OK):**

```json
{
  "findeksCode": 182783973
}
```

**Yanıt Alanları:**

- `findeksCode` - Kredi raporu için oluşturulan kod (PIN onayında kullanılır)


**Not:** Başarılı rapor oluşturulduktan sonra, doğrulama için müşterinin telefon numarasına bir PIN gönderilir.

### PIN Onayı

Kredi kontrol sürecini yetkilendirmek için müşterinin telefonuna gönderilen PIN'i onaylar.

#### Endpoint

```
POST /findeks/pin-confirm
```

#### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `findeksCode` | string | Evet | Rapor oluşturma işleminden Findeks kodu |
| `pinCode` | string | Evet | SMS ile alınan PIN kodu |
| `integrationCode` | string | Evet | Arama sonucundan entegrasyon takip kodu |


#### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/pin-confirm \
  -H "Authorization: Bearer ERİŞİM_JETONUNUZ" \
  -H "Content-Type: application/json" \
  -d '{
    "findeksCode": "45473452",
    "pinCode": "123456",
    "integrationCode": "integrationCode123"
  }'
```

#### Yanıt

**Başarılı Yanıt (204 No Content):**

Yanıt gövdesi yok. 204 durumu başarılı PIN onayını gösterir.

**Hata Yanıtları:**

- `400 Bad Request` - Geçersiz PIN veya istek formatı
- `401 Unauthorized` - Geçersiz veya eksik erişim jetonu
- `500 Internal Server Error` - Sunucu hatası


### PIN Yenile

Orijinal PIN'in süresi dolduğunda veya alınmadığında yeni bir PIN talep eder.

#### Endpoint

```
POST /findeks/pin-renew
```

#### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `findeksCode` | string | Evet | Rapor oluşturma işleminden Findeks kodu |
| `integrationCode` | string | Evet | Arama sonucundan entegrasyon takip kodu |


#### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/pin-renew \
  -H "Authorization: Bearer ERİŞİM_JETONUNUZ" \
  -H "Content-Type: application/json" \
  -d '{
    "findeksCode": "45473452",
    "integrationCode": "integrationCode123"
  }'
```

#### Yanıt

**Başarılı Yanıt (204 No Content):**

Yanıt gövdesi yok. 204 durumu başarılı PIN yenilenmesini gösterir.

**Hata Yanıtları:**

- `400 Bad Request` - Geçersiz istek formatı
- `401 Unauthorized` - Geçersiz veya eksik erişim jetonu
- `500 Internal Server Error` - Sunucu hatası


## Tam Entegrasyon Örneği

İşte tam bir iş akışı uygulama örneği:

```javascript
async function performFindeksVerification(customerData) {
    const {identityNumber, integrationCode, birthDate, driverLicenseDate, phone} = customerData;

    try {
        // Adım 1: İlk uygunluk kontrolü
        const initialCheck = await checkFindeksEligibility(identityNumber, integrationCode);

        if (initialCheck.status === 'Positive' || initialCheck.status === 'Positive With Young Driver') {
            return {approved: true, status: initialCheck.status};
        }

        if (initialCheck.status === 'Negative') {
            return {approved: false, status: 'Negative'};
        }

        // Adım 2: Bilinmeyen durum için telefon listesi al
        if (initialCheck.status === 'Unknown') {
            const phoneList = await getFindeksPhoneList(identityNumber, integrationCode);

            // Adım 3: Seçilen telefonla rapor oluştur
            const selectedPhone = phoneList.phoneList[0]; // Kullanıcı uygun telefonu seçer
            const report = await generateFindeksReport({
                identityNumber,
                birthDate,
                driverLicenseDate,
                phone,
                phoneKey: selectedPhone.key,
                integrationCode
            });

            // Adım 4: Kullanıcıdan PIN al ve onayla
            const pinCode = await getPinFromUser(); // Uygulama arayüze bağlıdır
            await confirmFindeksPin(report.findeksCode, pinCode, integrationCode);

            // Adım 5: PIN onayından sonra durumu yeniden kontrol et
            // Not: Durum güncellemesi 1 dakika kadar sürebilir
            await waitForStatusUpdate();
            const finalCheck = await checkFindeksEligibility(identityNumber, integrationCode);

            return {
                approved: finalCheck.status.startsWith('Positive'),
                status: finalCheck.status
            };
        }

    } catch (error) {
        if (error.message.includes('PIN')) {
            // Gerekirse PIN yenilemeyi ele al
            await renewFindeksPin(findeksCode, integrationCode);
            return performFindeksVerification(customerData); // Yeniden dene
        }
        throw error;
    }
}

async function checkFindeksEligibility(identityNumber, integrationCode) {
    const response = await fetch('/api/v1/findeks/check', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({identityNumber, integrationCode})
    });

    if (!response.ok) throw new Error('Findeks kontrolü başarısız oldu');
    return response.json();
}

async function waitForStatusUpdate() {
    // Durum güncellemesini bekle (1 dakika kadar sürebilir)
    return new Promise(resolve => setTimeout(resolve, 60000));
}
```

## Hata Yönetimi

### Yaygın Hata Kodları

| Kod | Açıklama |
|  --- | --- |
| 1001 | Veri ayrıştırma hatası |
| 1002 | Doğrulama hatası |
| 1003 | Parametre hatası |
| 2001 | Yetkisiz |
| 2002 | Yasak |
| 5001 | Acente yapılandırması bulunamadı |


### En İyi Uygulamalar

1. **Asenkron Durum Güncellemelerini Ele Alın**: PIN onayından sonra durum güncellemeleri 1 dakika kadar sürebilir
2. **Yeniden Deneme Mantığı Uygulayın**: PIN yenileme senaryolarını zarif bir şekilde ele alın
3. **Güvenli PIN İşleme**: PIN kodlarını asla kaydetmeyin veya saklamayın
4. **Hata Kurtarma**: Her adım için uygun hata yönetimi uygulayın
5. **Kullanıcı Deneyimi**: Doğrulama süreci boyunca net geri bildirim sağlayın
6. **Zaman Aşımı İşleme**: PIN girişi için uygun zaman aşımları ayarlayın


## Güvenlik Değerlendirmeleri

### Veri Gizliliği

- Müşteri kimlik numaralarını veya PIN kodlarını asla saklamayın veya kaydetmeyin
- Hassas verileri GDPR ve yerel gizlilik düzenlemelerine uygun şekilde ele alın
- Tüm API iletişimleri için HTTPS kullanın


### Uygulama Güvenliği

- API çağrılarından önce tüm giriş parametrelerini doğrulayın
- Çok adımlı doğrulama için uygun oturum yönetimi uygulayın
- Geçici doğrulama durumu için güvenli depolama kullanın
- Kullanımdan sonra hassas verileri bellekten temizleyin


## Sorun Giderme

### Yaygın Sorunlar

**Bilinmeyen Durum Devam Ediyor**

- Tüm gerekli müşteri bilgilerinin doğru olduğundan emin olun
- Telefon numarası formatını kontrol edin (E.164)
- PIN onayının başarılı olduğunu doğrulayın


**PIN Alınmadı**

- PIN yenileme endpointini kullanın
- Telefon numarasının doğru ve aktif olduğunu doğrulayın
- SMS teslimat gecikmelerini kontrol edin


**Doğrulama Zaman Aşımı**

- Üstel geri çekilme ile yeniden deneme mantığı uygulayın
- API hız sınırlarını kontrol edin
- Entegrasyon kodunun oturum için geçerli olduğunu doğrulayın


### Test Önerileri

- Farklı durum yanıtlarını anlamak için çeşitli kimlik numaralarıyla test edin
- Ağ zaman aşımları için uygun hata yönetimi uygulayın
- PIN yenileme senaryolarını test edin
- Farklı ortamlarda durum güncelleme zamanlamasını doğrulayın