Perguntas frequentes

Privacidade de dados e conformidade

Algum dado sai da minha infraestrutura?

Nao. O Analisador de extratos bancarios opera como uma biblioteca sem estado. Todo o processamento -- analise, mascaramento de PII, extracao de arquivos -- ocorre na memoria local de execucao. Sem chamadas de API, sem servicos de nuvem, sem telemetria. Os parsers XML sao protegidos com no_network=True, bloqueando todo acesso externo no nivel do parser. Seus dados financeiros nunca saem do seu ambiente.

Como funciona o mascaramento de PII?

Campos sensiveis sao mascarados antes de chegarem a logica da sua aplicacao. O parser identifica nomes de devedores, nomes de credores, IBANs e enderecos postais, substituindo-os por ***REDACTED*** na saida do console e no modo streaming.

• O mascaramento esta ativado por padrao na saida CLI e no modo streaming.
• Exportacoes de arquivos (CSV, JSON, Excel) mantem dados nao mascarados para processamento posterior.
• Ative dados completos com --show-pii no CLI ou redact_pii=False na API.

O processo de extracao e deterministico?

Sim -- saida identica byte a byte em cada execucao. Com o mesmo arquivo de entrada, o parser produz o mesmo resultado todas as vezes. Sem aleatoriedade, sem inferencia de modelo, sem amostragem heuristica. O CI impoe determinismo com 467 testes em cobertura 100% de branches, incluindo fuzzing baseado em propriedades via Hypothesis.

Quais padroes de conformidade o projeto segue?

O projeto mantem documentacao alinhada a ISO 13485 com rastreabilidade completa:

• Um Registro de riscos quantificado com pontuacao de severidade/probabilidade e avaliacao de risco residual.
• Um Plano de verificacao e validacao com 19 etapas controladas em 5 fases.
• Um Procedimento de controle de mudancas com avaliacao de impacto e protocolos de rollback.
• Um Registro SOUP cobrindo todas as dependencias com niveis de risco e rastreamento de EOL.
• Uma Matriz de rastreabilidade mapeando entradas de design para implementacao e verificacao.

Cada versao inclui um SBOM CycloneDX, checksums SHA-256 e atestacao de procedencia de build do GitHub.

Desempenho e escalabilidade

Qual e a velocidade do Analisador de extratos bancarios?

Os limiares de desempenho sao validados no CI a cada commit:

Como arquivos grandes sao tratados?

Streaming com memoria limitada -- testado com 50.000 transacoes por arquivo. Use parse_streaming() para processar arquivos XML incrementalmente. Cada transacao e retornada como dicionario; elementos sao limpos apos o processamento para evitar crescimento de memoria. A memoria nao escala com o tamanho do arquivo -- o teste com 50K transacoes (25+ MB) usa menos de 2x a memoria do teste com 10K transacoes.

Para arquivos superiores a 50 MB (por exemplo, lotes PAIN.001 host-to-host com 100K+ pagamentos), o parser processa via streaming atraves de um arquivo temporario com remocao de namespaces por blocos -- o documento completo nunca e carregado na memoria.

Como arquivos ZIP sao processados com seguranca?

iter_secure_xml_entries() valida cada membro antes da extracao:

• Limite de tamanho de entrada (padrao 10 MB por entrada)
• Limite de tamanho total descomprimido (padrao 50 MB)
• Limite de taxa de compressao (padrao 100:1) para prevenir bombas ZIP
• Rejeicao de entradas criptografadas

Nenhum arquivo e escrito em disco. Bytes XML passam diretamente ao parser via from_bytes().

Posso analisar multiplos arquivos em paralelo?

Sim. Use parse_files_parallel() que distribui o trabalho em um 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")

Formatos suportados

Quais formatos de extratos bancarios sao suportados?

Formato	Padrao	Tipos de arquivo	Classe parser
CAMT.053	ISO 20022 Extrato banco-para-cliente	.xml	CamtParser
PAIN.001	ISO 20022 Iniciacao de transferencia de credito	.xml	Pain001Parser
CSV	Exportacoes bancarias genericas	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	Padrao SWIFT	.mt940, .sta	Mt940Parser

O parser lida com dialetos CAMT.053 especificos de bancos?

Sim -- agnostico a namespace por design. O parser remove namespaces XML antes do processamento, lidando com qualquer variante CAMT.053 (camt.053.001.02, camt.053.001.04 ou wrappers proprietarios de bancos) sem configuracao especifica de namespace. Consultas XPath visam a estrutura dos elementos, nao URIs de namespace.

Para bancos que encapsulam CAMT em um envelope personalizado, use from_string() ou from_bytes() para fornecer o documento interno diretamente.

Posso mapear cabecalhos de colunas CSV personalizados para o esquema padrao?

Sim -- normalizacao automatica, zero configuracao. CsvStatementParser reconhece variacoes comuns de cabecalhos: "Date", "Transaction Date", "Booking Date" mapeiam para o campo date. "Amount", "Value", "Sum" mapeiam para amount. Colunas separadas de credito/debito (por exemplo, "Credit" e "Debit") sao detectadas e combinadas automaticamente em um unico valor com sinal.

Qual e o formato de saida?

Todos os parsers produzem DataFrames pandas padronizados com tipos de colunas consistentes:

Formato	Colunas principais
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 (normalizados)

Voce tambem pode exportar para CSV, JSON, Excel ou converter para DataFrames Polars.

