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/kurum callback'leri) token istemez. Her ucun altındaki Dene panelini aç: örnek istek ve yanıtı görür, düzenleyip gerçek FinevoConnect YÖS'e canlı gönderebilirsin.
https://yos.91.98.230.19.nip.io ü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: https://yos.91.98.230.19.nip.io/api/v1/accounts.X-App-Key önceden tanımlı) denemek için indir: koleksiyon (.json) · environment (.json). Ayrıntı için Koleksiyonlar.Canlı Konsol
Aşağıdaki her ucun altında bir Dene düğmesi var: aç, örnek gövdeyi düzenle, gerçek FinevoConnect YÖS'e gönder ve canlı yanıtı gör. Paneller sakin kalsın diye kapalı başlar — aynı anda yalnız biri açılır. Önce aşağıdaki karttan bir token al; JWT isteyen uçlara otomatik eklenir.
register ucuna gider, dönen erişim token’ını saklar. JWT isteyen uçlara otomatik eklenir. İstekler docs sunucusu üzerinden bulut FinevoConnect YÖS’e (yos.91.98.230.19.nip.io) proxy’lenir — tarayıcı CORS’a takılmaz.
Kimlik (Auth)
Kullanıcı hesapları burada yönetilir. Sistemde parola yoktur: kullanıcıyı, FinevoConnect YÖS'ü 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.
/api/v1/auth/registeraçıkKullanı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.
/api/v1/auth/refreshaçıkEriş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.
/api/v1/auth/logoutJWTÇıkış yapar: yenileme token'ını iptal eder, böylece o token'la artık yeni erişim token'ı üretilemez.
/api/v1/auth/meJWTŞ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.
Banka/Kurum Bağlantıları (HHS Connections)
Kullanıcının bir bankaya/kuruma bağlanması (rıza vermesi) akışını yönetir. Önce bağlantı başlatılır, kullanıcı bankanın/kurumun onay ekranına yönlendirilir, onaylayınca banka/kurum callback ile geri döner. Callback'i banka/kurum çağırdığı için token gerektirmez.
/api/v1/hhs-connectionsJWTKullanıcının şu ana kadar kurduğu tüm banka/kurum bağlantılarını (hangi banka/kurum, durumu ne) listeler.
/api/v1/hhs-connections/{id}JWTTek bir bağlantının ayrıntısını verir. Sonuna ?fresh=true eklersen sistem o an bankadan/kurumdan canlı veri çeker (biraz daha yavaş ama en güncel hâli).
/api/v1/hhs-connectionsJWTYeni bir bağlantı başlatır, yani bankaya/kuruma rıza talebini oluşturur. Yanıtta kullanıcıyı bankanın/kurumun onay ekranına götürecek adres döner. accessDurationDays alanı zorunludur: en az 1 gün olmalıdır; üst sınır bireysel (tckn) müşteride yaklaşık 6 ay, kurumsal (vkn) müşteride yaklaşık 12 aydır. İsteğe bağlı consumerSuccessUrl / consumerErrorUrl alanlarıyla, onay bitince kullanıcının döneceği adresleri istek başına verebilirsin; adresin host'u uygulamanın izinli host listesinde olmalıdır (değilse 422), verilmezse ortam ayarındaki varsayılan adresler kullanılır.
/api/v1/hhs-connections/callbackaçıkYönlendirme (redirect) modu: kullanıcı bankanın/kurumun onay ekranında işlemi bitirince banka/kurum onu bu adrese geri yönlendirir (GKD callback). Bağlantı burada tamamlanır. Callback'i banka/kurum çağırdığı için token gerektirmez.
/api/v1/hhs-connections/{id}/callbackJWTAyrık (poll) modu: uygulama, bağlantının tamamlanıp tamamlanmadığını sormak için bu ucu çağırır (yetKod bankadan/kurumdan yoklanır, erişim token'ı alınır, bağlantı tamamlanır). Token gerektirir.
/api/v1/hhs-connections/{id}JWTBir bağlantıyı / rızayı iptal eder. Bundan sonra o bankadan/kurumdan yeni veri çekilmez.
Bankalar/Kurumlar (HHS Registry)
Sistemin bağlanabildiği bankaların/kurumların kataloğu. Kullanıcı, bağlantı kurmadan önce hangi bankaların/kurumların desteklendiğini buradan görür.
/api/v1/hhsJWTBağlanılabilecek tüm bankaların/kurumların listesini döndürür. Örneğin bağlantı ekranındaki banka/kurum seçme kutusunu bu doldurur.
/api/v1/hhs/{hhsCode}JWTTek bir bankanın/kurumun (kodu ile belirtilen) adı, adresi gibi ayrıntılarını verir.
Hesaplar (Accounts)
Kullanıcının bağlı olduğu tüm bankalardaki/kurumlardaki hesaplar tek bir listede toplanır — hangi bankada/kurumda 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.
/api/v1/accountsJWTBağlı tüm bankalardaki/kurumlardaki hesapları, bakiyeleriyle birlikte tek listede döndürür. Örneğin GET /api/v1/accounts üç farklı bankadaki/kurumdaki hesapları aynı yanıtta getirir.
/api/v1/accounts/{id}JWTTek bir hesabın ayrıntısını (IBAN, tür, bakiye) verir.
/api/v1/accounts/{id}/transactionsJWTBir 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.
/api/v1/accounts/refreshJWTHesap ve bakiye bilgilerinin bankadan/kurumdan yeniden çekilmesini elle tetikler. Örneğin kullanıcı 'yenile' düğmesine basınca çağrılır.
Kartlar (Cards)
Kullanıcının bağlı bankalardaki/kurumlardaki kredi/banka/kurum kartları. Kart işlem geçmişi de hesaplarda olduğu gibi sayfa sayfa (imleç tabanlı) gelir.
/api/v1/cardsJWTBağlı tüm bankalardaki/kurumlardaki kartları tek listede döndürür.
/api/v1/cards/{id}JWTTek bir kartın özet bilgisini (kart adı, son 4 hane gibi) verir.
/api/v1/cards/{id}/detailJWTKartın ayrıntısını verir: kart limiti, güncel borç, ekstre tipi gibi bilgiler.
/api/v1/cards/{id}/transactionsJWTKartla yapılan harcamaların geçmişini döndürür; sonuçlar sayfa sayfa gelir.
/api/v1/cards/{id}/statementsJWTKredi kartının ekstre dönemlerini listeler (dönem, kesim tarihi, son ödeme tarihi, dönem borcu gibi).
/api/v1/cards/{id}/statement-transactionsJWTSeçilen ekstre dönemine ait kart hareketlerini döndürür; sonuçlar sayfa sayfa gelir.
Ö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/kurum 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).
/api/v1/payment-ordersJWTYeni bir ödeme emri oluşturur ve rıza akışını başlatır. Yanıtta kullanıcıyı bankanın/kurumun onay ekranına götürecek adres döner. Opsiyonel consumerSuccessUrl / consumerErrorUrl ile onay sonrası dönüş adresleri istek başına verilebilir (host, uygulamanın izinli listesinde olmalı; verilmezse ortam varsayılanı).
/api/v1/payment-ordersJWTKullanıcının verdiği ödeme emirlerini listeler; sonuçlar sayfa sayfa gelir.
/api/v1/payment-orders/{id}JWTTek bir ödeme emrinin ayrıntısını ve o an hangi aşamada olduğunu (beklemede, tamamlandı, reddedildi) gösterir.
/api/v1/payment-orders/callbackaçıkKullanıcı ödemeyi bankada/kurumda onayladıktan sonra banka/kurum bu adrese geri döner (GKD callback). Ödeme burada sonuçlanır.
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.
/api/v1/recurring-paymentsJWTYeni bir düzenli ödeme talimatı oluşturur (örneğin her ayın 1'inde şu tutarı şu hesaba gönder). Opsiyonel consumerSuccessUrl / consumerErrorUrl ile onay sonrası dönüş adresleri istek başına verilebilir (host, uygulamanın izinli listesinde olmalı; verilmezse ortam varsayılanı).
/api/v1/recurring-paymentsJWTKullanıcının kurduğu düzenli ödeme talimatlarını listeler; sonuçlar sayfa sayfa gelir.
/api/v1/recurring-payments/{id}JWTTek bir talimatın ayrıntısını (tutar, sıklık, durum) verir.
/api/v1/recurring-payments/{id}/planJWTTalimatın ödeme takvimini gösterir: gelecekte hangi tarihlerde ne kadar ödeneceği.
/api/v1/recurring-payments/callbackaçıkTalimat bankada/kurumda onaylandığında banka/kurum bu adrese geri döner (GKD callback).
/api/v1/recurring-payments/{id}JWTDüzenli ödeme talimatını iptal eder; bundan sonraki otomatik ödemeler durur.
İ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.
/api/v1/forward-dated-paymentsJWTGelecekteki bir tarihe zamanlanmış tek seferlik bir ödeme oluşturur. Opsiyonel consumerSuccessUrl / consumerErrorUrl ile onay sonrası dönüş adresleri istek başına verilebilir (host, uygulamanın izinli listesinde olmalı; verilmezse ortam varsayılanı).
/api/v1/forward-dated-paymentsJWTİleri tarihli ödemeleri listeler; sonuçlar sayfa sayfa gelir.
/api/v1/forward-dated-payments/{id}JWTTek bir ileri tarihli ödemenin ayrıntısını (tutar, planlanan tarih, alıcı) verir.
/api/v1/forward-dated-payments/{id}/statusJWTÖdemenin şu anki durumunu gösterir: henüz bekliyor mu, gerçekleşti mi, iptal mi edildi.
/api/v1/forward-dated-payments/callbackaçıkÖdeme bankada/kurumda onaylandığında banka/kurum bu adrese geri döner (GKD callback).
/api/v1/forward-dated-payments/{id}JWTÖdeme henüz gerçekleşmediyse iptal eder. Planlanan gün gelip ödeme yapıldıysa artık iptal edilemez.
Sağlık (Health)
Servisin ayakta olup olmadığını denetleyen teknik uçlar. Genelde kullanıcı değil, izleme/altyapı sistemleri çağırır.
/api/v1/health/liveaçıkUygulamanın kendisi çalışıyor mu diye bakar (liveness). Cevap veriyorsa süreç ayaktadır.
/api/v1/health/readyaçıkUygulama iş görmeye hazır mı diye bakar (readiness): veritabanı gibi bağımlılıklara erişebiliyor mu kontrol eder.