Preguntas frecuentes

Privacidad de datos y cumplimiento normativo

¿Algún dato sale de mi infraestructura?

No. El Analizador de extractos bancarios opera como una biblioteca sin estado. Todo el procesamiento -- análisis, enmascaramiento de PII, extracción de archivos -- se realiza en la memoria de su entorno de ejecución local. Sin llamadas a API, sin servicios en la nube, sin telemetría. Los analizadores XML están reforzados con no_network=True, bloqueando todo acceso saliente a nivel del parser. Sus datos financieros nunca abandonan su entorno.

¿Cómo funciona el enmascaramiento de PII?

Los campos sensibles se ocultan antes de llegar a la lógica de su aplicación. El analizador identifica nombres de deudores, nombres de acreedores, IBANs y direcciones postales, reemplazándolos con ***REDACTED*** en la salida de consola y en modo streaming.

• El enmascaramiento está activo por defecto en la salida CLI y en modo streaming.
• Las exportaciones de archivos (CSV, JSON, Excel) conservan los datos sin enmascarar para el procesamiento posterior.
• Active la visualización completa con --show-pii en la CLI o redact_pii=False en la API.

¿El proceso de extracción es determinista?

Sí -- salida idéntica byte a byte en cada ejecución. Dado el mismo archivo de entrada, el analizador produce el mismo resultado cada vez. Sin aleatoriedad, sin inferencia de modelos, sin muestreo heurístico. La integración continua garantiza el determinismo con 467 pruebas al 100% de cobertura de ramas, incluyendo fuzzing basado en propiedades mediante Hypothesis.

¿Qué estándares de cumplimiento sigue el proyecto?

El proyecto mantiene documentación alineada con ISO 13485 con trazabilidad completa:

• Un Registro de riesgos cuantificado con puntuación de severidad/probabilidad y evaluación de riesgo residual.
• Un Plan de verificación y validación con 19 pasos controlados en 5 fases.
• Un Procedimiento de control de cambios con evaluación de impacto y protocolos de reversión.
• Un Registro SOUP que cubre todas las dependencias con niveles de riesgo y seguimiento de fin de vida.
• Una Matriz de trazabilidad que relaciona entradas de diseño con implementación y verificación.

Cada versión incluye un SBOM CycloneDX, sumas de verificación SHA-256 y atestación de procedencia de compilación de GitHub.

Rendimiento y escalabilidad

¿Qué tan rápido es el Analizador de extractos bancarios?

Los umbrales de rendimiento se validan en la integración continua en cada commit:

¿Cómo se gestionan los archivos grandes?

Streaming con memoria acotada -- probado con 50,000 transacciones por archivo. Use parse_streaming() para procesar archivos XML de forma incremental. Cada transacción se emite como un diccionario; los elementos se limpian después del procesamiento para evitar el crecimiento de memoria. La memoria no escala con el tamaño del archivo -- la prueba de 50K transacciones (25+ MB) usa menos del doble de memoria que la prueba de 10K transacciones.

Para archivos que excedan 50 MB (por ejemplo, lotes PAIN.001 host-to-host con 100K+ pagos), el analizador procesa mediante un archivo temporal con eliminación de namespaces basada en fragmentos -- el documento completo nunca se carga en memoria.

¿Cómo se procesan los archivos ZIP de forma segura?

iter_secure_xml_entries() valida cada miembro antes de la extracción:

• Tope de tamaño de entrada (10 MB por entrada por defecto)
• Tope de tamaño total descomprimido (50 MB por defecto)
• Límite de ratio de compresión (100:1 por defecto) para prevenir bombas ZIP
• Rechazo de entradas cifradas

No se escribe ningún archivo en disco. Los bytes XML pasan directamente al analizador mediante from_bytes().

¿Puedo analizar múltiples archivos en paralelo?

Sí. Use parse_files_parallel() que distribuye el trabajo a través de un 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), "filas")

Formatos soportados

¿Qué formatos de extractos bancarios se soportan?

Formato	Estándar	Tipos de archivo	Clase del parser
CAMT.053	ISO 20022 Extracto banco-cliente	.xml	CamtParser
PAIN.001	ISO 20022 Iniciación de transferencia de crédito	.xml	Pain001Parser
CSV	Exportaciones bancarias genéricas	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	Estándar SWIFT	.mt940, .sta	Mt940Parser

¿El analizador gestiona dialectos CAMT.053 específicos de cada banco?

Sí -- agnóstico a namespaces por diseño. El analizador elimina los namespaces XML antes del procesamiento, gestionando cualquier variante de CAMT.053 (camt.053.001.02, camt.053.001.04, o envoltorios propietarios de bancos) sin configuración específica de namespace. Las consultas XPath apuntan a la estructura del elemento, no a las URIs de namespace.

Para bancos que envuelven CAMT en un sobre personalizado, use from_string() o from_bytes() para alimentar el documento interno directamente.

¿Puedo mapear encabezados CSV personalizados al esquema estándar?

Sí -- normalización automática, cero configuración. CsvStatementParser reconoce variaciones comunes de encabezados: "Date", "Transaction Date", "Booking Date" se mapean al campo date. "Amount", "Value", "Sum" se mapean a amount. Las columnas divididas de crédito/débito (por ejemplo, "Credit" y "Debit") se detectan y combinan automáticamente en un monto con signo único.

¿Cuál es el formato de salida?

Todos los analizadores producen DataFrames de pandas estandarizados con tipos de columna consistentes:

Formato	Columnas principales
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 (normalizado)

También puede exportar a CSV, JSON, Excel o convertir a DataFrames de Polars.

