SSS

Veri Gizliliği ve Uyumluluk

Altyapımdan herhangi bir veri çıkıyor mu?

Hayır -- PDF çıkarımı için bile. Bank Statement Parser durum bilgisi olmayan bir kitaplık olarak çalışır. Tüm işlemler -- ayrıştırma, PII redaksiyonu, arşiv çıkarma -- yerel çalışma zamanı belleğinizde gerçekleşir. Hibrit PDF pipeline, yerel LLM çıkarımı için Ollama kullanır -- bulut API'si yok. XML ayrıştırıcıları no_network=True ile güçlendirilmiştir ve ayrıştırıcı düzeyinde tüm giden erişimi engeller. Finansal verileriniz ortamınızdan asla çıkmaz.

PII redaksiyonu nasıl çalışır?

Hassas alanlar uygulama mantığınıza ulaşmadan önce maskelenir. Ayrıştırıcı borçlu adlarını, alacaklı adlarını, IBAN'ları ve posta adreslerini tanır ve bunları konsol çıkışı ile streaming modunda ***REDACTED*** ile değiştirir.

• Redaksiyon varsayılan olarak açıktır -- CLI çıkışında ve streaming modunda.
• Dosya dışa aktarmaları (CSV, JSON, Excel), sonraki işlemler için ham verileri korur.
• Tam veriyi görmek için CLI'de --show-pii veya API'de redact_pii=False kullanın.

Çıkarım süreci deterministik midir?

Yapılandırılmış formatlar için evet -- her çalıştırmada bayt düzeyinde aynı çıktı. Aynı girdi dosyası verildiğinde deterministik ayrıştırıcılar (CAMT, PAIN.001, CSV, OFX, QFX, MT940) her seferinde aynı sonucu üretir. Rastgelelik yok, model çıkarımı yok, buluşsal örnekleme yok.

Hibrit PDF pipeline için LLM tabanlı çıkarım yolları, çalıştırmalar arasında küçük farklılıklar üretebilir. Bu nedenle her PDF çıkarımı Altın Kural (opening + credits − debits == closing) ile doğrulanır ve işaretlenen tutarsızlıklar etkileşimli olarak incelenebilir.

CI, Hypothesis ile özellik tabanlı bulanıklaştırma dahil %100 dal kapsamında 718 testle determinizmi güvence altına alır.

Proje hangi uyumluluk standartlarını takip ediyor?

Proje, ISO 13485 uyumlu belgeleri tam izlenebilirlikle sürdürüyor:

• Şiddet/olasılık puanlaması ve kalan risk değerlendirmesiyle sayısallaştırılmış bir Risk Kaydı.
• 5 aşamada 19 kapılı adımdan oluşan bir Doğrulama ve Geçerleme Planı.
• Etki değerlendirmesi ve geri alma protokollerini içeren bir Değişiklik Kontrol Prosedürü.
• Risk seviyeleri ve EOL takibi ile tüm bağımlılıkları kapsayan bir SOUP Kaydı.
• Tasarım girdilerini uygulama ve doğrulamaya eşleyen bir İzlenebilirlik Matrisi.

Her sürüm CycloneDX SBOM, SHA-256 sağlama toplamları ve GitHub derleme kaynağı doğrulaması içerir.

Performans ve Ölçeklenebilirlik

Bank Statement Parser ne kadar hızlı?

Performans eşikleri her commit'te CI'da doğrulanır:

PDF çıkarım hızı yönlendirme yoluna bağlıdır: deterministik (saniyenin altı), metin-LLM (saniyeler), görüntü-LLM (sayfa başına saniyeler).

Büyük dosyalar nasıl işlenir?

Sınırlı bellekle streaming -- dosya başına 50.000 işlemle test edilmiştir. XML dosyalarını aşamalı olarak işlemek için parse_streaming() kullanın. Her işlem bir sözlük olarak döndürülür; bellek büyümesini önlemek için öğeler işlendikten sonra temizlenir. Bellek dosya boyutuna göre ölçeklenmez -- 50K işlem testi (25+ MB), 10K işlem testinin 2 katından daha az bellek kullanır.

50 MB'ı aşan dosyalar için (örneğin 100K+ ödemeli ana bilgisayardan ana bilgisayara PAIN.001 grupları), ayrıştırıcı parça tabanlı ad alanı temizlemesiyle geçici bir dosya üzerinden streaming yapar -- belgenin tamamı hiçbir zaman belleğe yüklenmez.

