Sıfırdan ilk ödemeye

Bu rehber, bulutta yayınlanan FinevoConnect YÖS'e bağlanmaktan bir bankayı/kurumu bağlamaya, hesap/bakiye görmeye ve ödeme başlatmaya kadar tüm yolu adım adım gösterir. Kod bilmesen de akışı takip edebilirsin; bilirsen örnekleri doğrudan kopyalayıp deneyebilirsin.

1. API adresi

FinevoConnect YÖS bulutta hazır yayında; kurulum yapman gerekmez. Tüm uçlar tek bir baz adresin altında:

2. Sağlığı doğrula

curl https://yos.91.98.230.19.nip.io/api/v1/health/ready   # -> 200 OK

3. Kayıt ol ve token al

Sistem çok kullanıcılıdır: herkes yalnız kendi bankalarını/kurumlarını, hesaplarını, ödemelerini görür. 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. Karşılığında JWT (kimliği kanıtlayan imzalı erişim token'ı) alınır; sonraki her istekte gösterilir.

# kayıt + token (kullanıcı zaten varsa yenisi açılmaz, yine token döner)
curl -X POST https://yos.91.98.230.19.nip.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-App-Key: aZ9BOJzxJLYDQ6LRTKgrnYRL0Mklru7P1T8RONZABz6brkRp" \
  -d '{ "userKey": "23456789138", "customerNo": "9570965931", "displayName": "Demo Kullanıcı" }'

# Yanıt:
# {
#   "accessToken":  "eyJhbGciOi...",  <- kısa ömürlü, her istekte kullan
#   "refreshToken": "d9f1c2...",      <- bitince /auth/refresh ile tazele
#   "expiresIn": 900
# }

Authorization: Bearer <accessToken>

4. Bir bankayı/kurumu bağla

İşin kalbi. Kullanıcı "şu bankadaki/kurumdaki hesaplarıma erişmene izin veriyorum" der; buna rıza (consent) denir. FinevoConnect YÖS bankaya/kuruma kendisi bağlanmaz — rızayı veritabanına yazar, banka/kurum konuşmasını batch'in iç ucunu senkron çağırarak (iç RPC) batch'e yaptırır:

# bankaları/kurumları listele
curl https://yos.91.98.230.19.nip.io/api/v1/hhs -H "Authorization: Bearer $TOKEN"

# rıza / bağlantı başlat
curl -X POST https://yos.91.98.230.19.nip.io/api/v1/hhs-connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "hhsId": "<banka/kurum-id>" }'
# -> { "connectionId": "...", "redirectUrl": "https://banka/kurum/onay?..." }

# kullanıcı redirectUrl'de onayladıktan sonra:
curl https://yos.91.98.230.19.nip.io/api/v1/hhs-connections \
  -H "Authorization: Bearer $TOKEN"
# -> status: "Connected" görene kadar bekle (birkaç saniye)

5. Veriyi gör

Bağlantı Connected olduğunda batch ilk hesap/bakiye/kart verisini çekip veritabanına yazar. Public API bu sorgularda bankaya/kuruma gitmez — veritabanından okur, bu yüzden hızlıdır. En güncel veri gerektiğinde isteğe ?fresh=true eklenir: API, batch üzerinden bankaya/kuruma canlı sorar ve taze veriyi aynı yanıtta döndürür.

# tüm bankalardaki/kurumlardaki hesaplar + bakiyeler tek listede
curl https://yos.91.98.230.19.nip.io/api/v1/accounts -H "Authorization: Bearer $TOKEN"

# bir hesabın işlem geçmişi (sayfa sayfa)
curl "https://yos.91.98.230.19.nip.io/api/v1/accounts/<hesapId>/transactions" \
  -H "Authorization: Bearer $TOKEN"

# kartlar
curl https://yos.91.98.230.19.nip.io/api/v1/cards -H "Authorization: Bearer $TOKEN"

# anlık taze veri: bankadan/kurumdan canlı çeker (biraz yavaş, en güncel)
curl "https://yos.91.98.230.19.nip.io/api/v1/hhs-connections/<id>?fresh=true" \
  -H "Authorization: Bearer $TOKEN"

6. Ödeme başlat

Ödeme, hesap bağlamayla aynı desendedir: emir oluştur → kullanıcı bankada/kurumda onaylar → banka/kurum geri döner → sonuç işlenir. Para hareketi olduğu için idempotency + iki fazlı tamamlanma devrededir.

curl -X POST https://yos.91.98.230.19.nip.io/api/v1/payment-orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceAccountId": "<gönderen-hesapId>",
    "amount": 125.50,
    "currency": "TRY",
    "creditorIban": "TR000000000000000000000000",
    "creditorName": "Alıcı Adı",
    "description": "Test ödemesi"
  }'

# yanıt: onay adresi -> kullanıcı onaylar -> durumu izle:
curl https://yos.91.98.230.19.nip.io/api/v1/payment-orders/<id> \
  -H "Authorization: Bearer $TOKEN"

Sorun giderme