Referência da API REST

Converta extratos bancários OFX, QFX, QBO e PDF para JSON, Excel ou CSV de forma programática.

Visão geral

A API REST do OFXConverter permite converter arquivos de extrato bancário a partir das suas próprias aplicações. Envie um arquivo e receba as transações extraídas em JSON estruturado ou como um arquivo Excel ou CSV codificado em Base64. A API está disponível para contas em um plano pago.

A API requer um plano premium ativo. Gere sua chave de API na página de perfil do seu painel.

URL base

Todos os endpoints são relativos à seguinte URL base. Todas as requisições devem ser feitas via HTTPS.

https://www.ofxconverter.com/api/v1

Autenticação

Autentique cada requisição enviando sua chave de API no cabeçalho Authorization. Use o valor bruto da chave, sem prefixo Bearer nem esquema.

Authorization: YOUR_API_KEY

Uma requisição sem chave retorna NO_API_KEY; uma chave inválida, ou uma chave de uma conta sem plano premium, retorna UNAUTHORISED. Ambas são enviadas com HTTP 401.

Limites e cotas

O uso é limitado pela cota mensal de conversões do seu plano: Start 500, Pro 1.500, Enterprise 5.000 conversões por mês. O tamanho máximo de arquivo é 10 MB. Os arquivos enviados e gerados são excluídos automaticamente após cerca de 30 minutos.

Plano	Conversões mensais	Tamanho máximo do arquivo
Start	500	10 MB
Pro	1,500	10 MB
Enterprise	5,000	10 MB

Endpoints

Requisições que enviam um arquivo usam multipart/form-data. O campo opcional output seleciona o formato da resposta: csv ou excel retornam o arquivo convertido como uma string Base64, enquanto qualquer outro valor (ou omiti-lo) retorna as transações extraídas em JSON.

post /api/v1/conversion

Converte um arquivo OFX, QFX ou QBO em uma única requisição.

Parâmetros da requisição

Nome	Local	Tipo	Obrigatório	Descrição
`Authorization`	header	string	Sim	Sua chave de API.
`file`	form-data	file	Sim	`.ofx`, `.qfx` ou `.qbo`, até 10 MB.
`output`	form-data	string	Não	`csv`, `excel`, ou omita para JSON.

Exemplo de requisição

curl -X POST "https://www.ofxconverter.com/api/v1/conversion" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.ofx" \
  -F "output=excel"

Exemplo de resposta (excel / csv)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement.ofx",
  "convertedFile": "UEsDBBQABgAIAAAAIQ...=="
}

Exemplo de resposta (json)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement.ofx",
  "convertedFile": {
    "header": {
      "status": "OK",
      "language": "ENG",
      "serverDate": "2024-01-31T00:00:00",
      "bankName": "Bank of Example",
      "currency": "USD",
      "hasInvestiment": false
    },
    "bankAccount": {
      "type": "CHECKING",
      "agencyCode": "0001",
      "bank": { "code": 1, "name": "Bank of Example" },
      "accountCode": "1234567"
    },
    "status": "OK",
    "initialDate": "2024-01-01T00:00:00",
    "finalDate": "2024-01-31T00:00:00",
    "transactions": [
      {
        "type": "DEBIT",
        "date": "2024-01-05T00:00:00",
        "value": -42.5,
        "id": "202401050001",
        "uniqueID": "202401050001",
        "description": "Coffee Shop",
        "checksum": 849302145,
        "units": null,
        "price": null,
        "comission": null,
        "secName": null,
        "ticker": null
      }
    ]
  }
}

post /api/v1/upload

Armazena um arquivo para conversão posterior. Retorna um fileID que você pode passar para GET /api/v1/download. Nenhuma conversão é realizada nesta etapa.

Parâmetros da requisição

Nome	Local	Tipo	Obrigatório	Descrição
`Authorization`	header	string	Sim	Sua chave de API.
`file`	form-data	file	Sim	`.ofx`, `.qfx` ou `.qbo`, até 10 MB.

Exemplo de requisição

curl -X POST "https://www.ofxconverter.com/api/v1/upload" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.ofx"

Exemplo de resposta

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement"
}

get /api/v1/download

Converte um arquivo armazenado anteriormente com POST /api/v1/upload. O arquivo deve pertencer à conta autenticada.

Parâmetros da requisição

