Alışveriş Kredisi API Entegrasyonu

Kimlik Doğrulama

API’ye erişim için yetkilendirme gereklidir. Yetkilendirme için Bearer Token kullanılmaktadır.

Token Alma

Endpoint: /loans/authenticate Method: POST Content-Type: application/json

İstek Parametreleri

{
  "username": "string",
  "password": "string",
  "merchantNo": 0,
  "apiSecretKey": "string"
}

Parametre	Tip	Açıklama	Zorunlu
username	string	Üye iş yeri API kullanıcı adı	Zorunlu
password	string	Üye iş yeri API parolası	Zorunlu
merchantNo	integer	Üye iş yeri numarası	Zorunlu
apiSecretKey	string	Üye iş yerine ait benzersiz anahtar (Nkolay tarafından iletilir)	Zorunlu

Yanıt Örneği

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJtZXJjaGFudF9ubyI6NDAwM..."
}

Token Kullanımı

Alınan token değeri, sonraki tüm API çağrılarında Authorization başlığına Bearer şeklinde eklenmelidir.

Örnek Authorization Header:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJtZXJjaGFudF9ubyI6NDAwM...

---

Banka Sorgulama

Anlaşmalı bankaların listesini getirir. Bu bilgi, son kullanıcının ekranında bankaları göstermek amacıyla kullanılması tavsiye edilir.

Endpoint: /loans/v1/facilitate/query/banks Method: POST Content-Type: application/json

İstek

Gövde boş bırakılabilir:

{}

Yanıt Örneği

{
  "banks": [
    {
      "countryId": "TR",
      "code": "AKTIFBANK",
      "type": "AKTIFBANK",
      "name": "Aktif Bank",
      "description": "Aktif Yatırım Bankası A.Ş.",
      "active": true
    }
  ]
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
banks	array[object]	Bankaların listesi
countryId	string	Ülke ID
code	string	Banka kodu (oturum açarken kullanılır)
type	string	Banka tipi
name	string	Banka adı
description	string	Banka açıklaması
active	boolean	Bankanın aktif olup olmadığı

---

Banka Oturumu Başlatma

Belirli bir banka için yeni bir kredi oturumu başlatır. Bu servisin sonucunda dönen referenceId değeri, sonraki API çağrılarında kullanılacaktır.

Endpoint: /loans/v1/facilitate/sessions/{bankCode} Method: POST Content-Type: application/json

Parametreler

Parametre	Tip	Açıklama	Örnek
bankCode	string (path)	Banka kodu (Banka Sorgulama servisinden alınan code değeri)	AKTIFBANK

İstek

Gövde boş bırakılabilir:

{}

Yanıt Örneği

{
  "referenceId": "7b942ca7-7ecd-4b45-9581-855a6f5c4856"
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
referenceId	string	Kredi oturumu referans ID’si. Bu ID, ödeme simülasyonu ve ön kredi değerlendirmesi servislerinde kullanılacaktır.

---

Ödeme Simülasyonu

Belirli bir kredi tutarı ve vade için aylık ödeme simülasyonu yapar. Müşterinize farklı taksit seçeneklerini göstermek için kullanabilirsiniz.

Endpoint: /loans/v1/facilitate/simulation/{bankSessionReferenceId} Method: POST Content-Type: application/json

Parametreler

Parametre	Tip	Açıklama
bankSessionReferenceId	string (path)	Banka oturumu açma işleminden dönen referenceId değeri

İstek Parametreleri

{
  "maxTerm": 6,
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Ürün Adı",
        "categoryCode": "Kategori Kodu",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00
      }
    ]
  }
}

Parametre	Tip	Açıklama	Zorunlu
maxTerm	integer	Maksimum vade sayısı	İsteğe Bağlı
cart	object	Alışveriş sepeti bilgileri	İsteğe Bağlı
cart.price	object	Fiyat bilgileri	Zorunlu
cart.price.itemsPrice	number	Ürünlerin toplam fiyatı	Zorunlu
cart.price.shippingPrice	number	Kargo fiyatı	Zorunlu
cart.price.totalPrice	number	Toplam fiyat (ürünler + kargo)	Zorunlu
cart.items	array[object]	Sepetteki ürünlerin listesi	Zorunlu
cart.items[].productName	string	Ürün adı	Zorunlu
cart.items[].categoryCode	string	Ürün kategori kodu	Zorunlu
cart.items[].quantity	integer	Ürün adedi	Zorunlu
cart.items[].price	number	Ürün birim fiyatı	İsteğe Bağlı
cart.items[].totalPriceWithoutDiscounts	number	İndirimsiz toplam fiyat	Zorunlu
cart.items[].totalPrice	number	İndirimli toplam fiyat	Zorunlu

Yanıt Örneği

