FAQ

은행 명세서 파서에 대한 일반적인 질문

데이터 프라이버시 및 컴플라이언스

내 인프라에서 데이터가 유출되나요?

아니요 — PDF 추출도 마찬가지입니다. Bank Statement Parser는 상태 비저장 라이브러리로 작동합니다. 파싱, PII 마스킹, 아카이브 추출 등 모든 처리는 로컬 런타임 메모리 내에서 이루어집니다. 하이브리드 PDF 파이프라인은 로컬 LLM 추론을 위해 Ollama를 사용하며 클라우드 API를 호출하지 않습니다. XML 파서는 no_network=True로 강화되어 파서 수준에서 모든 아웃바운드 접근을 차단합니다. 금융 데이터는 절대 외부 환경으로 유출되지 않습니다.

PII 마스킹은 어떻게 작동하나요?

민감한 필드는 애플리케이션 로직에 도달하기 전에 마스킹됩니다. 파서는 채무자 이름, 채권자 이름, IBAN, 우편 주소를 식별하여 콘솔 출력 및 스트리밍 모드에서 ***REDACTED***로 대체합니다.

  • CLI 출력 및 스트리밍 모드에서는 마스킹이 기본 활성화됩니다.
  • 파일 내보내기(CSV, JSON, Excel)는 다운스트림 처리를 위해 마스킹되지 않은 데이터를 유지합니다.
  • CLI에서 --show-pii 또는 API에서 redact_pii=False로 전체 데이터를 선택적으로 표시할 수 있습니다.

추출 프로세스가 결정적인가요?

구조화된 형식의 경우 예 — 매번 바이트 단위로 동일한 출력을 생성합니다. 동일한 입력 파일이 주어지면 결정적 파서(CAMT, PAIN.001, CSV, OFX, QFX, MT940)는 매번 동일한 결과를 생성합니다. 무작위성, 모델 추론, 경험적 샘플링이 없습니다.

하이브리드 PDF 파이프라인의 경우 LLM 기반 추출 경로는 실행 간 미세한 변동이 있을 수 있습니다. 이것이 모든 PDF 추출이 Golden Rule(opening + credits − debits == closing)로 검증되고 플래그된 불일치를 대화형으로 검토할 수 있는 이유입니다.

CI는 Hypothesis를 통한 속성 기반 퍼징을 포함하여 100% 브랜치 커버리지에서 718개 테스트로 결정성을 보장합니다.

프로젝트는 어떤 컴플라이언스 표준을 따르나요?

이 프로젝트는 완전한 추적성을 갖춘 ISO 13485 기반 문서를 유지합니다.

  • 심각도/확률 점수 및 잔여 위험 평가가 포함된 정량화된 위험 등록부.
  • 5단계에 걸쳐 19개 게이트 단계로 구성된 검증 및 유효성 검사 계획.
  • 영향 평가 및 롤백 프로토콜이 포함된 변경 관리 절차.
  • 위험 수준 및 EOL 추적과 함께 모든 종속성을 다루는 SOUP 레지스터.
  • 설계 입력을 구현 및 검증에 매핑하는 추적성 매트릭스.

모든 릴리스에는 CycloneDX SBOM, SHA-256 체크섬, GitHub 빌드 출처 증명이 포함됩니다.

성능 및 확장성

Bank Statement Parser는 얼마나 빠른가요?

성능 임계값은 모든 커밋마다 CI에서 검증됩니다.

지표 값
CAMT.053 처리량 초당 27,000+ 트랜잭션
PAIN.001 처리량 초당 52,000+ 트랜잭션
트랜잭션당 지연 시간 (CAMT) 37 마이크로초
트랜잭션당 지연 시간 (PAIN.001) 19 마이크로초
첫 번째 결과 반환 시간 < 2 ms

PDF 추출 속도는 라우팅 경로에 따라 다릅니다: 결정적(1초 미만), 텍스트-LLM(수 초), 비전-LLM(페이지당 수 초).

대용량 파일은 어떻게 처리되나요?

제한된 메모리를 사용한 스트리밍 — 파일당 50,000건의 트랜잭션으로 테스트되었습니다. parse_streaming()을 사용하여 XML 파일을 증분적으로 처리합니다. 각 트랜잭션은 딕셔너리로 생성되며, 메모리 증가를 방지하기 위해 처리 후 요소가 지워집니다. 메모리는 파일 크기에 비례하지 않습니다 — 50K 트랜잭션 테스트(25MB 이상)가 10K 트랜잭션 테스트의 2배 미만의 메모리를 사용합니다.

