Documentação da API do BankConv
A API REST do BankConv converte extratos bancários em PDF em dados estruturados. Envie um PDF com a chave de API da sua equipe, consulte o status até a conversão terminar e obtenha as transações como linhas JSON limpas, ou baixe CSV, OFX, QFX, QBO ou Xero CSV.
URL base: https://bankconv.com/api/v1
Especificação OpenAPI: openapi.json
Autenticação
Toda requisição precisa de uma chave de API da equipe, enviada como token Bearer:
Authorization: Bearer sk_live_your_api_keyAs chaves de API pertencem a uma equipe. Crie-as no aplicativo do BankConv, nas configurações da sua equipe. A chave completa aparece uma única vez, quando é criada: guarde-a em um lugar seguro. As conversões pela API usam as páginas do plano da sua equipe; veja a cobrança.
Início rápido
1. Enviar um extrato
curl -X POST https://bankconv.com/api/v1/conversions \
-H "Authorization: Bearer sk_live_your_api_key" \
-F "[email protected]"A API responde 201 Created com a nova conversão:
{
"data": {
"id": "9a8b7c6d-…",
"status": "processing",
"pages_count": 3,
"created_at": "2026-10-11T12:00:00Z",
"input": {
"filename": "statement.pdf",
"pages_count": 3
}
}
}2. Consultar o status
curl https://bankconv.com/api/v1/conversions/9a8b7c6d-… \
-H "Authorization: Bearer sk_live_your_api_key"Repita a cada poucos segundos até que status seja completed ou failed.
3. Baixar os resultados
# JSON (default)
curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download \
-H "Authorization: Bearer sk_live_your_api_key"
# CSV, with matching tables merged into one transaction list
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=csv&view=merged" \
-H "Authorization: Bearer sk_live_your_api_key" \
-o statement.csv
# QBO for QuickBooks Desktop (also ofx, qfx or xero)
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=qbo" \
-H "Authorization: Bearer sk_live_your_api_key" \
-o statement.qboEndpoints
Todos os caminhos são relativos a https://bankconv.com/api/v1.
| Método | Caminho | O que faz |
|---|---|---|
POST | /conversions | Enviar um PDF e iniciar uma conversão |
GET | /conversions | Listar as conversões da sua equipe (paginado) |
GET | /conversions/{id} | Obter o status de uma conversão |
GET | /conversions/{id}/transactions | Obter as transações como linhas JSON limpas |
GET | /conversions/{id}/download | Baixar em JSON, CSV, OFX, QFX, QBO ou Xero CSV |
DELETE | /conversions/{id} | Excluir uma conversão |
GET | /credits | Consultar suas páginas disponíveis |
GET | /credits/usage | Páginas usadas no período atual |
Criar uma conversão
POST /conversions recebe um corpo multipart/form-data.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
file | file | Sim | O extrato em PDF, até 30 MB |
password | string | Não | A senha de um PDF protegido, para abrir o arquivo. |
Para um extrato protegido por senha, envie a senha junto com o arquivo:
curl -X POST https://bankconv.com/api/v1/conversions \
-H "Authorization: Bearer sk_live_your_api_key" \
-F "[email protected]" \
-F "password=the_pdf_password"Se você não sabe a senha, as páginas dos bancos (em inglês) indicam o formato que cada banco usa, quando conseguimos confirmá-lo.
Listar conversões
GET /conversions retorna as conversões da sua equipe, da mais recente para a mais antiga.
| Parâmetro | Padrão | Descrição |
|---|---|---|
page | 1 | Número da página |
per_page | 15 | Resultados por página, até 100 |
status | nenhum | Filtrar por pending, processing, completed ou failed |
sort | -created_at | Campo de ordenação; um - no início ordena de forma decrescente |
Obter as transações
GET /conversions/{id}/transactions retorna as transações do extrato prontas para usar: datas reais, um único valor com sinal (créditos positivos, débitos negativos), o saldo acumulado, sem o saldo inicial nem as linhas de totais. Os valores são strings decimais na moeda do extrato.
curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/transactions \
-H "Authorization: Bearer sk_live_your_api_key"{
"data": {
"tables": "0:1,1:0",
"institution": "JPMorgan Chase Bank, N.A.",
"country": "US",
"account_type": "checking",
"account_number": "XXXX4821",
"currency": "USD",
"period": { "start": "2026-01-03", "end": "2026-01-31" },
"transaction_count": 42,
"transactions": [
{ "date": "2026-01-03", "description": "Payroll deposit", "reference": null, "amount": "3200.00", "balance": "4450.00" },
{ "date": "2026-01-04", "description": "Coffee shop", "reference": null, "amount": "-4.80", "balance": "4445.20" }
],
"warnings": []
}
}O BankConv escolhe o grupo de tabelas que rende mais transações e informa qual em tables (índices de página e de tabela, a partir de 0). Para ler outras tabelas, passe-as, por exemplo ?tables=2:0,3:0. Se elas não puderem ser lidas como transações, como um resumo da conta, a resposta é 422 unreadable_statement com o motivo.
Baixar os resultados
GET /conversions/{id}/download funciona quando a conversão está em completed.
| Parâmetro | Padrão | Descrição |
|---|---|---|
format | json | json, csv, ofx, qfx (Quicken), qbo (QuickBooks Web Connect) ou xero (Xero CSV) |
view | raw | Para CSV: raw mantém cada tabela como foi extraída, página por página; merged junta as tabelas com as mesmas colunas em uma única lista |
tables | escolhidas automaticamente | Para OFX, QFX, QBO e Xero: as tabelas usadas, como em Obter as transações |
A resposta JSON contém cada página extraída com seus blocos (tabelas e texto), para que você faça o mapeamento das colunas. Para linhas prontas para usar, prefira Obter as transações.
Os downloads OFX, QFX, QBO e Xero trazem os avisos que houver, como um banco que não está na lista do QuickBooks, em um array JSON no cabeçalho X-BankConv-Warnings.
Créditos e consumo
GET /credits retorna suas páginas disponíveis no período de cobrança atual:
{
"data": {
"total": 1000,
"remaining": 842,
"bonus": 50,
"bonusRemaining": 50
}
}GET /credits/usage retorna as páginas usadas desde o início do período:
{
"data": {
"period_start": "2026-09-11",
"period_end": "2026-10-11",
"pages_used": 158
}
}Respostas e erros
As respostas bem-sucedidas trazem o resultado sob a chave data. As listas acrescentam as informações de paginação:
{
"data": [ … ],
"links": { … },
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 15,
"total": 72
}
}Todos os erros têm o mesmo formato:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. You have 2 remaining but need 5.",
"status": 422
}
}| Código | Status | Significado |
|---|---|---|
unauthenticated | 401 | A chave de API está ausente ou não é válida |
not_found | 404 | A conversão não existe ou pertence a outra equipe |
gone | 410 | A conversão foi excluída de acordo com o seu período de retenção |
validation_error | 422 | Parâmetros inválidos, por exemplo, falta o arquivo ou a senha está errada |
insufficient_credits | 422 | Não há páginas suficientes para o documento inteiro |
payment_failed | 402 | O último pagamento da assinatura falhou e o plano está suspenso; billing_url abre o portal de cobrança. As conversões recusadas nesse meio-tempo são processadas quando o pagamento é feito, se isso acontecer dentro do seu período de retenção de dados |
not_ready | 422 | A conversão ainda está em andamento, ou os dados do extrato ainda estão sendo lidos (somente transações e formatos contábeis, até cinco minutos depois do fim) |
unreadable_statement | 422 | As tabelas não podem ser lidas como transações; failure_class indica o motivo |
rate_limited | 429 | Requisições demais; aguarde os segundos indicados em Retry-After |
Limites de requisições
Cada chave de API pode fazer 60 requisições por minuto. As respostas trazem os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining, e uma resposta 429 traz Retry-After com os segundos que você deve aguardar.
Cobrança
Cada página de um PDF convertido usa uma das páginas mensais do seu plano. Uma conversão precisa de páginas suficientes para o documento inteiro; não há conversões parciais, e a requisição retorna insufficient_credits no lugar. Se o pagamento da sua assinatura falhou, a requisição retorna payment_failed até você atualizar o cartão.
| Plano | Páginas por mês | Preço |
|---|---|---|
| Starter | 500 | R$ 159/mês, ou R$ 99/mês com cobrança anual |
| Professional | 1.000 | R$ 269/mês, ou R$ 159/mês com cobrança anual |
| Business | 5.000 | R$ 429/mês, ou R$ 269/mês com cobrança anual |
Compare os planos na página de preços. Preços em reais (BRL).
Retenção de dados
As conversões são excluídas automaticamente de acordo com o período de retenção da sua equipe: 24, 48 ou 72 horas, 24 por padrão. Depois disso, as requisições de download retornam 410 Gone. Baixe o que precisar antes, ou exclua você mesmo uma conversão com DELETE /conversions/{id}. Veja segurança e tratamento de dados.