Fluxos de tesouraria

Como o parser lida com extratos multimoeda?

Cada transacao preserva sua moeda original -- sem conversao implicita. O campo Currency e extraido do atributo XML Ccy por transacao. Extratos multimoeda permanecem inalterados. O metodo get_account_balances() retorna saldos de abertura e fechamento por conta com codigos de moeda originais. A reconciliacao entre moedas fica para sua logica posterior, onde voce controla a fonte da taxa de cambio.

O parser suporta tanto formatos de saida quanto de entrada?

Sim. Pain001Parser lida com arquivos ISO 20022 PAIN.001 de iniciacao de transferencia de credito (pagamentos enviados). CamtParser lida com arquivos CAMT.053 de extrato banco-para-cliente (relatorios recebidos). Ambos suportam streaming, mascaramento de PII e exportacao para CSV, JSON e Excel. Use detect_statement_format() para identificar o formato automaticamente.

O que acontece quando uma entrada de transacao esta malformada?

O comportamento depende do modo de analise:

• parse() (modo batch) -- Entradas malformadas sem campos obrigatorios (Amount, Currency ou CdtDbtInd) sao ignoradas com um aviso no log. O restante do extrato e analisado normalmente.
• parse_streaming() (modo streaming) -- Erros de analise se propagam imediatamente como excecoes. Sem perda silenciosa de dados. Este comportamento fail-fast e intencional para fluxos financeiros onde cada transacao deve ser contabilizada.

Como funciona a deduplicacao?

A classe Deduplicator detecta duplicatas exatas e correspondencias suspeitas com scores de confianca explicaveis:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Unicas: {len(result.unique_transactions)}")
print(f"Duplicatas exatas: {len(result.exact_duplicates)}")
print(f"Correspondencias suspeitas: {len(result.suspected_matches)}")

Instalacao e compatibilidade

Como instalo o Analisador de extratos bancarios?

pip install bankstatementparser

Para suporte opcional a DataFrame Polars:

pip install bankstatementparser[polars]

Quais versoes do Python sao suportadas?

Python 3.9 ate 3.14. Todas as versoes sao testadas no CI com 467 testes em cobertura 100% de branches.

Quais sao as dependencias?

A biblioteca tem 5 dependencias diretas:

• lxml -- analise XML com protecao de seguranca
• pandas -- DataFrames e manipulacao de dados
• openpyxl -- exportacao Excel
• pydantic -- validacao de dados e modelos
• defusedxml -- protecao XXE

Todas as dependencias tem versoes bloqueadas com hash SHA-256. O SBOM CycloneDX mapeia cada componente de runtime.

Funciona no macOS, Linux e Windows?

Sim. A biblioteca funciona no macOS, Linux e Windows (via WSL). Nao tem dependencias especificas de plataforma.

Reprodutibilidade e seguranca

Como posso verificar a reprodutibilidade?

python -m pytest                              # 467 testes, cobertura 100% de branches
python scripts/verify_locked_hashes.py        # Verificacao de hash SHA-256
git log --show-signature -1                   # Verificar assinatura do commit

Quais protecoes de seguranca estao integradas?

• Protecao XXE: resolve_entities=False, no_network=True, load_dtd=False
• Protecao contra bombas ZIP: Limites de taxa de compressao, limites de tamanho de entrada, rejeicao de entradas criptografadas
• Prevencao de travessia de caminho: Lista de bloqueio de padroes perigosos e resolucao de links simbolicos
• Validacao de entrada: Limites de tamanho de arquivo (100 MB padrao), validacao de extensao/formato
• Cadeia de suprimentos: Dependencias bloqueadas com hash SHA-256, SBOM CycloneDX, atestacao de procedencia de build
• Commits assinados: Impostos no CI

Como o Analisador de extratos bancarios se compara ao pyiso20022?

pyiso20022 e um toolkit ISO 20022 amplo que gera dataclasses Python a partir de esquemas XML ISO. Cobre uma ampla gama de tipos de mensagens ISO 20022 (PACS, PAIN, CAMT, ADMI) com validacao de esquema. O Analisador de extratos bancarios e construido especificamente para analise de extratos bancarios com suporte a streaming, mascaramento de PII, deduplicacao e uma API unificada para seis formatos, incluindo formatos nao-ISO (CSV, OFX, QFX, MT940). Se voce precisa analisar extratos bancarios em DataFrames com seguranca de nivel de producao, use o Analisador de extratos bancarios. Se voce precisa trabalhar com o catalogo completo de mensagens ISO 20022, use pyiso20022.

Quais sao os prazos de migracao SWIFT ISO 20022?

SWIFT publicou um cronograma de migracao faseado:

• Novembro 2026: Enderecos estruturados e hibridos se tornam obrigatorios. Mensagens MT101 com multiplas instrucoes serao rejeitadas. Fase 1 do Gerenciamento de Casos comeca.
• Novembro 2027: Todas as instituicoes financeiras devem ser capazes de receber extratos CAMT.053 nativamente. SWIFT deixara de converter formato MT para ISO.
• Novembro 2028: Aposentadoria total de MT940, MT942, MT950, MT900 e MT910. Serao substituidos pelos equivalentes CAMT.052, CAMT.053 e CAMT.054.

O Analisador de extratos bancarios suporta tanto o formato legado MT940 quanto os formatos modernos CAMT.053/PAIN.001, tornando-o ideal para o periodo de transicao.