API'ye Giriş

Banka Hesapları API'si, panelden bağladığınız bankalardaki hesapları, bakiyeleri ve hareketleri kendi sunucunuzdan okumanızı sağlar. Bağlantınız destekliyorsa aynı API ile bağlı hesabınızdan para transferi ve hesaplarınız arasında döviz işlemi de yapabilirsiniz. Para hareketi uçları ayrı bir yetki ve IP izin listesi ister; okuma uçları bunlardan etkilenmez.

Uçlar

Taban adres: https://api-gateway.lunixi.com/api/v1/bank-connect

Bankayı bağlama ve bağlantıyı kesme için uç yoktur; bunlar yalnız panelden yapılır. → Panelden Banka Bağlama

Kimlik doğrulama

Bu uçlar her istekte API anahtarınızla imzalanmış istek ister. Authorization: Bearer jetonu ve panel oturumu kimlik yerine geçmez; imza başlıkları olmayan istek 401 AUTH_HEADERS_MISSING alır.

İmzalanan kanonik dizi YÖNTEM, tam yol, X-Date:… ve X-Nonce:… satırlarının \n ile birleşimidir. Okuma uçlarının gövdesi olmadığı için Digest satırı yazılmaz; gövdeli para hareketi isteklerinin imzası: Para Transferi › Gövdeli isteği imzalama. Kanonik dizinin kuralları ve anahtar yönetimi: Kimlik Doğrulama › Kanonik dize.

Bu bölümdeki cURL örnekleri imzayı aşağıdaki kabuk fonksiyonuyla hesaplar (OpenSSL 3.0 veya üstü gerekir):

# lunixi-sign.sh — Kullanım: source lunixi-sign.sh; lunixi_sign GET "/api/v1/bank-connect/accounts"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

PHP SDK

PHP örnekleri PHP SDK'nın (lunixi/php-sdk, 0.14.0 ve üstü; para transferi ve döviz için 0.22.0 ve üstü) bankConnect() istemcisini kullanır. SDK her isteği sizin yerinize imzalar:

use Lunixi\Sdk\LunixiClient;
 
$lunixi = LunixiClient::create([
    'baseUrl'     => 'https://api-gateway.lunixi.com',
    'keyId'       => getenv('LUNIXI_KEY_ID'),
    'privateKey'  => getenv('LUNIXI_PRIVATE_KEY_PEM'),
    'environment' => 'TEST', // anahtarınızın ortamı: TEST ya da LIVE
]);
 
$bankConnect = $lunixi->bankConnect();

• Liste yöntemleri (listBanks, listConnections, listAccounts, listBalances, listTransactions) tek bir sayfa döner: items(), hasMore(), nextCursor(). Aynı adlı iterate… yöntemleri bütün sayfaları sizin yerinize dolaşır.
• SDK tanımadığı süzgeçleri, değer kümesi dışındaki değerleri ve kurala uymayan tarih ya da tutar aralıklarını istek göndermeden Lunixi\Sdk\Exception\ConfigurationException ile reddeder.
• API hataları Lunixi\Sdk\Exception\ApiException olarak gelir; getStatusCode() ve getErrorCode() ile dallanın.

Yetkiler

İmza doğrulandıktan sonra iki şey denetlenir:

1. Ürün. Anahtarınızda Banka Bağlantıları ürünü (BANK_CONNECT) tanımlı olmalıdır; yoksa 403 PRODUCT_NOT_ENABLED. → Hata Yönetimi › PRODUCT_NOT_ENABLED
2. Yetki. Anahtarınız ucun yetkisini taşımalıdır; yoksa 403 API_INSUFFICIENT_SCOPE.

IP izin listesi

Para hareketi yapan uçlarda (bank-connect:transfer) doğrulama kodu yoktur; onay anahtar yetkisi, istek imzası ve isteğin geldiği IP adresidir. Bu yüzden:

1. Anahtar oluştururken ya da güncellerken: bank-connect:transfer yetkisi yalnız IP izin listesi olan bir anahtara verilebilir. Liste boşken bu yetkiyi eklemeye çalışırsanız işlem 400 organization.api_key.scope_requires_ip_allowlist ile reddedilir.
2. Her istekte: isteğin geldiği IP adresi anahtarın listesinde olmalıdır. Listesi boş anahtar 403 bank_connect.auth.ip_allowlist_required, listede olmayan adres 403 bank_connect.auth.ip_not_allowed alır. Liste geçici olarak doğrulanamazsa istek 503 bank_connect.auth.ip_allowlist_unavailable alır; aynı istekle yeniden deneyin.

Listeye tek tek IP adresleri yazılır (IPv4 ya da IPv6); adres aralıkları (CIDR) kabul edilmez, en çok 50 adres eklenebilir. Listede yaptığınız değişiklik en geç 15 saniye içinde geçerli olur. Okuma uçları (bank-connect:view, bank-connect:transactions:view) bu kurala tabi değildir.

Ortam

Ortamı (test ya da canlı) anahtarınızın ortamı belirler. Test anahtarı yalnız test ortamındaki bağlantıları ve verileri, canlı anahtar yalnız canlı ortamdakileri görür. Sorguda environment gönderilmez; gönderilirse istek 400 VALIDATION_ERROR alır. Başka bir organizasyonun ya da diğer ortamın kaydı 404 döner.

Yanıt zarfı

Başarılı yanıtta veri data altındadır. Tek kayıt dönen uçlarda data kaydın kendisidir. Liste uçlarında kayıtlar data.items içindedir ve sayfalama bilgisi pageInfo, data'nın yanındadır:

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "items": [ ]
  },
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Örneklerde kısalık için gösterilmeyen zarf alanları (message, timestamp …) da yanıtta bulunur; alanların tam listesi ve hata zarfı için: Hata Yönetimi. Hata durumunda message'a göre değil code'a göre dallanın. Bu ürünün kodları: Hata Kodları.

Ortak alan kuralları

Sayfalama

Liste uçları cursor tabanlı sayfalama kullanır:

• pageInfo.hasMore true ise sonraki sayfayı cursor=<nextCursor> ile isteyin.
• Bu uçlarda pageInfo.totalCount her zaman null'dır; includeTotal=true gönderseniz de toplam sayı dönmez. İlerlemek için hasMore yeterlidir.
• İmleci kendiniz üretmeyin ve değiştirmeyin. Bozuk imleç 400 bank_connect.cursor.invalid döner; ilk sayfadan yeniden başlayın.
• Süzgeçleri değiştirdiğinizde imleci sıfırlayın; bir süzgeç kümesinin imleci başka süzgeçlerle kullanılmaz.

Sıradaki adım

• Bağlanabilecek bankalar: Bankalar
• Hesaplarınız ve tazelik: Hesaplar
• Hareketleri okuma ve senkron tutma: Hareketler
• Para gönderme: Para Transferi
• Hesaplarınız arasında döviz alım satımı: Döviz İşlemi