Versões do formato OFX: especificações, datas e o que mudou

Onde o arquivo declara qual versão ele fala

Antes de ler qualquer lançamento, o programa que importa um extrato lê a declaração do topo do arquivo — e é ali que a versão está escrita. Dois números convivem nessa declaração, e trocá-los é a origem de boa parte das dúvidas.

• OFXHEADER descreve o cabeçalho, não o conteúdo. Só há dois valores em circulação: 100, do cabeçalho em texto puro das versões 1.x, e 200, do cabeçalho em XML que estreou no 2.0. Ele muda quando um programa antigo não conseguiria nem terminar de ler o topo do arquivo.
• VERSION descreve a especificação que rege o conteúdo, num número de três dígitos sem pontos: 102 é 1.0.2, 160 é 1.6, 211 é 2.1.1, 221 é 2.2.1.

A forma muda de uma linhagem para outra. No 1.x, cada campo ocupa uma linha:

OFXHEADER:100 · DATA:OFXSGML · VERSION:102

No 2.x, tudo vira uma instrução de processamento única, depois da declaração XML:

<?OFX OFXHEADER="200" VERSION="211" SECURITY="NONE" OLDFILEUID="NONE" NEWFILEUID="NONE"?>

Vale lembrar de onde essa numeração veio. O OFX nasceu como conversa entre dois programas: o cliente anunciava o maior VERSION que sabia falar, e o servidor respondia na mesma moeda — ecoando aquele valor ou baixando para um que soubesse atender, e usando apenas etiquetas que o outro lado conseguisse processar. O arquivo que você baixa do internet banking é o lado final dessa negociação, gravado em disco. O número que sobrou nele é o resultado do acordo, não uma preferência do banco.

A linhagem 1.x: nove anos de SGML

A primeira especificação amplamente implantada é a 1.0.2, de 30 de maio de 1997. Ela já descrevia quase tudo que se usa hoje — conta corrente, cartão, investimento, pagamentos e o perfil da instituição —, deixando de fora apenas a apresentação de faturas, que chegaria na 1.5.1. Como o dicionário de etiquetas da 1.5.1 continha o da 1.0.2 inteiro, um mesmo servidor conseguia atender aos dois públicos sem manter duas implementações.

A 1.6, de 18 de outubro de 1999, fecha a linhagem: é a última especificação com corpo em SGML. As novidades dela são refinamentos opcionais, que um cliente só deve usar se a instituição declarar suporte no próprio perfil. Uma mudança pequena dessa versão tem efeito direto por aqui: a partir dela o campo ENCODING passou a aceitar UTF-8, onde antes o valor previsto era UNICODE. Num extrato em português, cheio de cedilha e til em nome de fornecedor, é a diferença entre o histórico chegar legível ou virar um amontoado de símbolos.

E então, em 1º de maio de 2006, aconteceu a coisa mais estranha da história do formato: saiu a 1.0.3 — a 1.0.2 acrescida de autenticação multifator, com etiquetas novas no sign-on e no perfil da instituição. Nove anos depois da versão que ela estende, e pulando por cima da 1.6. No mesmo dia foram publicadas a 2.0.3 e a 2.1.1, com exatamente a mesma adição. Não foi coincidência: em 2006 havia três linhas de compatibilidade vivas em produção, e a autenticação em duas etapas tinha de existir em todas, sem obrigar ninguém a migrar de linhagem.

A linhagem 2.x: XML, imagens e OAuth

A 2.0 é a virada de sintaxe: passou a exigir de clientes e servidores conformidade com XML. No conteúdo, trouxe o extrato de plano de aposentadoria 401(k) e, num adendo, os formulários fiscais 1099 e W-2 — dois assuntos que dizem muito sobre onde o padrão era usado.

Daí em diante as revisões são incrementais e cada uma tem um tema claro:

• 2.0.1 — estorno de operação de investimento, lista livre de saldos dentro do extrato e identificação do emissor da fatura no pagamento.
• 2.0.2 — só esclarecimentos de redação.
• 2.1 — empréstimos, download de imagem (o documento digitalizado ligado a um lançamento) e o Automatic 1-Way OFX, para atualização de dados sem interação do usuário.
• 2.0.3 e 2.1.1 — a autenticação multifator de 2006, cada uma sobre a sua base.

Há uma pegadinha útil aqui, e é a própria mantenedora quem a aponta: a 2.0.3 equivale à 2.1.1 sem empréstimo, imagem e fechamento de investimento. Se o assunto que você precisa consultar não é nenhum desses, ela é o documento menor e mais rápido de percorrer — mesmo conteúdo, várias centenas de páginas a menos.

Depois de onze anos parada, a linhagem voltou a andar com a 2.2, de 26 de novembro de 2017, que trocou o modelo de autenticação por token no padrão OAuth, acrescentou elementos pensados para agregadores de dados e reconciliou o schema principal com o fiscal, que haviam se afastado desde 2006. A 2.2.1 subiu o VERSION para 221. E a Banking 2.3, de outubro de 2020, fez o corte que vale para hoje: a parte fiscal saiu do documento principal, que passou a se chamar OFX Banking e deixou de precisar de uma revisão anual só porque a receita americana mudou um formulário.

