Sıfırdan ilk ödemeye

Bu rehber, api-yos'u kendi makinende ayağa kaldırmaktan bir bankayı 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. Ortamı hazırla

api-yos üç parçadan oluşur ve hepsi Docker ile gelir: MSSQL (veritabanı), apps/api (Public API) ve apps/batch (bankalarla konuşan işçi). Önce ayarları kopyala, gizli değerleri doldur:

cp .env.example .env

# En az bunları ayarla:
#   MSSQL_SA_PASSWORD       -> SA parolası (yalnız DB + login oluşturmada; uygulamalar sa ile bağlanmaz)
#   YOS_APP_DB_PASSWORD     -> uygulama giriş parolası (api + batch yos_app olarak bağlanır)
#   CODE_AGENT_DB_PASSWORD  -> salt-okunur code_agent DB kullanıcısının parolası
#   JWT_SIGNING_KEY         -> JWT imzalama anahtarı (uzun, rastgele)
#   OHVPS_* (batch)         -> banka (HHS) bağlantı ayarları

2. Servisleri başlat

docker compose up --build
# mssql + api-yos + batch "healthy" olana kadar bekle

3. Sağlığı doğrula

curl http://127.0.0.1:8444/api/v1/health/ready   # -> 200 OK
curl http://127.0.0.1:8445/api/v1/health/ready   # -> 200 OK

4. Kayıt ol ve token al

Sistem çok kullanıcılıdır: herkes yalnız kendi bankalarını, hesaplarını, ödemelerini görür. 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. Karşılığında JWT (imzalı dijital giriş bileti) 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 http://127.0.0.1:8444/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-App-Key: dev-app-key-0123456789abcdef" \
  -d '{ "userKey": "demo-user-1", "customerNo": "1001", "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>

5. Bir bankayı bağla

İşin kalbi. Kullanıcı "şu bankadaki hesaplarıma erişmene izin veriyorum" der; buna rıza (consent) denir. api-yos bunu doğrudan bankaya iletmez — niyet kutusuna yazar, bankayla konuşmayı batch yürütür:

# bankaları listele
curl http://127.0.0.1:8444/api/v1/hhs -H "Authorization: Bearer $TOKEN"

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

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

6. Veriyi gör

Bağlantı Connected olduğunda batch ilk hesap/bakiye/kart verisini çekip veritabanına yazar. Public API bu sorgularda bankaya gitmez — veritabanından okur, bu yüzden hızlıdır.

# tüm bankalardaki hesaplar + bakiyeler tek listede
curl http://127.0.0.1:8444/api/v1/accounts -H "Authorization: Bearer $TOKEN"

# bir hesabın işlem geçmişi (sayfa sayfa)
curl "http://127.0.0.1:8444/api/v1/accounts/<hesapId>/transactions" \
  -H "Authorization: Bearer $TOKEN"

# kartlar
curl http://127.0.0.1:8444/api/v1/cards -H "Authorization: Bearer $TOKEN"

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

7. Ödeme başlat

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

curl -X POST http://127.0.0.1:8444/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 http://127.0.0.1:8444/api/v1/payment-orders/<id> \
  -H "Authorization: Bearer $TOKEN"

Sorun giderme