ZIP arşivleri nasıl güvenli şekilde işlenir?

iter_secure_xml_entries() çıkarmadan önce her üyeyi doğrular:

• Giriş boyutu üst sınırı (giriş başına varsayılan 10 MB)
• Toplam sıkıştırılmamış boyut üst sınırı (varsayılan 50 MB)
• ZIP bombalarını önlemek için sıkıştırma oranı sınırı (varsayılan 100:1)
• Şifreli giriş reddi

Diske hiçbir dosya yazılmaz. XML baytları from_bytes() ile doğrudan ayrıştırıcıya aktarılır.

Birden fazla dosyayı paralel olarak ayrıştırabilir miyim?

Evet. İşi ProcessPoolExecutor üzerinden dağıtan parse_files_parallel() kullanın:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

Toplu PDF alımı için, klasör ağaçlarını otomatik tekilleştirmeyle işleyen scan_and_ingest() kullanın.

Desteklenen Formatlar

Hangi banka ekstresi formatları destekleniyor?

Format	Standart	Dosya Türleri	Ayrıştırıcı/Yöntem
CAMT.053	ISO 20022 Bankadan Müşteriye Ekstre	.xml	CamtParser
PAIN.001	ISO 20022 Kredi Transferi Başlatma	.xml	Pain001Parser
CSV	Genel banka dışa aktarımları	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	SWIFT standardı	.mt940, .sta	Mt940Parser
PDF	Dijital ve taranmış ekstreler	.pdf	smart_ingest()

Hibrit PDF pipeline nasıl çalışır?

Hibrit pipeline (v0.0.5+) PDF'leri akıllıca üç çıkarım yolundan geçirir:

• Yol A (Deterministik): Yapılandırılmış PDF tabloları doğrudan ayrıştırılır -- ücretsiz, en hızlı, LLM gerektirmez.
• Yol B (Metin-LLM): Karmaşık düzene sahip dijital PDF'ler yerel LLM (LiteLLM/Ollama) ile çıkarılır.
• Yol C (Görüntü-LLM): Taranan veya fotokopi edilmiş ekstreler çok modlu görüntü modelleriyle işlenir.

Her çıkarım Altın Kural (opening + credits − debits == closing) ile doğrulanır. Tutarsızlıklar --type review ile etkileşimli olarak incelenebilir.

Ayrıştırıcı CAMT.053'ün bankaya özgü lehçelerini işliyor mu?

Evet -- tasarım gereği ad alanından bağımsız. Ayrıştırıcı, XML ad alanlarını işlemeden önce çıkarır ve herhangi bir CAMT.053 varyantını (camt.053.001.02, camt.053.001.04 veya özel banka sarmalayıcıları) ad alanına özgü yapılandırma olmadan işler. XPath sorguları ad alanı URI'lerini değil, öğe yapısını hedefler.

CAMT'yi özel bir zarfa saran bankalar için iç belgeyi doğrudan beslemek üzere from_string() veya from_bytes() kullanın.

Özel CSV sütun başlıklarını standart şemayla eşleyebilir miyim?

Evet -- otomatik normalleştirme, sıfır yapılandırma. CsvStatementParser yaygın başlık varyasyonlarını tanır: "Date", "Transaction Date", "Booking Date" hepsi date alanına eşlenir. "Amount", "Value", "Sum" ise amount alanına eşlenir. Ayrı alacak/borç sütunları (ör. "Credit" ve "Debit") otomatik algılanır ve tek bir işaretli tutarda birleştirilir.

Çıktı formatı nedir?

Tüm ayrıştırıcılar tutarlı sütun türlerine sahip standartlaştırılmış pandas DataFrames üretir:

Format	Anahtar Sütunlar
CAMT	Amount, Currency, DrCr, Debtor, Creditor, Reference, ValDt, BookgDt, AccountId
PAIN.001	PmtInfId, PmtMtd, InstdAmt, Currency, CdtrNm, EndToEndId, MsgId, CreDtTm, NbOfTxs
CSV/OFX/QFX/MT940	date, description, amount (normalleştirilmiş)

Ayrıca CSV, JSON, Excel, Polars DataFrames, hledger veya beancount defter formatına da aktarabilirsiniz.

PDF ve LLM Özellikleri

Hibrit pipeline hangi LLM modellerini destekliyor?

Pipeline, model soyutlama katmanı olarak LiteLLM ve görüntü istemleri için doğrudan Ollama köprüsü kullanır. Önerilen modeller:

• Metin çıkarımı: LiteLLM uyumlu herhangi bir model (yerel veya uzak).
• Görüntü çıkarımı: Taranmış PDF'ler için ollama/minicpm-v (önerilir).
• Sınıflandırma: LiteLLM uyumlu herhangi bir model.

Tüm modeller Ollama ile %100 yerel çalışabilir -- API anahtarı gerekmez.

Altın Kural doğrulaması nedir?

Her PDF çıkarımı şu denklemle doğrulanır: opening balance + credits − debits == closing balance. Sonuçlar şöyle etiketlenir:

• VERIFIED: Bakiyeler tam olarak eşleşir.
• DISCREPANCY: Bakiyeler eşleşmez -- inceleme önerilir.
• FAILED: Doğrulama yapılamadı (bakiye verisi eksik).

İşlemleri otomatik sınıflandırabilir miyim?

Evet. Zenginleştirme modülü (v0.0.6+) LLM destekli işlem sınıflandırması sağlar:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)

Varsayılan şema 13 Plaid uyumlu kategori kullanır. Kendi kategori şemanızı da sağlayabilirsiniz.

hledger veya beancount'a aktarabilir miyim?

Evet (v0.0.8+). İşlemleri hesap eşlemesi ile düz metin muhasebe defter formatlarına aktarın:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")

Hazine İş Akışları

Ayrıştırıcı çoklu para birimli ekstreleri nasıl işler?

Her işlem orijinal para birimini korur -- örtülü dönüştürme yapılmaz. Currency alanı işlem başına XML Ccy özelliğinden çıkarılır. Çoklu para birimi ekstreleri olduğu gibi kalır. get_account_balances() yöntemi, orijinal para birimi kodlarıyla hesap başına açılış ve kapanış bakiyelerini döndürür.

v0.0.8'den itibaren verify_balance_multi_currency() işlemleri para birimine göre gruplar ve Altın Kuralı her grup için bağımsız çalıştırır -- birden fazla para birimi tutan hesaplar için kullanışlıdır.

Ayrıştırıcı hem giden hem de gelen formatları destekliyor mu?

Evet. Pain001Parser ISO 20022 PAIN.001 kredi transferi başlatma dosyalarını (giden ödemeler) yönetir. CamtParser CAMT.053 bankadan müşteriye ekstre dosyalarını (gelen raporlama) yönetir. Her ikisi de streaming, PII redaksiyonu ve CSV, JSON, Excel, hledger ve beancount formatlarına dışa aktarımı destekler. Formatı otomatik tanımak için detect_statement_format() kullanın.

Bir işlem girişi hatalı biçimlendirildiğinde ne olur?

Davranış ayrıştırma moduna bağlıdır:

• parse() (toplu mod) -- Gerekli alanları (Amount, Currency veya CdtDbtInd) eksik olan hatalı girişler uyarı günlüğüyle atlanır. Ekstrenin geri kalanı normal şekilde ayrıştırılır.
• parse_streaming() (streaming modu) -- Ayrıştırma hataları istisnalar olarak hemen yayılır. Sessiz veri kaybı yok. Bu hızlı başarısızlık davranışı, her işlemin hesaba katılması gereken finansal iş akışları için tasarlanmıştır.
• smart_ingest() (hibrit PDF) -- Çıkarım hataları doğrulama durumuyla birlikte IngestResult içinde yakalanır ve etkileşimli incelemeye olanak tanır.

Tekilleştirme nasıl çalışır?

Her işleme, anahtar alanlarına dayalı idempotent bir transaction_hash (MD5 parmak izi) atanır. Bu, güvenli artımlı veri alımı sağlar -- aynı dosyanın yeniden işlenmesi aynı hash'leri üretir, böylece kopyalar otomatik algılanır.

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

Kurulum ve Uyumluluk

Bank Statement Parser'ı nasıl kurarım?

# Temel kurulum (yalnızca deterministik ayrıştırıcılar)
pip install bankstatementparser

# PDF hibrit pipeline
pip install 'bankstatementparser[hybrid]'         # Metin-LLM yolu
pip install 'bankstatementparser[hybrid-vision]'   # Görüntü-LLM yolu

# Eklentiler
pip install 'bankstatementparser[enrichment]'      # İşlem sınıflandırması
pip install 'bankstatementparser[api]'             # REST API mikro hizmeti
pip install 'bankstatementparser[polars]'          # Polars DataFrame desteği

Hangi Python sürümleri destekleniyor?