Flujos de trabajo de tesorería

¿Cómo gestiona el analizador los extractos multidivisa?

Cada transacción conserva su divisa original -- sin conversión implícita. El campo Currency se extrae del atributo XML Ccy por transacción. Los extractos multidivisa permanecen tal cual. El método get_account_balances() devuelve saldos de apertura y cierre por cuenta con códigos de divisa originales. La conciliación entre divisas queda para su lógica posterior, donde usted controla la fuente de tipos de cambio.

¿El analizador soporta tanto formatos de salida como de entrada?

Sí. Pain001Parser gestiona archivos de iniciación de transferencia de crédito ISO 20022 PAIN.001 (pagos salientes). CamtParser gestiona archivos de extracto banco-cliente CAMT.053 (informes entrantes). Ambos soportan streaming, enmascaramiento de PII y exportación a CSV, JSON y Excel. Use detect_statement_format() para identificar el formato automáticamente.

¿Qué sucede cuando una entrada de transacción está malformada?

El comportamiento depende del modo de análisis:

• parse() (modo lote) -- Las entradas malformadas que carecen de campos obligatorios (Amount, Currency o CdtDbtInd) se omiten con un registro de advertencia. El resto del extracto se analiza normalmente.
• parse_streaming() (modo streaming) -- Los errores de análisis se propagan inmediatamente como excepciones. Sin pérdida silenciosa de datos. Este comportamiento de fallo rápido es intencional para flujos de trabajo financieros donde cada transacción debe ser contabilizada.

¿Cómo funciona la deduplicación?

La clase Deduplicator detecta duplicados exactos y coincidencias sospechosas con puntuaciones de confianza explicables:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Únicos: {len(result.unique_transactions)}")
print(f"Duplicados exactos: {len(result.exact_duplicates)}")
print(f"Coincidencias sospechosas: {len(result.suspected_matches)}")

Instalación y compatibilidad

¿Cómo instalo el Analizador de extractos bancarios?

pip install bankstatementparser

Para soporte opcional de DataFrames de Polars:

pip install bankstatementparser[polars]

¿Qué versiones de Python se soportan?

Python 3.9 a 3.14. Todas las versiones se prueban en la integración continua con 467 pruebas al 100% de cobertura de ramas.

¿Cuáles son las dependencias?

La biblioteca tiene 5 dependencias directas:

• lxml -- Análisis XML con refuerzo de seguridad
• pandas -- DataFrames y manipulación de datos
• openpyxl -- Exportación a Excel
• pydantic -- Validación de datos y modelos
• defusedxml -- Protección XXE

Todas las dependencias tienen versiones con hash SHA-256 bloqueado. El SBOM CycloneDX mapea cada componente en tiempo de ejecución.

¿Funciona en macOS, Linux y Windows?

Sí. La biblioteca funciona en macOS, Linux y Windows (vía WSL). No tiene dependencias específicas de plataforma.

Reproducibilidad y seguridad

¿Cómo puedo verificar la reproducibilidad?

python -m pytest                              # 467 pruebas, 100% cobertura de ramas
python scripts/verify_locked_hashes.py        # Verificación de hash SHA-256
git log --show-signature -1                   # Verificar firma del commit

¿Qué protecciones de seguridad están integradas?

• Protección XXE: resolve_entities=False, no_network=True, load_dtd=False
• Protección contra bombas ZIP: Límites de ratio de compresión, topes de tamaño de entrada, rechazo de entradas cifradas
• Prevención de path traversal: Lista de bloqueo de patrones peligrosos y resolución de enlaces simbólicos
• Validación de entrada: Límites de tamaño de archivo (100 MB por defecto), validación de extensión/formato
• Cadena de suministro: Dependencias con hash SHA-256 bloqueado, SBOM CycloneDX, atestación de procedencia de compilación
• Commits firmados: Obligatorios en la integración continua

¿Cómo se compara el Analizador de extractos bancarios con pyiso20022?

pyiso20022 es un toolkit ISO 20022 general que genera dataclasses de Python a partir de los esquemas XML de ISO. Cubre una amplia gama de tipos de mensajes ISO 20022 (PACS, PAIN, CAMT, ADMI) con validación de esquemas. El Analizador de extractos bancarios está diseñado específicamente para el análisis de extractos bancarios con soporte de streaming, enmascaramiento de PII, deduplicación y una API unificada para seis formatos, incluyendo formatos no ISO (CSV, OFX, QFX, MT940). Si necesita analizar extractos bancarios en DataFrames con seguridad de nivel de producción, use el Analizador de extractos bancarios. Si necesita trabajar con el catálogo completo de mensajes ISO 20022, use pyiso20022.

¿Cuáles son los plazos de migración a ISO 20022 de SWIFT?

SWIFT ha publicado un cronograma de migración por fases:

• Noviembre 2026: Las direcciones estructuradas e híbridas se vuelven obligatorias. Los mensajes MT101 multi-instrucción serán rechazados. Comienza la Fase 1 de gestión de casos.
• Noviembre 2027: Todas las instituciones financieras deben poder recibir extractos CAMT.053 de forma nativa. SWIFT dejará de convertir el formato MT a ISO.
• Noviembre 2028: Retiro completo de MT940, MT942, MT950, MT900 y MT910. Serán reemplazados por los equivalentes CAMT.052, CAMT.053 y CAMT.054.

El Analizador de extractos bancarios soporta tanto el formato heredado MT940 como los formatos modernos CAMT.053/PAIN.001, lo que lo hace ideal para el período de transición.