Ir para o conteúdo

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_key

As 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.qbo

Endpoints

Todos os caminhos são relativos a https://bankconv.com/api/v1.

MétodoCaminhoO que faz
POST/conversionsEnviar um PDF e iniciar uma conversão
GET/conversionsListar as conversões da sua equipe (paginado)
GET/conversions/{id}Obter o status de uma conversão
GET/conversions/{id}/transactionsObter as transações como linhas JSON limpas
GET/conversions/{id}/downloadBaixar em JSON, CSV, OFX, QFX, QBO ou Xero CSV
DELETE/conversions/{id}Excluir uma conversão
GET/creditsConsultar suas páginas disponíveis
GET/credits/usagePáginas usadas no período atual

Criar uma conversão

POST /conversions recebe um corpo multipart/form-data.

CampoTipoObrigatórioDescrição
filefileSimO extrato em PDF, até 30 MB
passwordstringNãoA 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âmetroPadrãoDescrição
page1Número da página
per_page15Resultados por página, até 100
statusnenhumFiltrar por pending, processing, completed ou failed
sort-created_atCampo 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âmetroPadrãoDescrição
formatjsonjson, csv, ofx, qfx (Quicken), qbo (QuickBooks Web Connect) ou xero (Xero CSV)
viewrawPara 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
tablesescolhidas automaticamentePara 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ódigoStatusSignificado
unauthenticated401A chave de API está ausente ou não é válida
not_found404A conversão não existe ou pertence a outra equipe
gone410A conversão foi excluída de acordo com o seu período de retenção
validation_error422Parâmetros inválidos, por exemplo, falta o arquivo ou a senha está errada
insufficient_credits422Não há páginas suficientes para o documento inteiro
payment_failed402O ú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_ready422A 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_statement422As tabelas não podem ser lidas como transações; failure_class indica o motivo
rate_limited429Requisiçõ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.

PlanoPáginas por mêsPreço
Starter500R$ 159/mês, ou R$ 99/mês com cobrança anual
Professional1.000R$ 269/mês, ou R$ 159/mês com cobrança anual
Business5.000R$ 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.