BKM ÖHVPS v2.0.0 · Açık Bankacılık

Bankalarla/Kurumlarla aranızdaki güvenli hat.

FinevoConnect YÖS, kullanıcıların birden çok bankadaki/kurumdaki hesap, bakiye, kart ve ödemelerini tek bir izinli bağlantıyla yönetmesini sağlayan YÖS/TPP arka ucudur. Kullanıcı bir kez rıza verir; sistem onun adına bankayla/kurumla konuşur, veriyi toplar, sade bir API olarak sunar.

Hızlı Başlangıç →API Uçları

Kısaca ne işe yarar?

Diyelim ki üç ayrı bankada/kurumda hesabınız var. Normalde her biri için ayrı uygulamaya girer, ayrı ayrı bakiyeye bakarsınız. FinevoConnect YÖS'te bir kez kaydolursunuz, her bankaya/kuruma bir defa izin verirsiniz — o andan sonra üç bankanın/kurumun hesabını, kartını, işlem geçmişini tek yerden görürsünüz; istediğinizde yine tek yerden ödeme başlatırsınız. Bankalarla/Kurumlarla konuşan tüm teknik iş perde arkasındadır.

Kim, ne için kullanır?

FinevoConnect YÖS bir altyapıdır: doğrudan kullanıcısı son kişi değil, üzerine uygulama kuran geliştiricilerdir. Zincir şöyle:

Son kullanıcı

Banka/Kurum müşterisi. Bir uygulama üzerinden "hesaplarımı bağla" der, bankanın/kurumun onay ekranından geçer, sonra hesaplarını görür.

Uygulama / geliştirici

FinevoConnect YÖS'ün web servislerini çağıran taraf. Kendi ekranını çizer; verileri ve ödeme işlemlerini bu sistemden ister.

FinevoConnect YÖS (biz)

Ortadaki YÖS altyapısı. Kimliği yönetir, izinleri tutar, bankalarla/kurumlarla konuşur, veriyi toplayıp sade biçimde sunar.

Sistem kimlerden oluşur?

apps/api — Public API

Kullanıcıların/uygulamaların konuştuğu web servisi. Çok kullanıcılı: uygulama anahtarı (X-App-Key) + kullanıcı kimliği → JWT. Bankaya/Kuruma hiç bağlanmaz — veriyi paylaşılan veritabanından okur, işi batch'e ya senkron iç RPC ile (rıza açma, iptal, callback, canlı okuma) ya da dayanıklı niyet kutusuna (SyncIntent outbox — ödeme/periyodik) yazarak devreder. Bu kural mimari testlerle zorlanır.

apps/batch — Arka plan işçisi

