ravan/ziraat-bank

Ziraat Bankası HEK_NKYWS (Hesap Hareketleri) SOAP API Wrapper for PHP 8+

dev-main 2026-07-22 20:29 UTC

Requires

• php: ^8.0
• ext-json: *
• ext-soap: *
• nesbot/carbon: ^2.0|^3.0
• psr/log: ^1.0|^2.0|^3.0
• psr/simple-cache: ^1.0|^2.0|^3.0

Requires (Dev)

• mockery/mockery: ^1.5
• phpunit/phpunit: ^9.5|^10.0

MIT

• Ravan Babayev

• api
• soap
• laravel
• Bank
• banka
• ziraat
• hek
• nkyws
• hesap
• ekstre

Published on Packagist.org on 2026-07-22 20:31 UTC

README

[TR] T.C. Ziraat Bankası HEK_NKYWS (Hesap Hareketleri) SOAP entegrasyonu için geliştirilmiş framework bağımsız, PHP 8.0+ destekleyen modern kütüphane.

[EN] Modern framework-agnostic PHP 8.0+ library for T.C. Ziraat Bank HEK_NKYWS (Account Transactions) SOAP integration.

Özellikler / Features

• PHP 8.0+ & PSR Standartları ile tam uyum.
• Framework Bağımsız (Agnostic): Herhangi bir PHP projesinde veya doğrudan Laravel ile kullanılabilir.
• 19 Metot Desteği: WSDL'de bulunan tüm SOAP metotlarını (sorgulamalar, PDF dekont, mutabakat) içerir.
• Casing Tutarlılığı: WSDL alan adlarındaki tutarsız casing yapısı korunarak hata yapma payı sıfıra indirilmiştir.
• Laravel Desteği: Auto-discovery, Config dosyası ve Facade desteği ile Laravel projelerinde anında entegrasyon.
• PSR-3 Logger & PSR-16 Cache desteği.

Kurulum / Installation

Composer aracılığı ile paketi projenize dahil edin:

composer require ravan/ziraat-bank

Not: SOAP servislerini kullanabilmek için PHP ext-soap eklentisinin aktif olması gerekmektedir.

Kullanım / Usage

1. Sade PHP (Framework Bağımsız) / Standalone PHP

use Ravan\ZiraatBank\ZiraatBankService;

$service = new ZiraatBankService(
    kurumKod: 'kullanıcı-adınız',
    sifre: 'şifreniz',
    wsdl: 'https://hesap.ziraatbank.com.tr/HEK_NKYWS/HesapHareketleri.asmx?WSDL', // Opsiyonel varsayılan
    tcknVkn: '1234567890' // Opsiyonel
);

// Örnek: IBAN ile hesap özeti sorgulama
$response = $service->sorgulaOzetWS(
    ibanNo: 'TR...',
    baslangicTarihi: '20.07.2026',
    bitisTarihi: '22.07.2026'
);

print_r($response);

2. Laravel Entegrasyonu / Laravel Integration

Paket, Laravel auto-discovery'yi destekler. Service provider ve Facade otomatik olarak yüklenir.

Yapılandırma Yayınlama / Publish Config

Ayarlar dosyasını (config/ziraatbank.php) oluşturmak için:

php artisan vendor:publish --provider="Ravan\ZiraatBank\Laravel\ZiraatBankServiceProvider" --tag="ziraatbank-config"

.env Tanımlamaları / .env Configuration

Aşağıdaki değişkenleri .env dosyanıza ekleyin:

ZIRAAT_HEK_USERNAME="kullanici_adiniz"
ZIRAAT_HEK_PASSWORD="sifreniz_buraya"
ZIRAAT_HEK_TCKNVKN="tckn_veya_vkn_numaraniz"
# Opsiyonel:
ZIRAAT_HEK_WSDL="https://hesap.ziraatbank.com.tr/HEK_NKYWS/HesapHareketleri.asmx?WSDL"

Laravel Facade Kullanımı / Facade Usage

use Ravan\ZiraatBank\Laravel\Facades\ZiraatBank;

// Müşteri ve ek no ile hesap hareketleri
$sonuc = ZiraatBank::sorgulaHesapHareket(
    musteriNo: 123456,
    ekNo: 0,
    baslangicTr: '20.07.2026',
    bitisTr: '22.07.2026'
);

Metotlar / Available Methods

Aşağıda kütüphane içerisinde hazır bulunan 19 SOAP metodu ve ek yardımcı metotlar listelenmiştir.

SOAP Servis Metotları

• musteriHesapHareket(...)
• hesapEkstre(...)
• hesapEkstreZamanIle(...)
• sorgulaDetayWS(...)
• sorgulaDetayWSZamanIle(...)
• sorgulaOzetWS(...)
• sorgulaOzetWSZamanIle(...)
• hareketSorgulaVknIle(...)
• getirPdfDekont(...)
• getirPdfDekontZamanIle(...)
• getirPdfDekontDekontNoIle(...)
• sorgulaHesapHareket(...)
• sorgulaHesapHareketZamanIle(...)
• sorgulaHesapHareketZamanIleHizli(...)
• getirTanimliHesapBilgileri(...)
• sorgulaGelenParaTransfer(...)
• sorgulaMutabakatOzetZamanIle(...)
• sorgulaMutabakatDetayZamanIle(...)
• sorgulaMahsupDetayZamanIle(...)

Birleşik ve Yardımcı Metotlar / Helper Methods

• ping(): WSDL endpoint'e erişilebilirliği test eder (bool).
• getBankAccounts(): TCKN/VKN'ye bağlı tüm aktif banka hesaplarını normalize edilmiş formatta listeler (Önbellekleme desteklidir).
• getAccountTransactions($accountId, $startDate, $endDate): Belirli bir hesaba ait hareketleri çeker ve entegrasyon zamanına göre filtreler.
• getHesaplarVeHareketleri($tcknVkn, $baslangicTr, $bitisTr): Tüm hesapları çeker ve her birinin hareketlerini birleştirerek tek bir dizi halinde döner.
• getLastExchange(): Son gönderilen/alınan XML istek ve yanıtlarını hata ayıklama (debug) için döner.

Hata Ayıklama (Debug) / Logging & Caching

Kütüphane PSR-3 uyumlu logger ve PSR-16 uyumlu cache arabirimlerini destekler. Laravel üzerinde kullanıldığında uygulamanızın varsayılan Log ve Cache sistemleri otomatik olarak kütüphaneye enjekte edilir.

Sade PHP kullanımında ise bağımlılıklarınızı manuel olarak enjekte edebilirsiniz:

$service->setLogger($myPsr3Logger);
$service->setCache($myPsr16Cache);

Lisans / License

Bu paket MIT Lisansı altında dağıtılmaktadır.