Utilize JSON quando precisar de dados de transações num script ou pipeline de dados, mantendo os metadados de conta do extrato. A nossa transferência em JSON é um único objeto que contém metadados e um array de transações. Não é uma lista simples de linhas nem um ficheiro JSON delimitado por linhas.
Descarregar o extrato estruturado
- Abra a Ferramenta de PDF para JSON e carregue um PDF legível e desbloqueado de até 25 MB.
- Selecione Converter o meu extrato e aguarde pelo processamento.
- Abra Mais formatos e selecione JSON sob Spreadsheet+.
- Guarde o ficheiro e compare uma amostra das respetivas datas e montantes com o PDF original.
Este guia aborda a leitura de um ficheiro descarregado. Uma exportação em JSON não estabelece por si só uma integração de API pública nem um fluxo de trabalho de carregamento automatizado.
Compreender a estrutura do objeto
| Campo | Formato | Significado |
|---|---|---|
| bankName, accountHolder, accountNumber | String ou null | Metadados de conta extraídos |
| currency | String ou null | Moeda ao nível do extrato |
| statementPeriod | Objeto com from e to | Strings de data ou null para cada limite |
| openingBalance, closingBalance | Número ou null | Saldos do extrato extraídos |
| transactions | Array | Linhas contendo date, description, debit, credit, balance |
| pageCount | Número | Contagem de páginas do PDF registada durante a conversão |
| validated | Booleano | Resultado da verificação de saldo da aplicação |
| parserUsed | String | Identificador do fornecedor de extração |
Em cada transação, date e description são strings; debit, credit e balance são números ou null. O parser é instruído a fornecer datas ISO, mas a sua integração deve ainda assim validá-las. Os números de conta são identificadores: mantenha-os como strings para que os zeros à esquerda sejam preservados. Não existe nenhum campo de categoria ou de ID original de transação bancária nesta exportação.
Ler o array de transações em Python
Guarde a sua transferência como statement.json para este exemplo. O módulo json de Python lê o objeto externo; selecione o respetivo campo transactions para obter as linhas. A utilização de Decimal para números fracionários evita adicionar arredondamentos de vírgula flutuante binária durante os seus próprios cálculos. Consulte a documentação de JSON em Python para json.load e parse_float.
python
import json
from decimal import Decimal
with open("statement.json", encoding="utf-8") as source:
statement = json.load(source, parse_float=Decimal)
rows = statement["transactions"]
if not isinstance(rows, list):
raise ValueError("Expected a transactions array")
print("Balance check:", statement["validated"])
for row in rows:
print(row["date"], row["description"], row["debit"], row["credit"])O exemplo lê e apresenta dados; não submete transações em lado nenhum. Se mais tarde utilizar um dataframe, construa-o a partir do array de transações e armazene os metadados do extrato em separado. Ler o objeto inteiro como se fosse uma tabela plana de transações mistura campos com estruturas diferentes.
Interpretar null e validated com cuidado
Null significa que um valor estava ausente ou indisponível. Não é permutável com zero. Um débito em falta é normal para uma linha de crédito, mas um saldo inicial em falta exige uma decisão diferente. Verifique estes casos explicitamente antes de calcular totais ou fazer importações.
O sinalizador validated verifica se existem transações e ambos os saldos do extrato, e depois compara o saldo inicial mais créditos menos débitos com o saldo final dentro de uma tolerância de 0.01. Não verifica cada descrição, data, identificador de conta ou saldo corrente. Um valor falso pode significar saldos em falta ou uma discrepância; um valor verdadeiro não é garantia de que todas as linhas estejam corretas.
Preparar dados para um fluxo de trabalho repetível
Verifique as chaves e tipos esperados, a validade das datas, a moeda do extrato e a conta antes de carregar as linhas. Mantenha uma referência do ficheiro de origem com os registos importados. A exportação não tem IDs de linha persistentes emitidos pelo banco, pelo que deve conceber a sua própria análise de duplicados em vez de presumir que a ordem das linhas é exclusiva entre ficheiros.
Para categorias, descarregue o livro de cálculo categorizado em separado. Para um ficheiro simples e sem formatação, siga o guia de CSV.