Bankalarla/Kurumlarla konuşan tek taraf (Hangfire). Niyet kutusunu tüketir, bankaya/kuruma mTLS+JWS ile bağlanır, hesap/kart/ödeme verisini paylaşılan MSSQL'e yazar. Dışarıya açık REST sunmaz; yalnız API'nin çağırdığı iç uçları (canlı okuma, rıza ve callback RPC'leri) ve banka/kurum olay webhook'unu barındırır.

Neden ikiye bölünmüş? Güvenlik ve hız. Sertifikalar ile imza anahtarları yalnız batch'te durur; API tarafının açığı banka/kurum erişimine ulaşamaz. API sadece DB okuduğu için hızlı yanıt verir; yavaş olabilecek banka/kurum konuşmaları arka planda ayrı yürür. Tek istisna ?fresh=true: kullanıcı o anki veriyi istediğinde API, batch'in iç ucunu senkron çağırır; taze banka/kurum verisi aynı istek içinde döner.

Temel akış: bir hesap nasıl bağlanır?

Kayıt / giriş
POST /api/v1/auth/register → JWT
Uygulama, kendi anahtarı (X-App-Key) ve kullanıcının kimliğiyle (userKey + customerNo) kayıt ucunu çağırır; imzalı bir erişim token'ı (JWT) alır. Aynı uç sonraki girişlerde de kullanılır; sonraki her istek bu token ile gönderilir.
Rıza oluşturma
POST /api/v1/hhs-connections → batch (iç RPC)
"Hesaplarıma erişmene izin veriyorum." API bankaya/kuruma doğrudan bağlanmaz: önce bağlantı kaydını veritabanına yazar, sonra batch'i senkron iç RPC ile çağırır. Kullanıcı yanıtı beklediği için niyet kutusu (outbox) değil, anlık RPC kullanılır.
Batch bankada/kurumda rızayı başlatır
POST /internal/... → mTLS+JWS
Batch RPC çağrısını alır, bankaya/kuruma mTLS+JWS ile bağlanır, rıza kaydını banka/kurum tarafında başlatır ve onay yönlendirme URL'ini aynı yanıtta geri döndürür.
Banka/Kurum onay ekranı (GKD)
yönlendirme → onay → callback
Kullanıcı kimliğini bankanın/kurumun kendi ekranında doğrular. Onay bitince banka/kurum bize yetki koduyla geri döner.
Erişim belirteci → Bağlandı
yetKod → erişim belirteci
API callback'i alır ve batch'i senkron iç RPC ile çağırır; batch yetki kodunu erişim belirtecine çevirir, bağlantıyı "Bağlandı" yapar. Belirteç ve kişisel bilgiler veritabanında şifreli saklanır.
Veri & ödeme
GET /accounts · ?fresh=true · POST /payment-orders
Kullanıcı hesap/bakiye/kart/işlemlerini görür. Varsayılan yerel önbellekten hızlı döner; ?fresh=true derse batch senkron çağrılıp o anki banka/kurum verisi aynı istekte döner (bkz. Canlı Okuma). Ödeme talimatı ise niyet kutusu üzerinden yazma yolunu izler.

Öne çıkan güvenceler

Kullanıcı izolasyonu

Herkes yalnız kendi verisine erişir; başkasının kaynağı 404 döner, varlığı bile sızmaz (BOLA).

Tekrar koruması

Aynı istek yanlışlıkla iki kez gelirse (örneğin "Öde" düğmesine iki kez basılırsa) iş yalnızca bir kez yapılır: yazma isteklerindeki Idempotency-Key başlığı ikinci çağrıyı yakalar, ilk çağrının kaydedilmiş yanıtını aynen döndürür. Ödemede ek güvence olarak işlem önce rezerve edilir, iş bitince tamamlanır — böylece yarıda kalan bir ödeme ikinci denemede yinelenmez.

Kayıp mesaj yok

API ile işçi outbox üzerinden haberleşir; iş en az bir kez işlenir, çift işlem engellenir.

Şifreli saklama

Banka/Kurum belirteçleri ve kişisel bilgiler veritabanında düz metin değil, şifreli tutulur.

Standarda birebir

Bankaya/Kuruma giden her alan adı ve kod, resmi ÖHVPS spesifikasyonuyla harfi harfine aynıdır.

Canlı & taze veri

Kullanıcı ekranın başındayken ?fresh=true ile o anki banka/kurum verisi aynı istekte anlık çekilir (senkron RPC); değilse hızlı yerel önbellek döner.

Çok dilli hatalar

RFC 7807 + makine-okunur kod + Türkçe/İngilizce açıklama + traceId.

Bu dokümanda ne var?

Hızlı Başlangıç

Kurulumdan ilk ödemeye adım adım; kopyala-çalıştır örneklerle.

Mimari

Parçalar nasıl birleşiyor, kim kiminle nasıl konuşuyor.

API Uçları

38 ucun tamamı: ne yapar, giriş gerekir mi.

Hata Kodları

48 kodun anlamı, HTTP karşılığı, Türkçe açıklaması.

Veritabanı

Tablolar ne tutuyor, nasıl ilişkili.

İstek Yaşam Döngüsü

Bir istek nerede başlar, hangi durakları geçer.

Canlı Okuma & PSU

?fresh=true nasıl anlık banka/kurum verisi çeker; kota-muaf senkron RPC yolu.

Referans (dosya-dosya)

Her dosya, her metot: ne yapar, kimi çağırır.

FinevoConnect YÖS sistem dokümantasyonu · BKM ÖHVPS v2.0.0 uyumlu YÖS/TPP backend · .NET 8 · Bu site yalnızca dokümantasyon amaçlıdır, canlı sisteme bağlı değildir.