일반 은행 CSV는 Python 임포터가 필요 없습니다. --csv로 열을 매핑하고, --account로 출금 계좌를 지정하고, --rules로 행을 분류한 다음, bea import로 항목을 미리 보고 적용하세요.
기존 장부가 필요합니다. 새 장부를 시작하는 경우 CLI 빠른 시작을 따르세요. 원본 은행 내역을 보관하여 미리보기와 비교할 수 있게 하세요.
1. CSV 열 매핑
이 샘플을 statement.csv로 저장한 다음, 같은 디렉터리에서 아래 명령을 실행하세요:
Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99금액은 은행 부호 규약을 따릅니다: 지출은 음수, 입금은 양수입니다. 통화는 장부의 운영 통화를 기본값으로 하므로 이 파일에는 통화 열이 필요 없습니다. 은행 설명 열을 narration에 넣고 payee는 판매처로 유지하세요.
장부를 만들고 아래에서 사용할 연료 하위 계좌를 여세요:
bea --no-input init books --currency USD --date 2026-08-01 \
--opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD템플릿은 이미 Expenses:Groceries 및 기타 일반 계좌를 엽니다. Expenses:Transport:Fuel은 열지 않으므로 가져오기 전에 두 번째 명령으로 엽니다. --file과 같은 전역 옵션은 하위 명령 앞에 옵니다.
2. 항목 미리보기
이 분류 규칙을 rules.toml로 저장한 다음 미리보세요:
cat > rules.toml <<'EOF'
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
EOF
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml규칙은 먼저 payee를 일치시킨 다음 대소문자를 무시하고 narration을 일치시킵니다. 첫 번째로 일치하는 규칙이 적용됩니다. 어떤 규칙도 일치하지 않는 행은 Expenses:Uncategorized에 플래그 !와 함께 전기되어 나중에 검토합니다. IMPORTING 가이드에는 debit 및 credit 쌍, category 열, --csv auto 헤더 읽기를 포함한 전체 매핑 참조가 문서화되어 있습니다.
아직 장부에는 아무것도 기록되지 않습니다. 미리보기는 3 ready, 0 exact duplicates, 0 possible duplicates를 보고하고 종료 코드 0으로 종료합니다. RULE 열은 행별로 승리한 패턴을 나타내며, Unknown Shop 행은 unmatched입니다. 날짜, payee, 부호 있는 소스 금액, 대상 계좌, 중복 일치, 제안된 파일 diff를 검토하세요. 잘못된 규칙이나 분류를 수정한 후 다시 미리보세요. 가져오기를 적용하기 전에 누락된 계좌를 여세요: 장부에 열리지 않은 계좌를 규칙이 지정하면 검증이 실패합니다.
3. 검토된 항목 적용
bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"열 매핑은 장부, 헤더 행, 소스 계좌별로 기억되므로 --apply는 플래그 없이 다시 실행되고 기억된 열 매핑을 사용하여 보고합니다. 현재 파일에 대해 미리보기를 다시 계산하고, 쓰기 전에 전체 후보 장부를 검증하고, 3개 항목을 기록합니다. bea check는 오류가 없음을 보고합니다. ! 큐는 일치하지 않은 행 하나를 나열합니다: -9.99 USD의 mystery인 Unknown Shop. 검증 통과는 장부가 균형을 이루고 유효하다는 것만 증명합니다. 해당 행이 Expenses:Uncategorized에 속하는지에 대해서는 아무 말도 하지 않으므로 장부에서 의도적으로 다시 분류하세요. 검사는 930.01 USD에서 끝납니다: 1,000 USD 개시 잔액에서 69.99 USD 지출을 뺀 값입니다.
4. 반복 가져오기는 추가하지 않음
bea --file books/main.bean import statement.csv --apply미리보기는 0 ready, 3 exact duplicates를 보고하고, 실행은 0개 항목을 기록하고 종료 코드 0으로 종료합니다. 기록된 각 행은 콘텐츠 해시가 포함된 import-id 메타데이터를 가지므로 동일한 파일은 모든 행과 일치합니다. 가져온 항목을 편집할 때 해당 메타데이터를 유지하세요. 가져오기는 항목을 추가합니다. 기존 거래를 업데이트하거나 삭제하지 않습니다. 장부에서 의도적으로 수정하고 이후 bea check를 실행하세요. bea add transactions로 대량 JSON 항목을 추가하는 경우 중복 감지 기능이 없습니다.
5. 가능한 중복 해결
나중에 다운로드하면 다른 설명이나 은행 ID로 행이 반복될 수 있습니다. 날짜, 정규화된 payee, 부호 있는 소스 금액은 여전히 가능한 일치로 표시합니다:
| 미리보기 상태 | 의미 | 조치 |
|---|---|---|
new | 중복 증거 없음 | 금액과 분류 확인 |
duplicate | 안정적인 ID와 거래 세부 정보 일치 또는 동일한 비거래 지시문이 존재 | 이미 건너뜀 |
possible_duplicate | 날짜, 정규화된 payee, 부호 있는 소스 금액/통화 일치 | 미리보기를 기존 항목과 비교 |
conflict | 안정적인 ID가 다른 거래 세부 정보와 일치 | ID 또는 데이터 불일치 해결 후 다시 미리보기 |
다른 은행 ID는 중복을 배제하지 않습니다. 은행은 나중에 다운로드에서 ID를 변경할 수 있습니다. 실제 구매 두 건도 날짜, payee, 금액이 같을 수 있으므로 가능한 일치는 증거이지 확정이 아닙니다. Bea는 AI 모델로 추측하지 않으며 규칙 외에는 분류를 대신하지 않습니다.
기본 --duplicates review는 해결되지 않은 일치를 적용하지 않습니다. 검증 실행에서 다른 설명으로 2026-08-02 Whole Foods -20.00 USD 행을 반복하는 두 번째 파일은 가능한 중복 1건으로 미리보기되었고, --apply는 아무것도 기록하지 않고 종료 코드 4로 종료했습니다. 각 가능한 일치를 검토한 후 다음 대안 중 하나를 선택하세요:
bea --file books/main.bean import statement.csv --apply --duplicates skip
bea --file books/main.bean import statement.csv --apply --duplicates include정당한 반복 구매를 보존하려면 include를 선택하세요. 해당 결정은 해당 호출의 모든 가능한 일치에 적용됩니다. 정확한 중복은 계속 건너뜁니다. ID 충돌은 여전히 쓰기를 차단합니다. --no-input 및 --yes는 그 검토를 우회하지 않습니다. 모든 행을 건너뛰는 의도적인 결정은 장부 추가 없이 종료 코드 0으로 종료합니다.
6. 다른 형식에는 Python 임포터 사용
OFX, QIF 또는 비정상적인 레이아웃의 CSV와 같이 열 매핑으로 표현할 수 없는 형식의 경우, bea import는 현재 Beangulp 인터페이스를 사용하는 구성된 임포터를 호출합니다: identify(filepath), account(filepath), extract(filepath, existing). 임포터는 은행별 파싱 및 분류를 담당합니다. 중복 일치가 실제 은행 금액을 사용하도록 소스 계좌 전기에 명시적 금액을 제공해야 합니다. Python 임포터는 이러한 형식의 고급 경로로 남아 있습니다. 은행 기본 CSV의 경우 먼저 --csv를 시도하세요.
첫 연습 실행을 위해 예제 분류 CSV 구성을 루트 장부 옆에 importers.py로 저장하세요. Beancount와 Python 표준 라이브러리만 사용하므로 Homebrew 설치에서 작동합니다. 샘플 bank.csv는 부호 있는 당좌 계좌 금액을 사용합니다: -5.25 USD 식비와 1,000 USD 급여 입금. 샘플 구성은 문서화된 정확한 열을 기대합니다. 신뢰하는 Python 구성만 실행하세요.
bea --file books/main.bean import bank.csv --config importers.py
bea --file books/main.bean import bank.csv --config importers.py --importer categorized-checking
bea --file books/main.bean import bank.csv --config importers.py --applyimporters.py 구성은 CONFIG = [importer, ...]를 내보냅니다. 여러 임포터가 파일을 인식하면 이름으로 하나를 선택하세요. 알 수 없는 이름은 구성된 이름을 나열합니다. 파일을 인식하지 못하는 알려진 임포터는 별도로 보고합니다.
CLI는 이 루트 장부의 구성 경로를 기억합니다. 향후 실행은 명시적 --config, 그 다음 기억된 경로, 그 다음 루트 옆의 importers.py를 선택합니다. 출력은 경로와 출처를 나타냅니다.
--apply는 현재 파일에 대해 미리보기를 다시 계산합니다. 쓰기 전에 전체 후보 장부를 검증합니다. 검증 실패는 원래 장부를 변경하지 않고 종료 코드 1로 종료합니다. 동시 장부 변경은 종료 코드 4로 종료합니다. 변경 사항을 검사하고 재시도 전에 새 미리보기를 실행하세요.
가져오기를 반복 가능하게 유지
기본적으로 중복 일치는 임포터의 소스 계좌 내에서 bank_id, fitid, transaction_id, imported_id 메타데이터를 확인합니다. 반복 --id-key KEY 옵션을 사용하여 해당 집합을 대체하세요.
안정적인 은행 ID가 있는 행은 bank: 또는 ofx: 접두사와 같은 종류를 나타내는 import-id 메타데이터와 함께 기록됩니다. 없는 행은 날짜, 금액, 설명, 계좌에 대한 csv:sha256: 콘텐츠 해시로 기록되므로 동일한 파일을 다시 가져오면 모든 행을 건너뜁니다. 이 규칙 이전에 기록된 항목은 여전히 bea_import_id 메타데이터를 가질 수 있으며 재가져오기에서 계속 일치합니다. 가능한 일치는 기존 거래와 같은 배치의 승인된 행에 대해 확인됩니다.
Payee, 설명, 문자열 메타데이터는 미리보기 및 쓰기 전에 줄바꿈을 공백으로 대체합니다. 따옴표와 백슬래시는 내용을 유지합니다. 따라서 가져온 판매처 텍스트는 단일 장부 줄에서 읽을 수 있습니다.
포함된 파일에 쓰기
--file을 루트로 유지하고 --into로 대상을 선택하세요:
bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply2026.bean은 이미 존재하고 루트에 포함되어야 합니다. 경로는 루트 디렉터리에 상대적입니다. 내보내기 경로는 작업 디렉터리에 상대적으로 유지됩니다. 미리보기는 변경될 파일을 식별합니다.
스크립트에서 가져오기 사용
bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skip가능한 일치에 대한 의도된 정책인 경우에만 skip을 선택하세요. JSON은 미리보기와 쓰기 수를 data 안에 반환합니다. 거부된 적용은 미리보기를 stderr의 error.result에 두고 written: 0으로 표시합니다. 항상 종료 상태를 확인하세요. 무인 가져오기를 예약하기 전에 JSON 및 종료 코드 참조를 참조하세요.
임포터 문제 해결
임포터 구성은 관리 엔진에서 실행됩니다. 구성이 Beangulp를 가져오는 경우 시스템 libmagic 라이브러리를 설치하고 엔진에서 Beangulp를 한 번 활성화하세요:
bea engine enable beangulp
bea --file books/main.bean import bank.ofx --config importers.py
bea --debug --file books/main.bean import bank.csv --config importers.pybea engine status는 활성화된 기능을 보고합니다. bea 프론트엔드와 함께 은행 임포터를 설치해도 엔진 내부에서 사용할 수 없습니다. 추가 패키지를 가져오는 구성은 해당 종속성이 엔진에 필요합니다. Beangulp만 활성화하면 설치되지 않습니다. 해당 임포터 종속성을 사용할 수 없는 경우 CSV 매퍼 또는 아래 변환기를 사용하세요.
임포터 예외의 경우 명령 앞에 --debug를 넣어 traceback을 표시하세요. 임포터 출력은 importer_output에 캡처되어 JSON을 손상시키지 않습니다. JSON 디버그 모드에서 traceback은 error.traceback입니다.
Python 임포터 없이 일회성 변환의 경우 CSV 변환기 또는 OFX 및 QIF 변환기를 시도하세요. 장부에 추가하기 전에 생성된 항목을 검토하세요.