bea import를 사용하여 은행 수출 내역을 미리 보고, 중복 항목을 검토하며, 검증된 항목을 로컬 원장에 추가할 수 있습니다.
기존 원장과 은행의 정확한 내보내기 형식에 맞는 Python 임포터가 필요합니다. 새 장부를 시작하는 경우 CLI 빠른 시작을 따르세요. 미리보기와 비교할 수 있도록 원본 은행 수출 파일을 보관하세요.
1. 임포터 선택
임포터는 은행의 파일을 읽고 거래 계정을 제공합니다. Bea는 형식을 추측하거나 AI 모델로 구매 내역을 분류하지 않습니다.
importers.py 구성은 CONFIG = [importer, ...]를 내보냅니다. 임포터는 현재 Beangulp 인터페이스(identify(filepath), account(filepath), extract(filepath, existing))를 사용합니다. 소스 계정 분개에는 중복 일치를 위해 명시적인 금액이 필요합니다.
첫 연습 실행을 위해 예제 분류 CSV 구성을 루트 원장 옆에 importers.py로 저장하세요. Beancount와 Python 표준 라이브러리만 사용하므로 Homebrew 설치에서도 작동합니다.
이 샘플을 같은 디렉토리에 bank.csv로 저장하세요:
Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002샘플은 부호 있는 당좌예금 계정 금액을 사용합니다: 지출은 음수, 입금은 양수입니다. Category가 다른 계정을 제공합니다. 두 범주 모두 bea init이 만든 USD 템플릿에 있습니다.
네이티브 CSV, OFX 또는 QIF를 가져올 때는 은행용으로 작성된 임포터를 사용하세요. 샘플 구성은 정확히 위의 열을 기대합니다. 신뢰하는 Python 구성만 실행하세요.
2. 항목 미리 보기
main.bean이 포함된 디렉토리에서 실행:
bea import bank.csv --config importers.py아직 원장에는 아무것도 기록되지 않습니다. 미리보기의 날짜, 수취인, 부호 있는 소스 금액, 대상 계정, 중복 일치 항목, 제안된 파일 diff를 검토하세요.
샘플의 경우 미리보기에는 5.25 USD 식사 비용과 1,000 USD 급여 입금이 포함되어야 합니다. 임포터 또는 소스 데이터에서 잘못된 범주를 수정한 후 다시 미리보세요. 가져오기를 적용하기 전에 누락된 계정을 여세요.
여러 임포터가 파일을 인식하는 경우 이름으로 하나를 선택하세요:
bea import bank.csv --config importers.py --importer categorized-checking알 수 없는 이름은 구성된 이름을 나열합니다. 파일을 인식하지 못하는 알려진 임포터는 이를 별도로 보고합니다.
3. 검토된 항목 적용
bea import bank.csv --apply
bea check
bea list transaction --limit 10CLI는 이 루트 원장에 대한 구성 경로를 기억합니다. 이후 실행은 명시적 --config, 그 다음 기억된 경로, 그 다음 루트 옆의 importers.py를 선택합니다. 출력은 경로와 그 출처를 명명합니다.
--apply는 현재 파일에 대해 미리보기를 다시 계산합니다. 쓰기 전에 전체 후보 원장을 검증합니다. 검증 실패는 원본 원장을 변경하지 않고 종료 코드 1로 끝납니다. 동시 원장 변경은 종료 코드 4로 끝납니다. 변경 사항을 검사하고 재시도 전에 새 미리보기를 실행하세요.
4. 가능한 중복 해결
동일한 샘플 가져오기를 반복하면 기존 항목을 건너뜁니다. 겹치는 export에는 결정이 필요한 행이 포함될 수도 있습니다:
| 미리보기 상태 | 의미 | 수행할 작업 |
|---|---|---|
new | 중복 증거 없음 | 금액과 범주 확인 |
duplicate | 안정적 ID와 거래 세부정보가 일치하거나 동일한 비거래 지시문이 존재함 | 이미 건너뜀 |
possible_duplicate | 날짜, 정규화된 수취인, 부호 있는 소스 금액/통화가 일치함 | 미리보기와 기존 항목 비교 |
conflict | 안정적 ID가 다른 거래 세부정보와 일치함 | ID 또는 데이터 불일치 해결 후 다시 미리보기 |
다른 은행 ID가 중복을 배제하지는 않습니다. 은행은 이후 다운로드에서 ID를 변경할 수 있습니다. 두 개의 실제 구매가 날짜, 수취인, 금액을 공유할 수도 있습니다.
모든 가능한 일치 항목을 검토한 후 다음 대안 중 하나를 선택하세요:
bea import bank.csv --apply --duplicates skipbea import bank.csv --apply --duplicates include결정은 해당 호출의 모든 가능한 일치 항목에 적용됩니다. 정확한 중복은 계속 건너뜁니다. ID 충돌은 여전히 쓰기를 차단합니다.
기본 --duplicates review는 해결되지 않은 일치 항목의 적용을 거부합니다. 종료 코드 4로 끝나고 영향을 받는 미리보기 행을 명명합니다. --no-input 및 --yes는 해당 검토를 우회하지 않습니다. 모든 행을 건너뛰려는 의도적 결정은 원장 추가 없이 종료 코드 0으로 끝납니다.
가져오기를 반복 가능하게 유지
기본적으로 중복 일치 검사는 임포터의 소스 계정 내 bank_id, fitid, transaction_id, imported_id 메타데이터를 확인합니다. 반복되는 --id-key KEY 옵션을 사용하여 해당 세트를 대체하세요.
CLI는 또한 원본 export에서 행을 식별하기 위해 bea_import_id 메타데이터를 기록합니다. 가져온 항목을 편집할 때 유지하세요. 가능한 일치 항목은 기존 거래 및 동일 배치의 승인된 행과 비교됩니다.
수취인, 설명, 문자열 메타데이터는 미리보기 및 쓰기 전에 줄바꿈을 공백으로 대체합니다. 따옴표와 백슬래시는 내용을 유지합니다. 가져온 상점 텍스트는 따라서 단일 원장 줄에서 읽을 수 있습니다.
가져오기는 항목을 추가합니다. 기존 거래를 업데이트하거나 삭제하지 않습니다. 원장에서 의도적으로 수정하고 bea check를 실행하세요. bea add transactions로 대량 JSON 항목을 추가할 때는 중복 감지가 없습니다.
포함된 파일에 쓰기
--file을 루트로 유지하고 --into로 대상을 선택하세요:
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply2026.bean은 이미 존재해야 하고 루트에 포함되어야 합니다. 경로는 루트 디렉토리 기준입니다. export 경로는 작업 디렉토리 기준으로 유지됩니다. 미리보기는 변경될 파일을 식별합니다.
스크립트에서 가져오기 사용
bea --json --no-input import bank.csv --apply --duplicates skipskip은 가능한 일치 항목에 대한 의도된 정책일 때만 선택하세요. JSON은 data 내부에 미리보기와 쓰기 횟수를 반환합니다. 거부된 적용은 stderr의 error.result에 미리보기를 넣고 written: 0을 반환합니다. 항상 종료 상태를 확인하세요. 무인 가져오기를 예약하기 전에 JSON 및 종료 코드 참조를 참조하세요.
임포터 문제 해결
구성이 타사 패키지를 가져오는 경우 해당 패키지는 bea를 실행하는 Python 환경에 있어야 합니다. 예:
uv run --with beancount-io --with beangulp \
bea --file ~/my-books/main.bean import bank.ofx --config importers.py별도로 설치된 은행 임포터에는 --with YOUR_IMPORTER_PACKAGE를 추가하세요. 이는 Homebrew와 별도의 환경을 사용합니다.
임포터 예외의 경우 명령 앞에 --debug를 넣어 traceback을 표시하세요:
bea --debug import bank.csv --config importers.py임포터 출력은 importer_output에 캡처되어 JSON을 손상시키지 않습니다. JSON 디버그 모드에서 traceback은 error.traceback입니다.
Python 임포터 없이 일회성 변환의 경우 CSV 변환기 또는 OFX 및 QIF 변환기를 시도하세요. 생성된 항목을 장부에 추가하기 전에 검토하세요.