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

Bankalarla aranızdaki güvenli hat.

api-yos, kullanıcıların birden çok bankadaki 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 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 hesabınız var. Normalde her biri için ayrı uygulamaya girer, ayrı ayrı bakiyeye bakarsınız. api-yos'ta bir kez kaydolursunuz, her bankaya bir defa izin verirsiniz — o andan sonra üç bankanın 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 konuşan tüm teknik iş perde arkasındadır.

Kim, ne için kullanır?

api-yos 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 müşterisi. Bir uygulama üzerinden "hesaplarımı bağla" der, bankanın onay ekranından geçer, sonra hesaplarını görür.

Uygulama / geliştirici

api-yos'un web servislerini çağıran taraf. Kendi ekranını çizer; verileri ve ödeme işlemlerini bu sistemden ister.

api-yos (biz)

Ortadaki YÖS altyapısı. Kimliği yönetir, izinleri tutar, bankalarla 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 hiç bağlanmaz — veriyi paylaşılan veritabanından okur, işi batch'e ya senkron iç RPC ile (rıza açma, callback, canlı okuma) ya da dayanıklı niyet kutusuna (SyncIntent outbox — ödeme/iptal/periyodik) yazarak devreder. Bu kural mimari testlerle zorlanır.

apps/batch — Arka plan işçisi

Bankalarla konuşan tek taraf (Hangfire). Niyet kutusunu tüketir, bankaya mTLS+JWS ile bağlanır, hesap/kart/ödeme verisini paylaşılan MSSQL'e yazar. Public REST sunmaz.

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 erişimine ulaşamaz. API sadece DB okuduğu için hızlı yanıt verir; yavaş olabilecek banka konuşmaları arka planda ayrı yürür. Karşı taraf ise api-hhs: geliştirmede gerçek bankayı taklit eden simülatör (HHS).

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 giriş bileti (JWT) alır. Aynı uç sonraki girişlerde de kullanılır; sonraki her istekte bu bilet gösterilir.
Rıza oluşturma
POST /api/v1/hhs-connections → batch (iç RPC)
"Hesaplarıma erişmene izin veriyorum." API bankaya 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 rızayı başlatır
POST /internal/... → mTLS+JWS
Batch RPC çağrısını alır, bankaya mTLS+JWS ile bağlanır, rıza kaydını banka tarafında başlatır ve onay yönlendirme URL'ini aynı yanıtta geri döndürür.
Banka onay ekranı (GKD)
yönlendirme → onay → callback
Kullanıcı kimliğini bankanın kendi ekranında doğrular. Onay bitince banka 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 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 iki kez gelse bir kez işlenir (Idempotency-Key). Ödemede rezerve→tamamla iki faz.

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 belirteçleri ve kişisel bilgiler veritabanında düz metin değil, şifreli tutulur.

Standarda birebir

Bankaya 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 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 verisi çeker; kota-muaf senkron RPC yolu.

Referans (dosya-dosya)

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

api-yos 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.