Extensões: agregação e o imposto de renda americano

Nem tudo que leva o nome OFX é uma versão da especificação principal. Duas famílias de documentos vivem à parte, escritas sobre uma versão-base e sem VERSION próprio.

A especificação de agregação 1.0, de 30 de janeiro de 2005, é a mais antiga delas. Ela foi escrita sobre a 2.0.2 e responde a um problema específico: o de um serviço que acessa contas de muitos usuários em muitas instituições. Para isso criou um registro de autenticação próprio e um jeito de listar credenciais por usuário — além de, por razões de época, um conjunto de mensagens para consultar saldo de programas de pontos.

A extensão fiscal é a que continua em movimento, e explica por que a numeração do OFX parece ter saltado para anos. Desde 2020 ela é versionada por ano-calendário — 2020.0, 2021.0, 2025.0, 2026.0 — para casar com o ano fiscal americano; a de 2021.0 serve também aos anos de 2022 a 2024. O conteúdo é a transmissão eletrônica dos informes de rendimento dos Estados Unidos: 1099 em todas as variações, W-2, os anexos K-1, o 5498. Para quem concilia extrato no Brasil, essa família é irrelevante na prática — mas é ela que responde por que a especificação bancária "parou" na 2.3: o que muda todo ano agora é um documento separado.

Qual versão este site gera — e o que fazer se o seu sistema recusar

O Converter OFX emite uma única versão: OFXHEADER:100, DATA:OFXSGML, VERSION:102. É o dialeto de 1997, e a escolha é deliberada — quem decide não é quem gera o arquivo, e sim quem o importa. O raciocínio completo está no guia sobre o que é o formato OFX.

Na prática, isso vale para qualquer um dos bancos e instituições da lista de conversores: o extrato entra em PDF e sai no mesmo dialeto, seja ele do Itaú ou de uma cooperativa de crédito.

Quando um sistema recusa o arquivo, a versão raramente é a causa. Antes de procurar uma conversão para 2.x, vale eliminar o que de fato costuma estar errado — código do banco, tipo de conta, data fora do período, identificador repetido —, e o caminho para isso é o guia de erros comuns ao importar OFX junto com a conferência antes de importar. Para abrir o arquivo e mexer campo a campo, o editor de OFX mostra o que cada etiqueta significa.

Se o seu software realmente exigir XML e recusar o SGML — o que é raro entre os sistemas brasileiros —, nos avise pelo contato dizendo qual é ele. É o tipo de informação que decide se vale a pena gerar as duas versões.

O que vem dentro de cada pacote

Os arquivos oficiais não são só o texto da especificação: cada pacote traz também a gramática formal contra a qual um arquivo pode ser validado. O que muda de uma linhagem para outra é o formato dessa gramática.

• 1.x — os capítulos vêm em documentos do Word, separados em partes, acompanhados dos DTDs: ofxmain.dtd puxa os demais, e cada assunto tem o seu (ofxbank.dtd, ofxinv.dtd, ofxbill.dtd, ofxprof.dtd, ofxsign.dtd).
• 2.x — a especificação vem em PDF único e a gramática, em XSD. É o que permite validar um arquivo com ferramenta de XML comum, sem escrever um leitor.
• Pacote completo — quando existe, junta o PDF e os schemas num download só.

Um detalhe do pacote da 1.0.3 mostra que essas gramáticas são levadas a sério: ele foi reeditado, sob o mesmo número de versão, apenas para renomear uma etiqueta de autenticação cujo nome no texto não batia com o dos schemas. Um arquivo readme.txt de três linhas documenta a troca. É o tipo de correção que não muda uma vírgula do que o formato faz, e ainda assim vale um relançamento — porque, para quem valida, uma etiqueta com dois nomes é um documento inválido.

Quem mantém o OFX hoje

A especificação foi criada em 1997 por Microsoft, Intuit e CheckFree, e a manutenção passou depois para a Financial Data Exchange (FDX), com um grupo de trabalho dedicado ao OFX e a participação de instituições financeiras e provedores de agregação. Os documentos ficam publicados na área desse grupo — e é para lá que apontam os links desta página.

Duas observações para quem for procurar por conta própria. A primeira: o endereço histórico do padrão, ofx.net, não hospeda mais os arquivos; links antigos para lá não levam a lugar nenhum, o que faz muito resultado de busca envelhecido apontar para o vazio. A segunda: baixar não custa nada e não exige cadastro. A licença publicada em toda especificação é explícita nesse ponto — concede a qualquer parte, em qualquer lugar e sem prazo, o direito de usar o padrão para fabricar, usar e vender produtos que o cumpram, sem pagar royalties. Foi essa cláusula que permitiu ao formato sobreviver às empresas que o criaram.