API de conversão de extratos bancários
Envie o PDF do extrato e receba, na mesma resposta, os lançamentos já estruturados em JSON e o arquivo pronto em OFX, Excel ou CSV.
- mais de 200 layouts suportados
- Detecção automática do banco
- OFX, Excel e CSV
Por que integrar com o OFX Fácil
A mesma leitura de extrato que atende milhares de contadores no site, disponível como uma chamada HTTP no seu sistema.
Integração em uma requisição
Um POST com o PDF, e a resposta já traz os lançamentos e o arquivo convertido em base64. Nada de fila, polling ou webhook para implementar do seu lado.
Cobertura dos bancos brasileiros
Suportamos mais de 200 layouts de extrato, dos grandes bancos às fintechs, contas digitais e cooperativas. A lista cresce a cada layout novo: consulte o endpoint de bancos em vez de fixá-la no seu código.
Detecção automática do layout
Não sabe qual banco emitiu o arquivo? Omita o parser_id: identificamos o layout e dizemos, no campo detection, como chegamos nele.
JSON padronizado
O mesmo formato de resposta para todos os bancos: data, descrição como impressa, valor com sinal e tipo C/D, mais os totais de crédito, débito e saldo líquido já somados.
Validação tudo ou nada
Se algum lançamento não passar na validação, recusamos a conversão inteira. O arquivo que devolvemos vai direto para a sua contabilidade, resultado parcial em silêncio não é uma opção.
Sem retenção e sem cobrança dupla
Autenticação por chave, arquivos descartados após o processamento e conformidade com a LGPD. Reenviar os mesmos bytes devolve o resultado já processado, sem nova cobrança.
Endpoints disponíveis
Clique em cada endpoint para expandir os detalhes
Abrir a referência interativa completa →GET /api/v1/banks Listar os bancos suportados
Devolve o catálogo completo de layouts que sabemos ler, com o nome do banco e o código FEBRABAN. É daqui que sai o parser_id usado na leitura manual, a lista cresce a cada layout novo, então consulte o endpoint em vez de fixá-la no seu código.
GET /api/v1/banks
Authorization: Bearer ofx_live_SUACHAVE[
{ "parser_id": "6", "bank_name": "Itaú", "bank_code": "341" },
{ "parser_id": "13", "bank_name": "Banco do Brasil", "bank_code": "001" },
{ "parser_id": "27", "bank_name": "Sicoob", "bank_code": "756" }
]curl https://www.ofxfacil.com.br/api/v1/banks \
-H "Authorization: Bearer ofx_live_SUACHAVE"POST /api/v1/convert Converter um extrato em PDF
Recebe o PDF em multipart/form-data e devolve, na mesma resposta, os lançamentos estruturados, os totais já somados e o arquivo convertido em base64. O parser_id é opcional: sem ele identificamos o banco automaticamente e informamos como chegamos nele no campo detection.
| Campo | Obrigatório | Descrição |
|---|---|---|
| file | sim | O extrato em PDF, com camada de texto. |
| output | sim | Formato do arquivo devolvido: ofx, excel ou csv. |
| parser_id | não | Força um layout específico. Omitido, o banco é detectado automaticamente. |
| password | não | Senha do PDF, quando o documento for protegido. |
POST /api/v1/convert
Authorization: Bearer ofx_live_SUACHAVE
Content-Type: multipart/form-data
file: extrato.pdf
output: ofx
parser_id: 13 (opcional)
password: (opcional){
"parser_id": "13",
"bank_code": "001",
"bank_name": "Banco do Brasil",
"detection": "detector",
"agency": "1234-5",
"account": "12345-6",
"total_transactions": 42,
"credits_count": 18,
"credits_amount": 15320.55,
"debits_count": 24,
"debits_amount": 9876.10,
"net_total": 5444.45,
"dropped_rows": 0,
"output": "ofx",
"filename": "extrato.ofx",
"file": "T0ZYSEVBREVSOjEwMApEQVRBOk9GWFNHTUwK...",
"transactions": [
{ "date": "01/08/2026", "description": "PIX RECEBIDO", "amount": 1200.50, "type": "C" },
{ "date": "02/08/2026", "description": "TARIFA MENSALIDADE", "amount": -49.90, "type": "D" }
]
}curl https://www.ofxfacil.com.br/api/v1/convert \
-H "Authorization: Bearer ofx_live_SUACHAVE" \
-F "[email protected]" \
-F "output=ofx"O campo file vem em base64. Para gravar o arquivo direto do terminal:
curl -s https://www.ofxfacil.com.br/api/v1/convert \
-H "Authorization: Bearer ofx_live_SUACHAVE" \
-F "[email protected]" -F "output=ofx" \
| python3 -c "import sys,json,base64; r=json.load(sys.stdin); \
open(r['filename'],'wb').write(base64.b64decode(r['file']))"Autenticação
Toda requisição precisa da sua chave de API, em um dos dois formatos abaixo.
Authorization: Bearer ofx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: ofx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxChaves ofx_test_… são de sandbox; ofx_live_… são de produção.
Limites
| Entrada aceita | PDF com camada de texto (o formato em que os bancos publicam extratos). |
|---|---|
| Formatos de saída | OFX, Excel (.xlsx) e CSV. |
| Tamanho do arquivo | 25 MiB por requisição, acima disso a resposta é 413. |
| Lançamentos por conversão | 20.000. |
| Requisições por minuto | Definido no seu contrato. Ao estourar, 429 com Retry-After e os headers X-RateLimit-*. |
Erros
Todo erro usa o mesmo envelope, com um code estável. Programe contra o code, nunca contra a message, ela pode mudar. O request_id é o que citar no suporte.
{
"error": {
"code": "layout_not_recognized",
"message": "Could not identify the statement layout.",
"request_id": "01J8Z2K7Q5"
}
}| Código | HTTP | Quando acontece |
|---|---|---|
| invalid_api_key | 401 | Chave ausente, malformada ou revogada. |
| insufficient_credits | 402 | Acabaram as conversões do seu plano. |
| file_too_large | 413 | PDF acima do limite de upload. |
| scanned_pdf | 422 | O PDF é imagem, sem camada de texto. |
| layout_not_recognized | 422 | Não identificamos o layout, ou as linhas não passaram na validação. |
| unsupported_file_type | 422 | A entrada não é um PDF. |
| invalid_pdf_password | 422 | O PDF é protegido e a senha enviada não abriu. |
| no_transactions | 422 | O extrato não tem nenhum lançamento. |
| duplicate_request | 409 | Um arquivo idêntico já está sendo convertido para a sua conta. |
| rate_limited | 429 | Requisições por minuto excedidas. Respeite o header Retry-After. |
Plano sob medida
Não trabalhamos com uma tabela única: o preço acompanha o seu volume mensal, o formato de cobrança que faz sentido para o seu financeiro e o nível de atendimento que a sua operação precisa. Conte para a gente o que você quer integrar e voltamos com uma proposta.
Perguntas frequentes
E se o extrato for um PDF escaneado?
A resposta é o erro scanned_pdf, e essa requisição não é cobrada. A API converte apenas PDF com camada de texto, é o formato em que os bancos publicam extratos, e é o que permite a conversão ser determinística, sem nenhuma etapa de adivinhação. Documentos escaneados passam por etapas de leitura adicionais no site, que tem tela de revisão humana.
Vocês guardam os arquivos que eu enviar?
Não. O PDF é processado e descartado; não mantemos cópia depois da resposta. Todo o tráfego é TLS e estamos em conformidade com a LGPD.
Como funciona a cobrança?
Cada conversão bem-sucedida conta uma unidade no seu plano. Conversão que falha não é cobrada, e o mesmo arquivo nunca é cobrado duas vezes: reenviar bytes idênticos devolve o resultado já processado, sem reprocessar, e você pode pedir outro formato de saída nesse reenvio.
Existe ambiente de teste?
Sim. Chaves ofx_test_… são de sandbox e chaves ofx_live_… são de produção. A chave nunca vai na query string, e nunca fica armazenada por nós em texto claro.
O que acontece se eu mandar o banco errado no parser_id?
Se aquele parser não conseguir ler o documento, a resposta é layout_not_recognized, nunca uma conversão silenciosa com outro banco. Na dúvida, omita o parser_id: a detecção automática identifica o layout e informa como chegou nele no campo detection.
Ficou alguma dúvida? Fale com a gente , ou veja as dúvidas gerais do OFX Fácil.