Python 3.10 - 3.14. Python 3.9 desteği v0.0.6'da kaldırıldı (EOL 2025-10-31). Tüm sürümler CI'da %100 dal kapsamında 718 testle test edilmiştir.

Bağımlılıklar nelerdir?

Temel kitaplığın 5 doğrudan bağımlılığı vardır:

• lxml -- Güvenlik güçlendirmesi ile XML ayrıştırma
• pandas -- DataFrames ve veri manipülasyonu
• openpyxl -- Excel dışa aktarımı
• pydantic -- Veri doğrulama ve modeller
• defusedxml -- XXE koruması

İsteğe bağlı eklentiler ekler: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

Tüm bağımlılıkların SHA-256 hash kilitli sürümleri vardır. CycloneDX SBOM her çalışma zamanı bileşenini eşler.

macOS, Linux ve Windows'ta çalışıyor mu?

Evet. Kitaplık macOS, Linux ve Windows'ta (WSL aracılığıyla) çalışır. Platforma özgü bağımlılığı yoktur.

REST API var mı?

Evet (v0.0.8+). pip install 'bankstatementparser[api]' ile kurun ve çalıştırın:

bankstatementparser-api --port 8000

Uç noktalar: POST /ingest (bir ekstreyi ayrıştır) ve GET /health (sağlık kontrolü).

Tekrarlanabilirlik ve Güvenlik

Tekrarlanabilirliği nasıl doğrulayabilirim?

python -m pytest                              # 718 tests, 100% branch coverage
python scripts/verify_locked_hashes.py        # SHA-256 hash verification
git log --show-signature -1                   # Verify commit signature

Hangi güvenlik korumaları yerleşiktir?

• XXE Koruması: resolve_entities=False, no_network=True, load_dtd=False
• ZIP Bomba Koruması: Sıkıştırma oranı sınırları, giriş boyutu üst sınırları, şifreli giriş reddi
• Yol Geçişi Önleme: Tehlikeli desen engelleme listesi ve sembolik bağlantı çözümlemesi
• Girdi Doğrulama: Dosya boyutu sınırları (varsayılan 100 MB), uzantı/format doğrulaması
• Tedarik Zinciri: SHA-256 hash kilitli bağımlılıklar, CycloneDX SBOM, derleme kaynağı doğrulaması
• İmzalı Commit'ler: CI'da zorunlu
• Yerel LLM'ler: Hibrit PDF pipeline Ollama kullanır -- bulut API çağrısı yok

Bank Statement Parser pyiso20022 ile nasıl karşılaştırılır?

pyiso20022, ISO XML şemalarından Python veri sınıfları üreten geniş bir ISO 20022 araç setidir. Şema doğrulamayla birlikte çok çeşitli ISO 20022 mesaj türlerini (PACS, PAIN, CAMT, ADMI) kapsar. Bank Statement Parser ise hibrit PDF desteği, bakiye doğrulama, zenginleştirme, defter dışa aktarımı ve ISO dışı formatlar (CSV, OFX, QFX, MT940, PDF) dahil yedi format genelinde birleşik API ile banka ekstresi ayrıştırma için özel olarak tasarlanmıştır. Banka ekstrelerini üretim düzeyinde güvenlikle DataFrames'e ayrıştırmanız gerekiyorsa Bank Statement Parser'ı kullanın. ISO 20022 mesaj kataloğunun tamamıyla çalışmanız gerekiyorsa pyiso20022'yi kullanın.

SWIFT ISO 20022 geçiş son tarihleri nelerdir?

SWIFT aşamalı bir geçiş zaman çizelgesi yayınladı:

• Kasım 2026: Yapılandırılmış ve karma adresler zorunlu hale gelir. MT101 çoklu talimat mesajları reddedilecektir. Vaka Yönetimi Aşama 1 başlar.
• Kasım 2027: Tüm finans kuruluşlarının CAMT.053 ekstrelerini doğrudan alabilmesi gerekir. SWIFT, MT'den ISO formatına dönüştürmeyi durduracaktır.
• Kasım 2028: MT940, MT942, MT950, MT900 ve MT910'un tamamen kullanımdan kaldırılması. Bunların yerini CAMT.052, CAMT.053 ve CAMT.054 eşdeğerleri alacaktır.

Bank Statement Parser hem eski MT940 formatını hem de modern CAMT.053/PAIN.001 formatlarını destekler; bu da onu geçiş dönemi için ideal kılar.