Parsing de registros e automação
TL; DR
A «solavancagem» confiável é baseada em três baleias: ingestão definida (entrega segura, idempotação, controle de integridade), camada de dados normalizada (esquema único, chaves de comparação, unidades de tempo/moedas/caracteres normalizados) e disciplina de qualidade rígida (validação, tolerance, DLQ, alertas, auto). O objetivo é transformar arquivos/webhooks compartilhados em tabelas estáveis para acréscimos, relatórios e BI com SLA de disponibilidade.
1) Paisagem de fontes e formatos
1. 1 Fontes
PSP/equeiros/agregadores: transações, redes, comissões, displays.
Bancos: extratos MT940, ISO 20022 CAMT. 052/053/054, pagamentos PAIN. 001/002.
ARM/carteiras/pagamentos (OCT/RTP/SEPA): registros de payouts, devoluções.
Kripto-castody/bolsas: transações, relatórios de conversões/comissões.
Impostos/estatais. portais: CSV/XLSX/PDF, às vezes por meio de um navegador.
1. 2 Formatos
CSV/TSV (separadores variáveis, locais, codificações).
XLSX (multi-shit, células combinadas).
O URL (ISO 20022 CAMT/PAIN, XSD Kastoms).
SWIFT MT940/942 (campos de posição).
JSON-API/NDJSON (descarregadores, cursores).
PDF (tabelas - parser; scan - OCR).
ZIP/TAR. GZ (batches com arquivos múltiplos).
2) Arquitetura ingestion-pipline
Caminhos:1. Landing: recepção segura de arquivos (SFTP/FTPS/WebDAV/API/webhooks) → imediatamente achamos checksum, preservando a matéria-prima invariavelmente.
2. Raw: localização de datas/provedores/batches, armazenamento com versões.
3. Normalize: parsing unificação de tipos/unidades da tabela normalizável.
4. Validated: pós-validação (regras de qualidade) → bandeiras, DLQ.
5. Matched: mapeamento com eventos/bancos internos.
6. Serving/BI: vitrines para acréscimo/finanças/transações.
Requisitos essenciais:- Idempotidade ingestion: '(provider, arquivo _ name, arquivo _ size, checksum, statement _ data)' → uma chave única.
- Repetições/retraí: a reaproximação do arquivo não cria duplicações.
- DLQ (dead-letter queue): todas as regras não identificadas/violadas estão em uma fila isolada.
- Versioning: o novo arquivo do mesmo dia → uma nova versão com referência ao anterior.
3) Segurança de entrega e segredos
Canais: SFTP com chaves limitadas; FTPS - somente com TLS rigoroso; API - OAuth2/tokens com TTL curto.
Criptografia de conteúdo: PGP/GPG ao carregar arquivos; S/MIME para e-mail-inbox (se usado).
Controle de integridade: SHA-256/512 checksum, comparação com a hashtag no manifesto.
Segredos: armazenados em Vault/KMS, rotação, proibidos em ficheiros de config/logs.
Acessíveis: RBAC + princípio de «menores privilégios», contas de serviço individuais.
4) Normalização e esquema de dados
4. 1 Regras Universais
Hora: sempre UTC no ISO-8601; para datas de senslement - 'DATA' sem TZ.
Somas: 'DECIMAL (p, s)' em menor units + «scale» individual; sinal: chegada/consumo rigorosamente no dicionário.
Moedas: ISO-4217, tabela fixa de cursos com 'fx _ src'.
Local: proibição do dispositivo automático - configuração clara de divisores/pontos decimais/milésimos.
Codificações: entrada UTF-8; outros - conversão com logs.
4. 2 Camada «plana» normalizada (exemplo)
json
{
"provider": "Acquirer_A",
"source_kind": "PSP_TX PSP_SETTLEMENT BANK WALLET CRYPTO",
"kind": "AUTH CAPTURE REFUND PAYOUT FEE SETTLEMENT CHARGEBACK",
"payment_id": "pay_123", // ваше
"provider_txid": "psp_abc_789", // внешнее
"merchant_ref": "mr_456",
"sequence": 0, // partial/refund line index
"amount_minor": 100000, // 1000.00
"currency": "EUR",
"fee_minor": 120, // 1.20
"fx_rate": 1.0000,
"fx_src": "PSP ECB BANK",
"event_ts": "2025-11-03T12:00:00Z",
"value_date": "2025-11-05",
"account": "PSP_MERCHANT_CARD_A",
"bin": "425000",
"last4": "1234",
"status": "APPROVED CAPTURED SUCCESS FAILED SETTLED",
"file_id": "ing_20251103_001",
"row_hash": "sha256(raw_row)"
}5) Parsers em formatos: técnicas e roubos
5. 1 CSV/TSV
Especifique claramente «delimiter», «cotechar», «escapechar», «encoding».
5. 2 XLSX
Leitura por sheet whitelist; a proibição de camadas automáticas é uma vaga de células combinadas.
Converter fórmulas em valores; datas Excel → UTC com TZ explícito.
5. 3 XML (ISO 20022 CAMT/PAIN)
Validação por XSD; XPath-mapping de adereços ('<Ntry>', '<TxDtls>', 'Amt>', '<CdtDbtInd>').
Normalizar credit/debit → um sinal; suporte múltiplo '<Chrgs>', '<RmtInf>'.
5. 4 MT940
Analisar marcas de formatação ': 61:', ': 86:'; Apoio às extensões nacionais; campos de posição → regras slicing.
Consolidação de vários '61:' em um único batch.
5. 5 JSON/NDJSON/API
5. 6 PDF/OCR
Primeiro, a tentativa de parsing de tabela (por exemplo, detector), só depois OCR (Tesseract) com os caracteres whitelist.
Pós-validação: somas, resumos de verificação, verificação do número de linhas.
5. 7 Arquivos/Batches
Descompasso mantendo a estrutura; cada arquivo é «arquivo _ id» separado; manifesto, controlo de todas as partes.
6) Validações e regras de qualidade de dados
Verificações obrigatórias:- Esquema: todos os campos de required estão presentes.
- Os tipos: somas são numéricos, as datas são parceladas.
- Somas de referência/resumos: soma de linhas = resultado no arquivo (se houver).
- Faixas: data em uma janela inteligente; soma> 0 (ou dicionário negativo válido).
- Exclusividade: '(provider, provider _ txid, sequence)' não é duplicado no normalized.
- Tolerance: variações válidas 'amount/fx/time'.
Resultado: 'VALID', 'VALID _ WITH _ WARNINGS', 'INVALID → DLQ'.
7) Idempotidade e dedução
Ingestion key: '(provider, arquivo _ name, filesize, checksum, statement _ data)' → o único 'arquivo _ id'.
Row-level idem: `row_hash = sha256(normalized_row_compact)`; carregar novamente não cria novos registros.
Webhooks/API: 'idempotency _ key' provedor + seus rótulos ('exec _ id'), armazenar TTL.
O provedor de duplos é «provider _ txid '+' sequence», e o DLQ _ DUPLICATE, quando o provedor está em divergência.
8) Orquestra e agendamento
Оркестратор: Airflow/Dagster (DAG: `fetch → decrypt → parse → normalize → validate → publish → match`).
SLA/SLO: 'Time-to-Availability (TtA)' desde o aparecimento do arquivo até 'normalize = READY'.
Retrai: backoff exponencial + jitter; limites de tentativa; estatais claras.
Paralelismo e isolamento: pesados OCR/parsing XLSX - em um pool/worker separado com limite CPU/RAM.
DLQ-replay: reprocess periódico quando as regras/muppings são atualizadas.
9) Observabilidade e alertas
Métricas:- Sugestão Sucess%, Parse Sucess% segundo as fontes.
- TtA p50/p95, Throughput (linhas/min).
- DLQ Rate и Aging DLQ p50/p95.
- Schema Drift Invidents (mudar de cabeçalho/formato).
- Duplicate Rate по `provider_txid`.
- `TtA p95 > SLA` → P1.
- 'DLQ Rate> 2%' por hora no provedor → P1.
- 'Schema Drivt detected' → P0 (parar o jogo automático pela fonte).
- 'Duplicate spike' → P2 (verificar provedores/webhooks).
Dashboard: vórtice 'files' raw _ raw _ rows _ normal _ valid _ rows _ matched ', mapa DLQ por razões, TtA-quantili.
10) Correções automáticas e muppings
Header aliases: dicionário com versões (e. g., `Amount`→`amt`, `AMOUNT`→`amt`).
11) Relação com «Pagamento e relatórios PSP»
Camada normalizante - entrada para matching (provider _ txid/merchant _ ref/fuzzy), calculação de diff-taxonomia, revistas automáticas e settlement↔bank. Os campos-chave são 'provider _ txid', 'sequence', 'kind',' amount _ menor ',' value _ data ',' account '.
12) Modelo de armazenamento e tabela
Tabela de arquivos landed:sql
CREATE TABLE landed_files (
file_id TEXT PRIMARY KEY,
provider TEXT,
source_kind TEXT,
file_name TEXT,
file_size BIGINT,
checksum TEXT,
statement_date DATE,
received_at TIMESTAMP WITH TIME ZONE,
version INT,
status TEXT, -- RECEIVED PARSED FAILED error TEXT
);sql
CREATE TABLE psp_norm (
row_id BIGSERIAL PRIMARY KEY,
file_id TEXT REFERENCES landed_files(file_id),
provider TEXT,
source_kind TEXT,
kind TEXT,
payment_id TEXT,
provider_txid TEXT,
merchant_ref TEXT,
sequence INT,
amount_minor BIGINT,
currency CHAR(3),
fee_minor BIGINT,
fx_rate NUMERIC(18,8),
fx_src TEXT,
event_ts TIMESTAMPTZ,
value_date DATE,
account TEXT,
status TEXT,
row_hash TEXT UNIQUE,
repair_flags TEXT[]
);
CREATE INDEX idx_psp_norm_txid ON psp_norm(provider, provider_txid, sequence);13) Pseudocode parsers
CSV/XLSX:python def parse_table(file, spec):
df = load_csv_or_xlsx(file, delimiter=spec.delim, encoding=spec.enc, sheet=spec.sheet)
df = rename_headers(df, spec.header_aliases)
df = clean_amounts(df, thousand=spec.thousand, decimal=spec.decimal, sign_policy=spec.sign)
rows = []
for r in df.itertuples():
rows.append(normalize_row(r, spec))
return rowspython def parse_camt(xml):
root = parse_xml(xml, xsd="camt053.xsd")
for ntry in root.findall('.//Ntry'):
sign = 1 if ntry.findtext('CdtDbtInd') == 'CRDT' else -1 amt = Decimal(ntry.findtext('Amt')) sign
... map to normalized fieldspython def parse_pdf_ocr(pdf):
text = tesseract(pdf, lang="eng", psm=6, whitelist="0123456789.,-;:/A-Za-z")
table = detect_table(text)
return normalize_table(table)14) GDPR/PII e edição de logs
Camuflagem/hash: PAN/email/telefone → 'sha256 + salt', logs sem valores primários.
Política de armazenamento «retentão» por tipo de origem (AML/contabilidade).
Acessíveis ao PII - somente pelo papel; auditoria de leitura/exportação.
15) KPI e alvos (para parsing/ingestão)
Ingestion Success % ≥ 99. 5 %/dia por fonte.
Parse Success % ≥ 99%, DLQ ≤ 1%.
TtA p95 (fayl→normalized) ≤ 15 minutos (CSV/URL), ≤ 60 minutos (PDF/OCR).
Schema Drift Invidents: 0/mês sem alert/fix.
Duplicate Rate по `provider_txid` ≤ 0. 05%.
16) Playbooks incidentes
Schema draft: parar o jogo automático, incluir um parser «macio» com pormenores de coluna ML, preparar alias-patch, expulsar o DLQ-replay.
Bits de DLQ: depuração de arquivos recentes, verificação de codificação/localização/sinal, rebaixamento temporário do rigor de tolerance (com bandeira).
Atrasos de SFTP: mudança para API-polling/webhooks, aumento de retais, comunicação com o provedor.
Spikes duplicates: inclua o aditivo 'row _ hash', o bloco de repetição antes de ser descoberto.
17) Pacote de teste-mala (UAT/Prd-pronto)
1. Idempotidade: repetição do mesmo download → 1 'arquivo _ id', 0 novas linhas.
2. Locais: arquivos com ', '/'/'/espaços → valores corretos.
3. Partial/refund: vários 'sequence' para um 'provider _ txid'.
4. URL XSD: CAMT → 'INVALID' + DLQ.
5. Variações MT940: extensões nacionais → análise correta.
6. PDF→OCR: roça com ruído → extração e regras básicas.
7. Schema draft: novo hader → alias-patch e reaproveitamento de arquivos históricos.
8. Throughput: teste de carga de arquivos N/hora → cumprimento de TtA SLA.
9. Edição PII: logs sem PAN/e-mail, apenas hashies.
18) Folha de cheque de implementação
- Registro de origem: protocolo, programação, SLA, formato, contato.
- Canais seguros (SFTP/PGP/API), Vault para segredos.
- Inhestion Idempotent + checksum + versão.
- Parsers por formatos, dicionário alias, sign/políticas locais.
- Camada normalizada e índices de chave.
- Regras de validação, tolerance, DLQ e replay.
- Orquestrador (DAG), retraí/backoff, pool de recursos.
- Observabilidade: métricas, dashboards, alertas.
- Camuflagem GDPR/PII, auditorias de acesso.
- Malas de teste e regulares schema-drivt drills.
Currículos
A automação do parsing não é «escrever parser», mas construir um circuito industrial, como entrega e criptografia confiáveis, pipas idumpotentes, normalização rigorosa, regras de qualidade e alertas transparentes. Esse caminho transforma quaisquer registros em tabelas previsíveis, com SLA garantido de disponibilidade de dados - fundamentos para dobradinha, tesouraria e relatórios gerenciais.