API Uçları
Bu sayfada Public API'nin dış dünyaya açtığı tüm servis adresleri (uçlar) listelenir — toplam 40 uç. Her satır bir işlemi temsil eder: hangi yöntemle (GET = veri okuma, POST = yeni kayıt oluşturma, DELETE = silme) hangi adrese istek atılacağını gösterir. "Giriş" sütununda JWT yazan uçlar için önce register ile bir token almış olman gerekir; "açık" yazanlar (kayıt, token yenileme, banka callback'leri) token istemez.
http://127.0.0.1:8444 üzerinden yanıt verir. Aşağıdaki tüm yollar bu adrese eklenir ve hepsi /api/v1/... ile başlar. Örneğin hesap listesi için tam adres: http://127.0.0.1:8444/api/v1/accounts.Kimlik (Auth)
Kullanıcı hesapları burada yönetilir. Sistemde parola yoktur: kullanıcıyı, api-yos'u kullanan uygulama tanıtır. Uygulama kendini X-App-Key başlığındaki uygulama anahtarıyla kanıtlar; kullanıcıyı da userKey + customerNo ikilisiyle bildirir. Ayrı bir giriş ucu yoktur — register hem kayıt hem giriştir.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| POST | /api/v1/auth/register | Kullanıcıyı kaydeder ve token verir. X-App-Key başlığı + gövdede userKey ve customerNo gönderilir. Kullanıcı yoksa oluşturulur, zaten varsa yenisi açılmaz — her iki durumda da erişim token'ı (kısa ömürlü, her istekte kullanılır) ve yenileme token'ı döner. Yani sonraki girişlerde de aynı uç çağrılır. | açık |
| POST | /api/v1/auth/refresh | Erişim token'ının süresi dolunca tekrar giriş yapmadan yenisini almanı sağlar. Elindeki yenileme token'ını yollar, taze bir erişim token'ı alırsın. | açık |
| POST | /api/v1/auth/logout | Çıkış yapar: yenileme token'ını iptal eder, böylece o token'la artık yeni erişim token'ı üretilemez. | JWT |
| GET | /api/v1/auth/me | Şu an giriş yapmış kullanıcının kim olduğunu (userKey, customerNo, görünen ad, tercih ettiği dil) döndürür. Örneğin uygulamanın sağ üstünde ismi göstermek için kullanılır. | JWT |
Banka Bağlantıları (HHS Connections)
Kullanıcının bir bankaya bağlanması (rıza vermesi) akışını yönetir. Önce bağlantı başlatılır, kullanıcı bankanın onay ekranına yönlendirilir, onaylayınca banka callback ile geri döner. Callback'i banka çağırdığı için token gerektirmez.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| GET | /api/v1/hhs-connections | Kullanıcının şu ana kadar kurduğu tüm banka bağlantılarını (hangi banka, durumu ne) listeler. | JWT |
| GET | /api/v1/hhs-connections/{id} | Tek bir bağlantının ayrıntısını verir. Sonuna ?fresh=true eklersen sistem o an bankadan canlı veri çeker (biraz daha yavaş ama en güncel hâli). | JWT |
| POST | /api/v1/hhs-connections | Yeni bir bağlantı başlatır, yani bankaya rıza talebini oluşturur. Yanıtta kullanıcıyı bankanın onay ekranına götürecek adres döner. | JWT |
| GET | /api/v1/hhs-connections/callback | Yönlendirme (redirect) modu: kullanıcı bankanın onay ekranında işlemi bitirince banka onu bu adrese geri yönlendirir (GKD callback). Bağlantı burada tamamlanır. Callback'i banka çağırdığı için token gerektirmez. | açık |
| GET | /api/v1/hhs-connections/{id}/callback | Ayrık (poll) modu: uygulama, bağlantının tamamlanıp tamamlanmadığını sormak için bu ucu çağırır (yetKod bankadan yoklanır, erişim token'ı alınır, bağlantı tamamlanır). Token gerektirir. | JWT |
| DELETE | /api/v1/hhs-connections/{id} | Bir bağlantıyı / rızayı iptal eder. Bundan sonra o bankadan yeni veri çekilmez. | JWT |
Bankalar (HHS Registry)
Sistemin bağlanabildiği bankaların kataloğu. Kullanıcı, bağlantı kurmadan önce hangi bankaların desteklendiğini buradan görür.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| GET | /api/v1/hhs | Bağlanılabilecek tüm bankaların listesini döndürür. Örneğin bağlantı ekranındaki banka seçme kutusunu bu doldurur. | JWT |
| GET | /api/v1/hhs/{hhsCode} | Tek bir bankanın (kodu ile belirtilen) adı, adresi gibi ayrıntılarını verir. | JWT |
Hesaplar (Accounts)
Kullanıcının bağlı olduğu tüm bankalardaki hesaplar tek bir listede toplanır — hangi bankada olduğunu ayrı ayrı sormana gerek kalmaz. İşlem geçmişi uzun olabileceği için imleç (cursor) tabanlı sayfalanır; yani liste kaymadan sayfa sayfa gezersin.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| GET | /api/v1/accounts | Bağlı tüm bankalardaki hesapları, bakiyeleriyle birlikte tek listede döndürür. Örneğin GET /api/v1/accounts üç farklı bankadaki hesapları aynı yanıtta getirir. | JWT |
| GET | /api/v1/accounts/{id} | Tek bir hesabın ayrıntısını (IBAN, tür, bakiye) verir. | JWT |
| GET | /api/v1/accounts/{id}/transactions | Bir hesabın işlem (harcama/gelen para) geçmişini döndürür. Tarih aralığı, tutar gibi filtreler uygulanabilir; sonuçlar sayfa sayfa gelir. | JWT |
| POST | /api/v1/accounts/refresh | Hesap ve bakiye bilgilerinin bankadan yeniden çekilmesini elle tetikler. Örneğin kullanıcı 'yenile' düğmesine basınca çağrılır. | JWT |
Kartlar (Cards)
Kullanıcının bağlı bankalardaki kredi/banka kartları. Kart işlem geçmişi de hesaplarda olduğu gibi sayfa sayfa (imleç tabanlı) gelir.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| GET | /api/v1/cards | Bağlı tüm bankalardaki kartları tek listede döndürür. | JWT |
| GET | /api/v1/cards/{id} | Tek bir kartın özet bilgisini (kart adı, son 4 hane gibi) verir. | JWT |
| GET | /api/v1/cards/{id}/detail | Kartın ayrıntısını verir: kart limiti, güncel borç, ekstre tipi gibi bilgiler. | JWT |
| GET | /api/v1/cards/{id}/transactions | Kartla yapılan harcamaların geçmişini döndürür; sonuçlar sayfa sayfa gelir. | JWT |
| GET | /api/v1/cards/{id}/statements | Kredi kartının ekstre dönemlerini listeler (dönem, kesim tarihi, son ödeme tarihi, dönem borcu gibi). | JWT |
| GET | /api/v1/cards/{id}/statement-transactions | Seçilen ekstre dönemine ait kart hareketlerini döndürür; sonuçlar sayfa sayfa gelir. | JWT |
Ödeme Emirleri (Payment Orders)
Tek seferlik bir para gönderme işlemi. Her ödeme kendi rızasını kendi taşır — yani önceden kurulmuş bir banka bağlantısına ihtiyaç yoktur. Oluştururken Idempotency-Key başlığı zorunludur (aynı isteği yanlışlıkla iki kez yollasan bile ödeme yalnızca bir kez yapılır).
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| POST | /api/v1/payment-orders | Yeni bir ödeme emri oluşturur ve rıza akışını başlatır. Yanıtta kullanıcıyı bankanın onay ekranına götürecek adres döner. | JWT |
| GET | /api/v1/payment-orders | Kullanıcının verdiği ödeme emirlerini listeler; sonuçlar sayfa sayfa gelir. | JWT |
| GET | /api/v1/payment-orders/{id} | Tek bir ödeme emrinin ayrıntısını ve o an hangi aşamada olduğunu (beklemede, tamamlandı, reddedildi) gösterir. | JWT |
| GET | /api/v1/payment-orders/callback | Kullanıcı ödemeyi bankada onayladıktan sonra banka bu adrese geri döner (GKD callback). Ödeme burada sonuçlanır. | açık |
Düzenli Ödemeler (Recurring Payments)
Belirli aralıklarla (örneğin her ay) otomatik tekrar eden ödeme talimatları. Bir kez kurulur, planına göre kendiliğinden işler.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| POST | /api/v1/recurring-payments | Yeni bir düzenli ödeme talimatı oluşturur (örneğin her ayın 1'inde şu tutarı şu hesaba gönder). | JWT |
| GET | /api/v1/recurring-payments | Kullanıcının kurduğu düzenli ödeme talimatlarını listeler; sonuçlar sayfa sayfa gelir. | JWT |
| GET | /api/v1/recurring-payments/{id} | Tek bir talimatın ayrıntısını (tutar, sıklık, durum) verir. | JWT |
| GET | /api/v1/recurring-payments/{id}/plan | Talimatın ödeme takvimini gösterir: gelecekte hangi tarihlerde ne kadar ödeneceği. | JWT |
| GET | /api/v1/recurring-payments/callback | Talimat bankada onaylandığında banka bu adrese geri döner (GKD callback). | açık |
| DELETE | /api/v1/recurring-payments/{id} | Düzenli ödeme talimatını iptal eder; bundan sonraki otomatik ödemeler durur. | JWT |
İleri Tarihli Ödemeler (Forward-Dated)
Bugün oluşturulan ama gelecekte belirli bir günde gerçekleşecek tek seferlik ödemeler. Örneğin bir kira ödemesini ayın sonuna zamanlarsın.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| POST | /api/v1/forward-dated-payments | Gelecekteki bir tarihe zamanlanmış tek seferlik bir ödeme oluşturur. | JWT |
| GET | /api/v1/forward-dated-payments | İleri tarihli ödemeleri listeler; sonuçlar sayfa sayfa gelir. | JWT |
| GET | /api/v1/forward-dated-payments/{id} | Tek bir ileri tarihli ödemenin ayrıntısını (tutar, planlanan tarih, alıcı) verir. | JWT |
| GET | /api/v1/forward-dated-payments/{id}/status | Ödemenin şu anki durumunu gösterir: henüz bekliyor mu, gerçekleşti mi, iptal mi edildi. | JWT |
| GET | /api/v1/forward-dated-payments/callback | Ödeme bankada onaylandığında banka bu adrese geri döner (GKD callback). | açık |
| DELETE | /api/v1/forward-dated-payments/{id} | Ödeme henüz gerçekleşmediyse iptal eder. Planlanan gün gelip ödeme yapıldıysa artık iptal edilemez. | JWT |
Sağlık (Health)
Servisin ayakta olup olmadığını denetleyen teknik uçlar. Genelde kullanıcı değil, izleme/altyapı sistemleri çağırır.
| Yöntem | Yol | Ne yapar | Giriş |
|---|---|---|---|
| GET | /api/v1/health/live | Uygulamanın kendisi çalışıyor mu diye bakar (liveness). Cevap veriyorsa süreç ayaktadır. | açık |
| GET | /api/v1/health/ready | Uygulama iş görmeye hazır mı diye bakar (readiness): veritabanı gibi bağımlılıklara erişebiliyor mu kontrol eder. | açık |