50MB를 초과하는 파일(예: 100K+ 결제가 포함된 호스트 간 PAIN.001 배치)의 경우 파서는 청크 기반 네임스페이스 제거를 사용하여 임시 파일을 통해 스트리밍합니다 — 전체 문서가 메모리에 로드되지 않습니다.

ZIP 아카이브는 어떻게 안전하게 처리되나요?

iter_secure_xml_entries()가 추출 전에 각 멤버의 유효성을 검사합니다.

  • 항목 크기 한도 (항목당 기본 10MB)
  • 압축 해제 후 총 크기 한도 (기본값 50MB)
  • ZIP 폭탄을 방지하기 위한 압축 비율 제한 (기본값 100:1)
  • 암호화된 항목 거부

디스크에 파일이 기록되지 않습니다. XML 바이트는 from_bytes()를 통해 파서에 직접 전달됩니다.

여러 파일을 병렬로 파싱할 수 있나요?

예. parse_files_parallel()을 사용하여 작업을 ProcessPoolExecutor에 분산합니다.

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")

대량 PDF 수집에는 자동 중복 제거와 함께 전체 폴더 트리를 처리하는 scan_and_ingest()를 사용합니다.

지원 형식

어떤 은행 명세서 형식이 지원되나요?

형식 표준 파일 유형 파서/메서드
CAMT.053 ISO 20022 은행-고객 명세서 .xml CamtParser
PAIN.001 ISO 20022 자금이체 개시 .xml Pain001Parser
CSV 일반 은행 내보내기 .csv CsvStatementParser
OFX Open Financial Exchange .ofx OfxParser
QFX Quicken Financial Exchange .qfx QfxParser
MT940 SWIFT 표준 .mt940, .sta Mt940Parser
PDF 디지털 및 스캔 명세서 .pdf smart_ingest()

하이브리드 PDF 파이프라인은 어떻게 작동하나요?

하이브리드 파이프라인(v0.0.5+)은 PDF를 3가지 추출 경로로 지능적으로 라우팅합니다.

  • 경로 A (결정적): 구조화된 PDF 테이블을 직접 파싱합니다. 무료이며 가장 빠르고 LLM이 필요하지 않습니다.
  • 경로 B (텍스트-LLM): 복잡한 레이아웃의 디지털 PDF를 로컬 LLM(LiteLLM/Ollama)으로 추출합니다.
  • 경로 C (비전-LLM): 스캔 또는 복사된 명세서를 멀티모달 비전 모델로 처리합니다.

모든 추출 결과는 Golden Rule(opening + credits − debits == closing)로 검증됩니다. 불일치는 --type review로 대화형 검토가 가능합니다.

파서가 CAMT.053의 은행별 변형을 처리하나요?

예 — 네임스페이스에 구애받지 않도록 설계되었습니다. 파서는 처리 전에 XML 네임스페이스를 제거하여 모든 CAMT.053 변형(camt.053.001.02, camt.053.001.04 또는 독점 은행 래퍼)을 네임스페이스별 설정 없이 처리합니다. XPath 쿼리는 네임스페이스 URI가 아닌 요소 구조를 대상으로 합니다.

CAMT를 커스텀 봉투에 감싸는 은행의 경우 from_string() 또는 from_bytes()를 사용하여 내부 문서를 직접 전달합니다.

커스텀 CSV 열 헤더를 표준 스키마에 매핑할 수 있나요?

예 — 자동 정규화, 설정 불필요. CsvStatementParser는 일반적인 헤더 변형을 인식합니다. "Date", "Transaction Date", "Booking Date"는 모두 date 필드에 매핑됩니다. "Amount", "Value", "Sum"은 amount에 매핑됩니다. 분리된 대변/차변 열(예: "Credit", "Debit")은 자동으로 감지되어 하나의 부호가 있는 금액으로 결합됩니다.

출력 형식은 무엇인가요?

모든 파서는 일관된 열 유형을 가진 표준화된 pandas DataFrame을 생성합니다.

형식 주요 열
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 (정규화)

CSV, JSON, Excel, Polars DataFrame, hledger 또는 beancount 저널 형식으로도 내보낼 수 있습니다.

PDF 및 LLM 기능

