O que é o formato OFX

Se você já importou extrato num sistema contábil, provavelmente pediu um arquivo OFX ao banco sem nunca ter aberto um. Ele é um arquivo de texto — dá para abrir no Bloco de Notas — e o que está lá dentro explica boa parte dos problemas de importação que aparecem no dia a dia: acentuação embaralhada, lançamento com o sinal trocado, Pix sem o nome de quem pagou.

Vale a pena entender o formato, porque quase todo erro de importação é um erro de detalhe do arquivo, não do sistema que o recebe.

OFX quer dizer Open Financial Exchange

É um padrão aberto para troca de dados financeiros, criado nos anos 1990 por Microsoft, Intuit e CheckFree — na época em que gerenciadores financeiros pessoais como o Quicken e o Microsoft Money precisavam falar com bancos, e cada banco falava um dialeto diferente. A primeira especificação é de 1997.

O objetivo era ter uma língua comum: um arquivo que o banco emite e qualquer software financeiro consegue ler, sem acordo bilateral entre os dois. Quase três décadas depois, é isso que o formato ainda faz — só que o consumidor mudou. No Brasil, quem lê OFX hoje é o sistema contábil: Domínio, Conta Azul, Omie, Bling e os demais esperam esse arquivo na tela de importação de extrato.

Por que o seu sistema pede justamente ele

Porque o OFX descreve cada lançamento de forma estruturada — data, valor, se é débito ou crédito, o histórico, o documento — em vez de desenhar uma tabela para alguém ler. Um PDF de extrato é feito para o olho humano; um OFX é feito para o software.

A diferença prática é a digitação. Com o OFX, o movimento do mês entra na contabilidade em um clique. Sem ele, alguém transcreve linha por linha, e a conciliação passa a depender de não ter havido erro de digitação em nenhuma delas.

O que existe dentro do arquivo

Um OFX tem duas partes: um cabeçalho de configuração e um corpo com os dados.

O cabeçalho são linhas simples de CHAVE:VALOR, antes de qualquer tag:

OFXHEADER:100
DATA:OFXSGML
VERSION:102
SECURITY:NONE
ENCODING:USASCII
CHARSET:1252
COMPRESSION:NONE
OLDFILEUID:NONE
NEWFILEUID:NONE

Três dessas linhas importam de verdade:

• VERSION:102 — a versão do formato. 102 é o OFX 1.0.2, e é o que praticamente todo banco brasileiro emite.
• DATA:OFXSGML — declara que o corpo é SGML, não XML. É a linha que causa mais confusão, e a próxima seção é inteira sobre ela.
• CHARSET:1252 — a codificação dos caracteres. É onde a acentuação se perde quando o arquivo é gravado errado.

Depois do cabeçalho vem o corpo, aberto por <OFX>. Dentro dele há o bloco de identificação da instituição, o da conta, e a lista de lançamentos. Cada lançamento é um <STMTTRN>:

<STMTTRN>
<TRNTYPE>DEBIT</TRNTYPE>
<DTPOSTED>20260302120000[-3:BRT]</DTPOSTED>
<TRNAMT>-1740.84</TRNAMT>
<FITID>202603021740840012</FITID>
<MEMO>PIX ENVIADO - FORNECEDOR EXEMPLO LTDA</MEMO>
</STMTTRN>

Campo por campo:

• TRNTYPE — DEBIT ou CREDIT, entre outros tipos previstos no padrão.
• DTPOSTED — a data, no formato AAAAMMDD, opcionalmente seguida de hora e fuso. Em extrato bancário só a data importa; a hora é ruído, e o fuso declarado varia tanto de um banco para outro que não dá para confiar nele.
• TRNAMT — o valor, com sinal. Negativo é saída.
• FITID — um identificador único do lançamento dentro daquela conta. É o que permite ao sistema perceber que você está importando de novo um período já importado, em vez de duplicar tudo.
• MEMO — o histórico.

E há dois campos opcionais que valem menção: NAME, com o nome do favorecido, e CHECKNUM, com o número do documento.

No fim do extrato aparece o saldo, dentro de <LEDGERBAL>:

<LEDGERBAL>
<BALAMT>17290.55</BALAMT>
<DTASOF>20260331120000[-3:BRT]</DTASOF>
</LEDGERBAL>

OFX 1.x não é XML — e isso tem consequência prática

Olhando o trecho acima, a impressão é de estar vendo XML. Não é.

O OFX 1.x é SGML, e a diferença que importa é uma só: as tags de valor não são fechadas. Um arquivo emitido por banco costuma trazer:

<TRNAMT>-1740.84
<FITID>202603021740840012

Sem </TRNAMT>, sem </FITID>. O valor termina na quebra de linha. Só as tags de agrupamento — <STMTTRN>, <BANKTRANLIST>, <OFX> — são fechadas.

