Importar exportaciones bancarias con la CLI

Use bea import para obtener una vista previa de una exportación bancaria, revisar duplicados y añadir entradas validadas a su libro mayor local.

Necesita un libro mayor existente y un importador de Python para el formato de exportación exacto de su banco. Si está comenzando libros nuevos, siga la guía de inicio rápido de la CLI. Conserve la exportación bancaria original para poder compararla con la vista previa.

1. Elija un importador​

Un importador lee el archivo del banco y suministra las cuentas de transacción. Bea no adivina el formato ni categoriza compras con un modelo de IA.

Su configuración importers.py exporta CONFIG = [importer, ...]. Los importadores utilizan la interfaz actual de Beangulp: identify(filepath), account(filepath) y extract(filepath, existing). Los asientos de cuenta de origen necesitan montos explícitos para la coincidencia de duplicados.

Para una primera prueba de práctica, guarde la configuración de CSV categorizado de ejemplo como importers.py junto a su libro mayor raíz. Utiliza solo Beancount y la biblioteca estándar de Python, por lo que funciona con la instalación de Homebrew.

Guarde esta muestra como bank.csv en el mismo directorio:

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

La muestra usa un monto firmado de cuenta corriente: el gasto es negativo y el depósito es positivo. Category suministra la otra cuenta. Ambas categorías están en la plantilla USD creada por bea init.

Use un importador escrito para su banco al importar su CSV, OFX o QIF nativo. La configuración de muestra espera exactamente las columnas anteriores. Solo ejecute configuraciones de Python que confíe.

2. Vista previa de las entradas​

Ejecute esto desde el directorio que contiene main.bean:

bea import bank.csv --config importers.py

Todavía no se escribe nada en el libro mayor. Revise las fechas, beneficiarios, montos de origen firmados, cuentas de destino, coincidencias duplicadas y la diferencia de archivo propuesta en la vista previa.

Para la muestra, la vista previa debe contener un gasto de comidas de 5.25 USD y un depósito de salario de 1,000 USD. Corrija una categoría incorrecta en el importador o en los datos de origen, luego previsualice de nuevo. Abra cualquier cuenta faltante antes de aplicar la importación.

Si varios importadores reconocen el archivo, seleccione uno por nombre:

bea import bank.csv --config importers.py --importer categorized-checking

Un nombre desconocido enumera los nombres configurados. Un importador conocido que no reconoce el archivo lo informa por separado.

3. Aplique las entradas revisadas​

bea import bank.csv --apply
bea check
bea list transaction --limit 10

La CLI recuerda la ruta de configuración para este libro mayor raíz. Las ejecuciones futuras eligen el --config explícito, luego la ruta recordada, y luego importers.py junto a la raíz. La salida nombra la ruta y su origen.

--apply recalcula la vista previa contra los archivos actuales. Valida el libro mayor candidato completo antes de escribir. Una falla de validación deja el libro mayor original sin cambios y sale con 1. Un cambio concurrente en el libro mayor sale con 4; inspeccione el cambio y ejecute una nueva vista previa antes de reintentar.

4. Resuelva posibles duplicados​

Repetir la misma importación de muestra omite sus entradas existentes. Una exportación superpuesta también puede contener filas que requieren una decisión:

Un ID bancario diferente no descarta un duplicado. Los bancos pueden cambiar los IDs en descargas posteriores. Dos compras reales también pueden compartir fecha, beneficiario y monto.

Después de revisar cada posible coincidencia, elija una de estas alternativas:

bea import bank.csv --apply --duplicates skip

bea import bank.csv --apply --duplicates include

La decisión se aplica a todas las posibles coincidencias en esa invocación. Los duplicados exactos permanecen omitidos. Los conflictos de ID aún bloquean la escritura.

El --duplicates review predeterminado se niega a aplicar coincidencias sin resolver. Sale con 4 y nombra las filas de vista previa afectadas. --no-input y --yes no omiten esa revisión. Una decisión intencional de omitir cada fila sale con 0 sin adiciones al libro mayor.

Mantenga las importaciones repetibles​

Por defecto, la coincidencia de duplicados verifica los metadatos bank_id, fitid, transaction_id e imported_id dentro de la cuenta de origen del importador. Use opciones repetidas --id-key KEY para reemplazar ese conjunto.

La CLI también escribe metadatos bea_import_id para identificar la fila en la exportación original. Consérvelos al editar entradas importadas. Las posibles coincidencias se verifican contra transacciones existentes y filas aceptadas en el mismo lote.

Beneficiarios, narraciones y metadatos de cadena reemplazan saltos de línea con espacios antes de la vista previa y la escritura. Las comillas y barras invertidas conservan su contenido. El texto del comerciante importado permanece legible en una sola línea del libro mayor.

Importar añade entradas; no actualiza ni elimina una transacción existente. Haga correcciones deliberadamente en su libro mayor y ejecute bea check después. La entrada JSON masiva con bea add transactions no tiene detección de duplicados.

Escribir en un archivo incluido​

Mantenga --file apuntando a la raíz y seleccione el destino con --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 --apply

2026.bean ya debe existir y estar incluido por la raíz. Su ruta es relativa al directorio raíz. La ruta de exportación permanece relativa a su directorio de trabajo. La vista previa identifica el archivo que cambiará.

Uso de importaciones en un script​

bea --json --no-input import bank.csv --apply --duplicates skip

Elija skip solo cuando esa sea su política prevista para posibles coincidencias. JSON devuelve la vista previa y el recuento de escritura dentro de data. Las aplicaciones rechazadas ponen la vista previa en error.result en stderr, con written: 0. Siempre verifique el estado de salida. Consulte la referencia de JSON y códigos de salida antes de programar importaciones sin supervisión.

Solucionar problemas de un importador​

Si la configuración importa paquetes de terceros, esos paquetes deben estar en el entorno de Python que ejecuta bea. Por ejemplo:

uv run --with beancount-io --with beangulp \
  bea --file ~/my-books/main.bean import bank.ofx --config importers.py

Agregue --with YOUR_IMPORTER_PACKAGE para un importador bancario instalado por separado. Esto usa un entorno separado de Homebrew.

Para una excepción del importador, ponga --debug antes del comando para mostrar su rastreo:

bea --debug import bank.csv --config importers.py

La salida del importador se captura en importer_output para que no corrompa el JSON. En modo de depuración JSON, el rastreo es error.traceback.

Para una conversión única sin un importador de Python, pruebe el convertidor CSV o el convertidor OFX y QIF. Revise las entradas generadas antes de agregarlas a sus libros.