{
  "bankResponseCode": "0",
  "bankResponseMessage": "İşlem Başarılı",
  "success": true,
  "monthlyPayments": [
    {
      "term": 3,
      "amount": 7442.8,
      "interestRate": 4.19,
      "totalPaymentAmount": 22328.38,
      "annualEffectiveInterestRate": 88.9774,
      "monthlyEffectiveInterestRate": 7.4148
    },
    {
      "term": 6,
      "amount": 4016.84,
      "interestRate": 4.19,
      "totalPaymentAmount": 24101.05,
      "annualEffectiveInterestRate": 88.9781,
      "monthlyEffectiveInterestRate": 7.4148
    }
  ]
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
bankResponseCode	string	Banka cevap kodu (“0” = başarılı)
bankResponseMessage	string	Banka cevap mesajı
success	boolean	İşlemin başarılı olup olmadığını belirtir
monthlyPayments	array[object]	Aylık ödeme planları listesi
monthlyPayments[].term	integer	Vade sayısı (ay)
monthlyPayments[].amount	number	Aylık ödeme miktarı (TL)
monthlyPayments[].interestRate	number	Faiz oranı (%)
monthlyPayments[].totalPaymentAmount	number	Toplam ödeme miktarı (TL)
monthlyPayments[].annualEffectiveInterestRate	number	Yıllık efektif faiz oranı (%)
monthlyPayments[].monthlyEffectiveInterestRate	number	Aylık efektif faiz oranı (%)

---

Ön Kredi Değerlendirmesi

Müşteri ve sepet bilgilerini ileterek müşterinin ön onaylı kredi limitini sorgular. Kredi başvurusu yapmadan önce bu servisin çağrılması zorunludur.

Endpoint: /loans/v1/facilitate/pre-approved/{bankSessionReferenceId} Method: POST Content-Type: application/json

Parametreler

Parametre	Tip	Açıklama
bankSessionReferenceId	string (path)	Banka oturumu açma işleminden dönen referenceId değeri

İstek Parametreleri

{
  "nationalIdentityNumber": "12345678901",
  "gsmNumber": "5551234567",
  "orderId": "ORDER-12345",
  "maxTerm": 6,
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Ürün Adı",
        "categoryCode": "Kategori Kodu",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00,
        "sellerExternalId": "SELLER-001",
        "commissionRate": 1.00,
        "withholdingTax": 0.10,
        "marketplaceCost": 2.00
      }
    ]
  }
}

Parametre	Tip	Açıklama	Zorunlu
nationalIdentityNumber	string	Müşterinin T.C. Kimlik Numarası (11 haneli)	Zorunlu
gsmNumber	string	Müşterinin telefon numarası (5XXXXXXXXX formatında)	Zorunlu
orderId	string	Sipariş numarası (benzersiz olmalı)	Zorunlu
maxTerm	integer	İstenilen maksimum vade sayısı	Zorunlu
cart	object	Sepet bilgileri	Zorunlu
cart.items[].sellerExternalId	string	Satıcı ID (pazaryeri için)	İsteğe Bağlı
cart.items[].commissionRate	number	Komisyon oranı (%)	İsteğe Bağlı*
cart.items[].commissionAmount	number	Komisyon tutarı (TL)	İsteğe Bağlı*
cart.items[].withholdingTax	number	Stopaj vergisi	İsteğe Bağlı
cart.items[].marketplaceCost	number	Pazaryeri maliyeti	İsteğe Bağlı

Not: commissionRate ve commissionAmount alanlarından yalnızca bir tanesi dolu gönderilmelidir.

Yanıt Örneği

{
  "success": true,
  "referenceId": "50171152-66c5-4374-9f82-6a97c9e6d5d0",
  "bankSuccess": true,
  "bankResponseCode": "0",
  "bankResponseMessage": "İşlem Başarılı",
  "monthlyPayments": [
    {
      "term": 3,
      "interestRate": 4.19,
      "amount": 7442.8,
      "totalPaymentAmount": 22328.38,
      "annualEffectiveInterestRate": 88.9774,
      "type": "CONSUMER_LOAN"
    }
  ]
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
success	boolean	İşlemin başarılı olup olmadığını belirtir
referenceId	string	Referans ID. Bu ID, kredi başvuru servisinde kullanılacaktır.
bankSuccess	boolean	Banka tarafından onaylanıp onaylanmadığını belirtir
bankResponseCode	string	Banka cevap kodu
bankResponseMessage	string	Banka cevap mesajı
monthlyPayments	array[object]	Aylık ödeme planı (Simülasyon servisi ile aynı formatta)
monthlyPayments[].type	string	Kredi tipi (örn: CONSUMER_LOAN)

---

Entegrasyon Akışı

Alışveriş kredisi entegrasyonunu tamamlamak için şu sırayı takip edin:

1. Kimlik Doğrulama - Bearer Token alın
2. Banka Sorgulama - Müşteriye gösterilecek banka listesini alın
3. Banka Oturumu Başlatma - Seçilen banka için oturum başlatın
4. Ödeme Simülasyonu (Opsiyonel) - Farklı vade seçeneklerini gösterin
5. Ön Kredi Değerlendirmesi - Müşterinin kredi uygunluğunu kontrol edin
6. Kredi Başvurusu - Sonraki adım →

Sonraki Adımlar

• Kredi Başvurusu ve Yönetim → - Başvuru yapma, sorgulama ve iade işlemleri