하이브리드 파이프라인은 어떤 LLM 모델을 지원하나요?

파이프라인은 모델 추상화 레이어로 LiteLLM을 사용하며, 비전 프롬프트에는 직접 Ollama 브리지를 사용합니다. 권장 모델:

  • 텍스트 추출: 모든 LiteLLM 호환 모델 (로컬 또는 원격).
  • 비전 추출: ollama/minicpm-v (스캔 PDF에 권장).
  • 분류: 모든 LiteLLM 호환 모델.

모든 모델은 Ollama를 통해 100% 로컬 실행이 가능하며 API 키가 필요하지 않습니다.

Golden Rule 검증이란 무엇인가요?

모든 PDF 추출은 다음 수식으로 검증됩니다: opening balance + credits − debits == closing balance. 결과는 다음과 같이 태그됩니다:

  • VERIFIED: 잔액이 정확히 일치합니다.
  • DISCREPANCY: 잔액이 불일치합니다 — 검토를 권장합니다.
  • FAILED: 검증을 수행할 수 없습니다 (잔액 데이터 누락).

트랜잭션을 자동으로 분류할 수 있나요?

예. 보강 모듈(v0.0.6+)은 LLM 기반 트랜잭션 분류를 제공합니다.

from bankstatementparser.enrichment import Categorizer

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

기본 스키마는 Plaid 호환 13개 카테고리를 사용합니다. 자체 카테고리 스키마를 제공할 수도 있습니다.

hledger 또는 beancount로 내보낼 수 있나요?

예 (v0.0.8+). 계정 매핑과 함께 트랜잭션을 일반 텍스트 회계 저널 형식으로 내보냅니다.

from bankstatementparser.export import to_hledger, to_beancount

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

재무 워크플로

파서는 다중 통화 명세서를 어떻게 처리하나요?

각 트랜잭션은 원래 통화를 유지하며 암시적 변환은 없습니다. Currency 필드는 트랜잭션별 XML Ccy 속성에서 추출됩니다. 다중 통화 명세서는 그대로 유지됩니다. get_account_balances() 메서드는 원래 통화 코드를 사용하여 계정별 시작 및 마감 잔액을 반환합니다.

v0.0.8부터 verify_balance_multi_currency()는 통화별로 트랜잭션을 그룹화하고 그룹별로 Golden Rule을 독립적으로 실행합니다 — 여러 통화를 보유하는 계정에 유용합니다.

파서가 송신 및 수신 형식을 모두 지원하나요?

예. Pain001Parser는 ISO 20022 PAIN.001 자금이체 개시 파일(송신 결제)을 처리합니다. CamtParser는 CAMT.053 은행-고객 명세서 파일(수신 보고)을 처리합니다. 둘 다 스트리밍, PII 마스킹, CSV/JSON/Excel/hledger/beancount 내보내기를 지원합니다. detect_statement_format()을 사용하여 형식을 자동으로 식별합니다.

트랜잭션 항목의 형식이 잘못되면 어떻게 되나요?

동작은 파싱 모드에 따라 다릅니다.

  • parse() (배치 모드) -- 필수 필드(Amount, Currency 또는 CdtDbtInd)가 누락된 형식 오류 항목은 경고 로그와 함께 건너뜁니다. 나머지 명세서는 정상적으로 파싱됩니다.
  • parse_streaming() (스트리밍 모드) -- 파싱 오류는 즉시 예외로 전파됩니다. 무음 데이터 손실이 없습니다. 이 빠른 실패 동작은 모든 트랜잭션을 반드시 처리해야 하는 금융 워크플로를 위한 것입니다.
  • smart_ingest() (하이브리드 PDF) -- 추출 오류는 검증 상태와 함께 IngestResult에 캡처되어 대화형 검토가 가능합니다.

중복 제거는 어떻게 작동하나요?

각 트랜잭션에는 핵심 필드를 기반으로 멱등성 transaction_hash(MD5 핑거프린트)가 할당됩니다. 이를 통해 안전한 증분 수집이 가능합니다 — 동일한 파일을 재처리하면 동일한 해시가 생성되므로 중복이 자동으로 감지됩니다.

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)}")

설치 및 호환성

Bank Statement Parser는 어떻게 설치하나요?

# 코어 설치 (결정적 파서만)
pip install bankstatementparser

# PDF 하이브리드 파이프라인
pip install 'bankstatementparser[hybrid]'         # 텍스트-LLM 경로
pip install 'bankstatementparser[hybrid-vision]'   # 비전-LLM 경로