Nome	Local	Tipo	Obrigatório	Descrição
`Authorization`	header	string	Sim	Sua chave de API.
`fileID`	query	string (GUID)	Sim	ID retornado por `/upload`.
`output`	query	string	Não	`csv`, `excel`, ou omita para JSON.

Exemplo de requisição

curl "https://www.ofxconverter.com/api/v1/download?fileID=3f2504e0-4f89-41d3-9a0c-0305e82c3301&output=csv" \
  -H "Authorization: YOUR_API_KEY"

Exemplo de resposta

O corpo da resposta tem o mesmo formato de POST /api/v1/conversion. Além dos erros de autenticação, download retorna NO_FILE_ID quando o fileID está ausente e FILE_NOT_FOUND quando não existe arquivo correspondente para sua conta (ambos com HTTP 401).

post /api/v1/pdf/conversion beta

Converte um extrato bancário em PDF. Extratos de bancos suportados são analisados diretamente; os demais utilizam OCR e extração por IA, portanto os resultados podem variar. Este endpoint é experimental e pode mudar.

Parâmetros da requisição

Nome	Local	Tipo	Obrigatório	Descrição
`Authorization`	header	string	Sim	Sua chave de API.
`file`	form-data	file	Sim	`.pdf`, até 10 MB.
`output`	form-data	string	Não	`csv`, `excel`, ou omita para JSON.

Exemplo de requisição

curl -X POST "https://www.ofxconverter.com/api/v1/pdf/conversion" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.pdf"

Exemplo de resposta (json)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "pdf",
  "filename": "statement.pdf",
  "convertedFile": {
    "transactions": [
      {
        "date": "2024-01-05T00:00:00",
        "value": -42.5,
        "description": "Coffee Shop",
        "type": "DEBIT"
      }
    ]
  }
}

Esquema de resposta

Para saída em JSON, os endpoints de conversão OFX e download retornam o extrato extraído em convertedFile com a seguinte estrutura.

Campo	Tipo	Descrição
`header.bankName`	string	Nome do banco a partir do extrato.
`header.currency`	string	Moeda do extrato (ex.: `USD`).
`header.serverDate`	datetime	Data reportada pelo servidor do banco.
`header.hasInvestiment`	boolean	`true` quando o extrato contém transações de investimento.
`bankAccount.type`	string	Tipo de conta (ex.: `CHECKING`).
`bankAccount.bank.code`	integer	Código do banco.
`bankAccount.accountCode`	string	Número da conta.
`initialDate` / `finalDate`	datetime	Período do extrato.
`transactions[]`	array	Lista de transações (veja abaixo).
`transactions[].date`	datetime	Data da transação.
`transactions[].value`	number	Valor (negativo para débitos).
`transactions[].type`	string	Tipo da transação.
`transactions[].description`	string	Descrição da transação.
`transactions[].id`	string	Identificador da transação no arquivo.
`transactions[].checksum`	integer	Checksum usado para detectar duplicatas.
`transactions[].units` / `price` / `comission`	number	Campos de investimento; `null` para transações comuns.
`transactions[].secName` / `ticker`	string	Nome do ativo e ticker para transações de investimento.

O endpoint de PDF retorna um formato mais simples: convertedFile.transactions[] com date, value, description e type.

Respostas de erro

Erros retornam um corpo JSON com "error": true e um código message. Erros relacionados a arquivo também repetem fileID, extension e filename.

{
  "error": true,
  "message": "FILE_NOT_SUPPORTED",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "txt",
  "filename": "statement.txt"
}

Mensagem	Status HTTP	Significado
`NO_API_KEY`	401	O cabeçalho `Authorization` está ausente.
`UNAUTHORISED`	401	Chave inválida, ou a conta não é premium.
`NO_FILE_ID`	401	`download` foi chamado sem um `fileID`.
`FILE_NOT_FOUND`	401	Nenhum arquivo com esse `fileID` existe para sua conta.
`FILE_NOT_UPLOADED`	400	Nenhum arquivo foi incluído na requisição.
`FILE_NOT_SUPPORTED`	400	A extensão do arquivo não é aceita por este endpoint.
`FILE_TOO_BIG`	400	O arquivo excede o limite de 10 MB.
`BAD_FILE_FORMAT`	400	O arquivo não pôde ser processado (ex.: um arquivo OFX inválido).
`SERVER_ERROR`	400	Ocorreu um erro inesperado ao processar o arquivo.