Kavramlar

Banka, bağlantı, hesap, bakiye, hareket

Sizin kurduğunuz tek şey bağlantıdır; hesaplar onun altında otomatik bulunur, her hesap için bakiye ve hareketler bankadan okunur.

Terim	Anlamı	API'deki kimliği
Banka	Katalogdaki banka; EFT koduyla tanımlanır.	`bankId`
Bağlantı	Sizin bir bankayla kurduğunuz okuma bağlantısı. Aynı ortamda bir bankaya bir bağlantınız olur.	`connectionId`
Hesap	Bağlantı altında bulunan banka hesabı. Bağlantı aktif olduğunda hesaplarınız kendiliğinden bulunur.	`accountId`
Bakiye	Hesabın en son okunan bakiyesi.	`accountId` ile
Hareket	Hesap ekstresindeki tek satır: tutar, yön, tarih, açıklama.	`transactionId`
Tazelik	Verinin en son ne zaman okunduğu ve bir sonraki okumanın ne zaman mümkün olduğu.	`freshness`
Yenileme isteği	Bir hesabın bankadan yeniden okunmasını istemek.	`POST …/sync`
Yetenek	Bir bağlantıda kullanılabilen veri türleri ve işlemler; transfer için `OUTGOING_TRANSFER`, döviz için `FX_EXCHANGE`.	`capabilities`
Transfer	Bağlı hesabınızdan bir IBAN'a gönderilen para.	`transferId` (`id`)
Döviz teklifi	Aynı bankadaki iki hesabınız arasında bankanın verdiği, kısa süre geçerli kur ve tutar.	`quoteId` (`id`)
Döviz işlemi	Bir teklifin işleme alınması.	`orderId` (`id`)
Ortam	Test ya da canlı; API anahtarınızın ortamıdır.	—

Bağlantı durumları

Bir bağlantı bankadan veri okunmaya başlamadan önce başvuru ve kurulum adımlarından geçer. Durum status alanındadır; durumun gerekçesi statusReasonCode alanında kısa bir kodla verilir (değerler: Bağlantılar).

Yeni veri yalnız ACTIVE ve DEGRADED durumlarında okunur. DEGRADED bir hata durumu değildir: okumalar yeniden denenir ve bağlantı kendiliğinden ACTIVE olur. DISCONNECTED yeniden açılmaz; bankayı tekrar bağladığınızda yeni bir connectionId oluşur.

Durum	Bankadan yeni veri okunur mu	Ne yapmalısınız
`PENDING_DOCUMENTS`	Hayır	Başvuru belgelerini panelde gösterilen teslim talimatına göre iletin.
`UNDER_REVIEW`	Hayır	Belgeleriniz inceleniyor; bekleyin. Bir belge reddedilirse bağlantı `PENDING_DOCUMENTS` durumuna döner.
`PENDING_SETUP`	Hayır	Kurulum Lunixi tarafından tamamlanıyor; bekleyin.
`ACTIVE`	Evet	Bir şey yapmanız gerekmez; hesaplarınız düzenli olarak okunur.
`DEGRADED`	Okuma deneniyor ama son okumalar başarısız	Son okunan veri döner ve güncel olmayabilir. Okumalar kendiliğinden yeniden denenir; `lastSuccessfulSyncAt` alanını izleyin.
`SUSPENDED`	Hayır	Bağlantı askıya alındı. Panelde bağlantı ayrıntısına bakın; gerekiyorsa Lunixi ile iletişime geçin.
`DISCONNECTED`	Hayır	Bağlantı kapandı ve yeniden açılmaz. Bankayı yeniden okumak için panelden yeniden bağlayın; yeni bağlantı yeni bir `connectionId` alır.

Bağlantı kesildiğinde hesapları silinmez; durumları INACTIVE olur. Banka bir hesabı artık döndürmüyorsa o hesap da INACTIVE olur.

Daha önce okunmuş hesaplar, bakiyeler ve hareketler bağlantı ACTIVE olmasa da API'den okunabilir. Durum yalnız bankadan yeni veri okunup okunmadığını belirler.

Hareket yönü ve tipi

Her hareketin bir yönü (direction) vardır:

`direction`	Anlamı
`CREDIT`	Hesaba giren para
`DEBIT`	Hesaptan çıkan para

amountMinor her zaman sıfır ya da pozitiftir; işaret taşımaz. Paranın girdiğini mi çıktığını mı direction alanından okuyun.

Bankalar hareketleri kendi kodlarıyla sınıflandırır. Lunixi bu kodları bankadan bağımsız ortak bir tipe (canonicalType) eşler; böylece bütün bankalarınızın hareketlerini aynı tiplerle süzebilirsiniz. Eşlenemeyen hareket OTHER olur.

`canonicalType`	Anlamı
`TRANSFER_IN`	Gelen havale/EFT
`TRANSFER_OUT`	Giden havale/EFT
`INTERNAL_IN`	Hesaplar arası giriş
`INTERNAL_OUT`	Hesaplar arası çıkış
`POS_SETTLEMENT`	POS hesaba geçiş
`POS_SETTLEMENT_REFUND`	POS iadesi
`FEE`	Masraf / komisyon
`TAX`	Vergi
`CASH_IN`	Nakit yatırma
`CASH_OUT`	Nakit çekme
`CARD`	Kart işlemi
`LOAN`	Kredi
`FX`	Döviz işlemi
`INTEREST`	Faiz
`OTHER`	Diğer

Para transferi

Bağlantınız transfer destekliyorsa (capabilities içinde OUTGOING_TRANSFER) bağlı hesabınızdan bir IBAN'a para gönderebilirsiniz; API'den Para Transferi uçlarıyla, panelden Para gönder ile. Lunixi bakiye kontrolü yapmaz; transferi bankaya iletir ve bankanın cevabına göre durumunu günceller.

Transfer durumları

Durum	Anlamı	Son durum mu
`PENDING_OTP`	Yalnız panelden başlatılan transferde: kullanıcının e-posta doğrulama kodu bekleniyor. API anahtarıyla oluşturulan transfer bu durumdan geçmez.	Hayır
`SUBMITTED`	Transfer onaylandı ve bankaya iletildi ya da iletilmek üzere sırada; bankanın cevabı bekleniyor.	Hayır
`PROCESSING`	Banka transferi işliyor.	Hayır
`COMPLETED`	Banka transferi tamamladı. Alıcı banka parayı sonradan iade ederse `RETURNED` olabilir.	Neredeyse — iade gelebilir
`FAILED`	Transfer gerçekleşmedi; sebep `failureCode` alanında.	Evet
`RETURNED`	Tamamlanan transfer alıcı bankadan iade edildi.	Evet
`CANCELED`	Transfer iptal edildi: doğrulama kodu süresinde onaylanmadı, kullanıcı ya da banka iptal etti.	Evet

Panelden başlatılan transfer PENDING_OTP, API ile oluşturulan transfer SUBMITTED durumunda başlar. outcomeUnknown: true olan transfer SUBMITTED durumunda bekler — tekrar göndermeyin. COMPLETED, alıcı banka parayı iade etmedikçe son durumdur.

PROCESSING her bankada görülmez; transfer SUBMITTED durumundan doğrudan sonuçlanabilir.
outcomeUnknown true ise bankanın cevabı henüz doğrulanamamıştır ve transfer SUBMITTED durumunda bekler. Transferi yeniden göndermeyin; Lunixi sonucu bankayla doğrular. → Para Transferi › Sonucu doğrulanamayan transfer
Tamamlanan transfer bir sonraki hesap okumasında hesabınızın hareketlerinde de giden hareket olarak görünür; eşleşen hareketin kimliği transferin bankTransactionId alanına yazılır.

Transfer yolu (`rail`)

Transferin hangi yoldan gideceğine banka karar verir; siz seçmezsiniz.

`rail`	Anlamı
`INTERNAL`	Aynı bankadaki kendi hesaplarınız arası (virman).
`INTRABANK`	Aynı bankadaki başka bir hesaba (havale).
`FAST`	FAST ile başka bankaya.
`EFT`	EFT ile başka bankaya. EFT kapanış saatinden sonra gönderilen transfer reddedilebilir (`bank_connect.transfer.eft_cutoff_passed`).
`UNKNOWN`	Banka yolu henüz bildirmedi.