# Extras
pip install 'bankstatementparser[enrichment]'      # 트랜잭션 분류
pip install 'bankstatementparser[api]'             # REST API 마이크로서비스
pip install 'bankstatementparser[polars]'          # Polars DataFrame 지원

어떤 Python 버전이 지원되나요?

Python 3.10~3.14. Python 3.9 지원은 v0.0.6에서 제거되었습니다(EOL 2025-10-31). 모든 버전은 CI에서 100% 브랜치 커버리지의 718개 테스트로 검증됩니다.

종속성은 무엇인가요?

코어 라이브러리에는 5개의 직접 종속성이 있습니다.

  • lxml -- 보안 강화가 적용된 XML 파싱
  • pandas -- DataFrame 및 데이터 조작
  • openpyxl -- Excel 내보내기
  • pydantic -- 데이터 유효성 검사 및 모델
  • defusedxml -- XXE 보호

선택적 extras: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

모든 종속성에는 SHA-256 해시 잠금 버전이 있습니다. CycloneDX SBOM이 모든 런타임 구성 요소를 매핑합니다.

macOS, Linux, Windows에서 작동하나요?

예. 라이브러리는 macOS, Linux, Windows(WSL 경유)에서 작동합니다. 플랫폼별 종속성이 없습니다.

REST API가 있나요?

예 (v0.0.8+). pip install 'bankstatementparser[api]'로 설치 후 실행합니다.

bankstatementparser-api --port 8000

엔드포인트: POST /ingest (명세서 파싱) 및 GET /health (헬스 체크).

재현성과 보안

재현성을 어떻게 확인할 수 있나요?

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

어떤 보안 보호 기능이 내장되어 있나요?

  • XXE 보호: resolve_entities=False, no_network=True, load_dtd=False
  • ZIP 폭탄 보호: 압축 비율 제한, 항목 크기 한도, 암호화된 항목 거부
  • 경로 탐색 방지: 위험한 패턴 차단 목록 및 심볼릭 링크 해석
  • 입력 유효성 검사: 파일 크기 제한(기본값 100MB), 확장자/형식 유효성 검사
  • 공급망: SHA-256 해시 잠금 종속성, CycloneDX SBOM, 빌드 출처 증명
  • 서명된 커밋: CI에서 시행됩니다
  • 로컬 LLM: 하이브리드 PDF 파이프라인은 Ollama를 사용 — 클라우드 API 호출 없음

Bank Statement Parser는 pyiso20022와 어떻게 비교되나요?

pyiso20022는 ISO XML 스키마에서 Python 데이터 클래스를 생성하는 광범위한 ISO 20022 툴킷입니다. 스키마 유효성 검사를 통해 광범위한 ISO 20022 메시지 유형(PACS, PAIN, CAMT, ADMI)을 다룹니다. Bank Statement Parser는 하이브리드 PDF 지원, 잔액 검증, 보강, 원장 내보내기, 비ISO 형식(CSV, OFX, QFX, MT940, PDF)을 포함한 7가지 형식의 통합 API를 갖춘 은행 명세서 파싱 전용으로 제작되었습니다. 프로덕션급 보안으로 은행 명세서를 DataFrame으로 파싱해야 하는 경우 Bank Statement Parser를 사용하세요. 전체 ISO 20022 메시지 카탈로그로 작업해야 하는 경우 pyiso20022를 사용하세요.

SWIFT ISO 20022 마이그레이션 마감일은 언제인가요?

SWIFT는 단계별 마이그레이션 타임라인을 발표했습니다.

  • 2026년 11월: 구조화된 주소와 하이브리드 주소가 필수가 됩니다. MT101 다중 명령 메시지는 거부됩니다. 사례 관리 1단계가 시작됩니다.
  • 2027년 11월: 모든 금융 기관은 CAMT.053 명세서를 기본적으로 수신할 수 있어야 합니다. SWIFT는 MT에서 ISO 형식으로의 변환을 중단합니다.
  • 2028년 11월: MT940, MT942, MT950, MT900, MT910이 완전히 중단됩니다. CAMT.052, CAMT.053, CAMT.054 등가물로 대체됩니다.

Bank Statement Parser는 레거시 MT940 형식과 최신 CAMT.053/PAIN.001 형식을 모두 지원하므로 전환 기간에 이상적입니다.