Para um parser de XML isso é arquivo malformado, e a reação dele é rejeitar o documento inteiro. É a origem de uma classe inteira de bugs em quem tenta ler OFX com uma biblioteca de XML e conclui que “o arquivo do banco está corrompido”. Não está: está no formato que o padrão especifica.

O OFX 2.x é XML de verdade, com todas as tags fechadas e prólogo <?xml ... ?>. Existe desde o início dos anos 2000 e é o que se usaria hoje se a escolha fosse nova. Só que ela não é: os bancos brasileiros exportam quase sempre 1.0.2, e um leitor que só entenda 2.x não serve para praticamente nenhum extrato emitido no país.

A saída, na prática, é ler o arquivo por varredura de tags em vez de por árvore de documento. É menos elegante e funciona nas duas versões — que é exatamente o que se precisa aqui.

A codificação: Windows-1252, nunca UTF-8

Este é o detalhe que mais quebra importação no Brasil, e o mais fácil de errar.

O cabeçalho declara CHARSET:1252, ou seja: os bytes do arquivo estão em Windows-1252 (o “ANSI” do Windows). O Domínio lê o arquivo assumindo isso. Se o OFX for gravado em UTF-8 — o padrão de qualquer ferramenta moderna — cada caractere acentuado ocupa dois bytes, e o importador, lendo byte a byte como cp1252, mostra dois caracteres no lugar de um.

O resultado aparece na tela de lançamentos: “TRANSFERÊNCIA” vira “TRANSFERÊNCIA”, cedilha vira ç, til vira ã. O arquivo importa — o que é pior do que falhar —, e a contabilidade fica com o histórico ilegível em todos os lançamentos que tinham acento. Ou seja, quase todos.

Há uma armadilha a mais para quem vai corrigir isso: latin1 não é a mesma coisa que Windows-1252. Latin1 é o ISO-8859-1, e os dois divergem justamente na faixa de bytes 0x80–0x9F, onde o cp1252 coloca a pontuação tipográfica — travessão, aspas curvas, símbolo do euro, bolinha de marcador. Gravar como latin1 converte esses caracteres em caracteres de controle, e o estrago é mais discreto que o do UTF-8, porque só aparece nos lançamentos que trazem um travessão no histórico.

Na leitura vale a regra inversa: um OFX que chegou do banco deve ser decodificado como Windows-1252, a menos que o próprio cabeçalho declare UTF-8. Ler um arquivo cp1252 como se fosse UTF-8 corrompe todo acento do histórico na direção contrária.

Onde o banco não segue o padrão

O padrão diz uma coisa; o arquivo que chega diz outra. Três divergências conhecidas, todas encontradas em arquivos reais:

Vírgula no lugar do ponto decimal. A especificação manda ponto: -1740.84. O Bradesco é o caso conhecido de banco que grava 1740,84. Um leitor que aceite só o ponto rejeita um arquivo que o próprio banco emitiu.

TRNTYPE contradizendo o sinal. Há arquivos com <TRNTYPE>CREDIT num lançamento de valor negativo. Quando os dois discordam, o sinal do TRNAMT é a fonte da verdade — ele é inequívoco, e o TRNTYPE é o campo que se erra ao gerar.

O nome do favorecido que some. Muitos importadores, o Domínio inclusive, exibem apenas o MEMO na tela de lançamentos e ignoram o NAME. Quando o banco coloca o histórico genérico no MEMO (“PIX RECEBIDO - OUTRA IF”) e o nome de quem pagou só no NAME, o lançamento chega à contabilidade sem identificar a contraparte. Por isso, ao gerar OFX, vale anexar o nome ao próprio memo em vez de confiar que alguém vai ler o campo certo.

OFX, OFC, CNAB: não são a mesma coisa

Três siglas que aparecem juntas na tela de exportação de alguns bancos e resolvem problemas diferentes:

• OFX é o extrato para gerenciador financeiro e sistema contábil — o assunto deste texto.
• OFC é o formato anterior da Microsoft, que o OFX veio substituir. Alguns bancos ainda o oferecem ao lado do OFX; a Caixa é um deles.
• CNAB não é extrato. É o arquivo de retorno de cobrança e pagamento, com layout de posição fixa, e serve para conciliar títulos — não para importar o movimento da conta.

Escolher o arquivo errado na tela do banco é uma das causas mais banais de “a importação não funciona”.

E quando o banco não entrega um OFX que sirva

Acontece mais do que se imagina, e nem sempre por ausência do recurso. O período exportável é curto demais para o fechamento; o arquivo é recusado na importação por um requisito do sistema contábil; a conta e a maquininha vêm em relatórios separados e só um deles sai em OFX; a cooperativa não liberou a opção na tela.

Em todos esses casos o PDF costuma ser o documento mais completo que o banco entrega. Ele tem todos os lançamentos, o saldo anterior e o saldo final impressos — e, com o saldo impresso, dá para provar aritmeticamente que a conversão não perdeu nada.

É disso que trata a página sobre converter PDF para OFX, e a lista de instituições reconhecidas mostra em quais delas o layout já é identificado automaticamente.