Banka yolu bildirene kadar alan null olabilir.

Döviz işlemi

Bağlantınız döviz işlemi destekliyorsa (capabilities içinde FX_EXCHANGE) aynı bankadaki iki hesabınız arasında döviz alıp satabilirsiniz; API'den Döviz İşlemi uçlarıyla, panelden Döviz çevir ile.

Teklif hiçbir tutarı bloke etmez ve kısa süre geçerlidir; işlemi expiresAt dolmadan açın. Sonucu işlem ucundan okuyun — döviz işlemleri için webhook gönderilmez.

Kavram	Açıklama
Kaynak hesap	Sattığınız para biriminin hesabı; tutar buradan çıkar.
Hedef hesap	Aldığınız para biriminin hesabı; tutar buraya girer. Kaynak hesapla aynı bağlantıda, farklı para biriminde olmalıdır.
Teklif	Bankanın uygulayacağı kur ve iki taraftaki tutar. Hiçbir şeyi bloke etmez; geçerlilik süresini banka belirler (çoğunlukla bir iki dakika). Bir teklifle yalnız bir işlem açılır.
İşlem	Teklifin işleme alınması. `SUBMITTED` durumunda açılır, bankanın cevabına göre `COMPLETED` ya da `FAILED` olur.

Döviz işlemleri için webhook gönderilmez; sonucu işlem ucundan sorgulayın.

Tazelik

Hesaplarınız bankadan belirli aralıklarla okunur; veri anlık değildir. Her hesap, verinin ne kadar taze olduğunu freshness nesnesiyle bildirir:

Alan	Anlamı
`lastSuccessfulSyncAt`	Bankadan en son başarılı okumanın zamanı
`nextSyncAvailableAt`	Bir sonraki okumanın en erken zamanı
`minSyncIntervalSeconds`	İki okuma arasındaki en kısa süre (saniye). Değer bağlantıya göre değişebilir; sabit bir değer varsaymayın, bu alandan okuyun.

Okuma aralığı kısaltılamaz. Şimdi yenile isteği de bu aralığa uyar: aralık dolmadıysa okuma nextSyncAvailableAt zamanına planlanır.

Bağlantı DEGRADED durumundayken okumalar başarısız olduğu için veri eski kalabilir; lastSuccessfulSyncAt ilerlemez.

Ortam

Ortamı API anahtarınız belirler. Test anahtarı (mk_test_…) yalnız test ortamındaki bağlantıları ve verileri, canlı anahtar (mk_live_…) yalnız canlı ortamdakileri görür. İstekte ortam göndermezsiniz; gönderirseniz istek 400 VALIDATION_ERROR ile reddedilir. Test ortamı için: Test Ortamı.

Maskeleme

Kişisel ve hassas banka verileri API'de ve webhook'ta yalnız maskeli döner:

Veri	Alan	Biçim
Hesabınızın IBAN'ı	`ibanMasked`	`TR00 ** 00 00` — ülke kodu, kontrol hanesi ve son 4 hane görünür
Hesap numarası	`accountNumberMasked`	`****0000` — son 4 hane görünür
Karşı tarafın adı	`counterpartyNameMasked`	`Ö** A**` — her kelimenin ilk harfi görünür
Karşı tarafın IBAN'ı	`counterpartyIbanMasked`	IBAN ile aynı biçim
Transfer alıcısının IBAN'ı ve adı	`receiverIbanMasked`, `receiverNameMasked`	IBAN ve ad ile aynı biçim

Hiç dönmeyen veriler: tam IBAN, tam hesap numarası, hesap sahibinin adı, karşı tarafın ve transfer alıcısının tam adı ve VKN/TCKN.

⚠️

Hareket açıklaması (description) bankanın yazdığı gibi, maskelenmeden döner; ödeme açıklamasındaki referans kodlarıyla eşleştirme yapabilmeniz içindir. Bankanın açıklamaya yazdığı bilgiler (ör. gönderenin adı) bu alanda olduğu gibi görünebilir.

Genel Bakış Panelden Banka Bağlama