Documentação da API - Bank-Statement-Conversion
Referência da API

API do Bank Statement Conversion

Adicione conversão ao seu software com um fluxo claro de upload, status e download.

Autenticação Endpoint de upload Endpoints do fluxo
api.bsc / v1
URL base
https://bank-statement-conversion.com/api
Endpoints do fluxo
POST/uploadEndpoint de upload
GET/conversion-status/{jobId}Endpoint de status
GET/download/{downloadToken}Endpoint de download

Visão geral

A API do Bank Statement Conversion é para desenvolvedores que querem adicionar conversão ao próprio app. Ela documenta o fluxo público de conversão: opcionalmente verificar a capacidade da conta, enviar arquivos, consultar o status do trabalho e baixar os resultados concluídos com o token retornado.

Esta referência é intencionalmente limitada ao fluxo público de conversão.

Início rápido

Etapa 1

Crie um token de API

Gere um token no painel e envie-o como Authorization: Bearer YOUR_API_TOKEN.

Etapa 2

Envie um arquivo

Faça POST para /api/upload com statement[], format e configurações opcionais.

Etapa 3

Consulte o status do trabalho

Use o jobId retornado com /api/conversion-status/{jobId} até que uma prévia inclua download_token.

Etapa 4

Baixe o resultado

Faça GET em /api/download/{downloadToken} e salve a resposta binária como arquivo convertido.

Autenticação

Autenticação por token de API

Todas as solicitações à API devem incluir um token de API para autenticação. Os tokens podem ser gerados no painel da conta, na seção API Tokens.

Como gerar um token de API

  1. Entre na sua conta
  2. Acesse a seção API Tokens no painel
  3. Clique em "Create New Token" e informe um nome para o token
  4. Copie e armazene o token com segurança. Ele será mostrado apenas uma vez.

Usando seu token de API

Inclua seu token de API no cabeçalho Authorization das solicitações:

Authorization: Bearer YOUR_API_TOKEN

Agentes de IA

Usar a API com agentes de IA

As ferramentas de IA podem se integrar ao mesmo fluxo público de conversão usado por desenvolvedores. Use o esquema OpenAPI, os arquivos de descoberta para LLM ou o endpoint MCP para que os agentes saibam quais endpoints de conversão chamar e quais ações exigem confirmação.

Descoberta para agentes

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Use /api/openapi.json para ferramentas compatíveis com schema, como ChatGPT Actions ou construtores de agentes personalizados.
  • Use /llms.txt e /llms-full.txt para dar aos agentes o contexto canônico do produto e da API.
  • Use /mcp/bank-statement-conversion para clientes de agentes compatíveis com MCP que ofereçam suporte a servidores MCP remotos.

Configuração única do token

  1. Faça login uma vez e crie um token de API no painel.
  2. Mantenha todas as permissões de conversão ativadas, a menos que queira um token restrito.
  3. Defina o token como BSC_API_TOKEN no ambiente do cliente MCP.
  4. Revogue o token no painel quando o acesso do agente precisar terminar.

Conectar Codex, Claude, Cursor e outros clientes de IA

Todos os clientes de IA compatíveis com MCP usam o mesmo endpoint remoto e token bearer. Mantenha o token em uma variável de ambiente, não em prompts ou código-fonte.

Endpoint MCP remoto
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Cabeçalho de autenticação
Authorization: Bearer YOUR_API_TOKEN
Configuração do Codex

Adicione esta entrada de servidor à sua configuração do Codex.

Codex MCP configtoml
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"

Defina o token no shell ou ambiente do sistema e reinicie o cliente de IA.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Outros clientes de IA
  • Claude, Cursor e outros clientes MCP devem usar o mesmo endpoint e token bearer Authorization.
  • ChatGPT Actions e construtores de agentes personalizados devem usar /api/openapi.json em vez de MCP quando precisarem de um schema OpenAPI.
  • Use /llms.txt e /llms-full.txt como contexto de produto para agentes que suportam arquivos de conhecimento.

Permissões de token com escopo

account:statusconversion:uploadconversion:readconversion:download

Endpoints do fluxo

Estes são os únicos endpoints necessários para adicionar conversão de documentos ao seu aplicativo.

EndpointMétodoDescrição
/api/user-statusGETVerificação opcional de créditos, limite de páginas e plano de assinatura
/api/uploadPOSTEnviar extratos bancários para conversão
/api/conversion-status/{jobId}GETVerificar o status de um trabalho de conversão
/api/download/{downloadToken}GETBaixar uma conversão concluída usando o token retornado na resposta de status

Endpoint de status da conta

GET /api/user-status

Use este endpoint opcional antes do upload quando seu app precisar confirmar se o token de API tem créditos, limite de páginas ou acesso pago.

Campos úteis da resposta

CampoTipoDescrição
remaining_creditsintegerCréditos disponíveis para conversões baseadas em crédito.
remaining_daily_pagesintegerLimite diário de páginas restante para o usuário autenticado.
remaining_premium_pagesintegerLimite mensal premium de páginas restante para o plano efetivo.
plan_typestringPlano de assinatura efetivo do token de API.

Exemplo de resposta

Resposta JSONjson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Endpoint de upload

POST /api/upload

Este endpoint permite enviar extratos bancários para conversão. O processo é assíncrono e você receberá um ID de trabalho para consultar o status depois.

Formatos de entrada compatíveis

UsoFormatosExtensõesNotas
Conversões padrãoPDF, JPG/JPEG, PNG, TIFF/TIF, CSV, XLS/XLSX, OFX, QBO, QFX, 940, STA, MT940, MT940X, XML, CAMT.053.pdf, .jpg, .jpeg, .png, .tiff, .tif, .csv, .xls, .xlsx, .ofx, .qbo, .qfx, .940, .sta, .mt940, .mt940x, .xml, .camt053Use para conversões de extratos bancários, faturas e recibos.
Limpador de CSVCSV, XLS, XLSX.csv, .xls, .xlsxUse somente quando format for csv_clean.
Geração de arquivos de pagamentoCSV, XLS, XLSX.csv, .xls, .xlsxUse para linhas de pagamento CSV ou Excel que geram arquivos ACH/NACHA, CPA005, SEPA XML, BACS, ABA ou NZ prontos para revisão bancária.

Formatos de saída compatíveis

document_typeDocumentoValores de format permitidos
bank_statementExtrato bancário
csvexceljsonqb_onlineqb_desktopxeroofxofx_legacyqfxmt940mt940_moneybirdcamt053camt053_legacycamt053_moneybirdcamt053_netsuitecamt053_sap_v2camt053_sap_v8camt053_business_centralcamt053_datevcamt053_afascamt053_twinfieldtally_xmlbai2bai2_netsuitebai2_sapbai2_bank_xsagesage_cloudsage_intacctmyobdatevdatev_accountingcsv_clean
invoiceFatura
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptRecibo
csvexceljson
payment_fileArquivo de pagamento bancário
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Parâmetros da solicitação

ParâmetroTipoObrigatórioDescrição
formatstringSimFormato de saída. Use um dos valores de format permitidos acima para o document_type escolhido.
document_typestringNãoCategoria de documento: bank_statement, invoice, receipt ou payment_file. Padrão: bank_statement.
statementfile arraySimArquivos para converter. Envie um ou mais arquivos como statement[].
separate_debit_creditbooleanNãoSe deve separar colunas de débito e crédito. Padrão: false.
combine_filesbooleanNãoSe deve combinar vários arquivos em uma única saída. Padrão: false.

Exemplo de resposta

Resposta JSONjson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint de status

GET /api/conversion-status/{jobId}

Este endpoint permite verificar o status de um trabalho de conversão. Consulte até que o trabalho seja concluído.

Parâmetros de caminho

ParâmetroTipoDescrição
jobIdstringO ID do trabalho retornado pelo endpoint de upload

Exemplo de resposta pendente

Resposta JSONjson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Exemplo de resposta concluída

Resposta JSONjson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "success": true,
  "previews": [
    {
      "file_name": "bank_statement.pdf",
      "format": "CSV",
      "download_token": "Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH",
      "partial_conversion": false,
      "credits_used": 1
    }
  ],
  "failed_files": [],
  "remaining_credits": 41,
  "remaining_premium_pages": 949,
  "remaining_daily_pages": 99
}

Exemplo de resposta com falha

Resposta JSONjson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Endpoint de download

GET /api/download/{downloadToken}

Use o download_token retornado em uma resposta de status concluída. Não construa tokens de download manualmente.

Parâmetros de caminho

ParâmetroTipoDescrição
downloadTokenstringO download_token retornado para um arquivo convertido na resposta de status.

Exemplo de solicitação

Baixar com cURLbash
Execute no terminal depois de substituir o token e o token de download.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Exemplo de resposta

200 OK
Retorna o arquivo convertido como download binário com Content-Disposition: attachment. A extensão depende do formato solicitado, como .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt ou .aba.

Exemplo de cabeçalhos de resposta

Cabeçalhos de respostahttp
O endpoint de download retorna um stream de arquivo em vez de um corpo JSON.
HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="bank-statement.csv"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
}

Tratamento de erros

A API usa códigos de status HTTP padrão para indicar sucesso ou falha das solicitações.

Código de statusDescrição
200 OKA solicitação foi bem-sucedida
400 Bad RequestA solicitação era inválida ou faltavam parâmetros obrigatórios
401 UnauthorizedA autenticação falhou ou o token é inválido
403 ForbiddenO usuário autenticado não tem permissão para acessar o recurso
422 Unprocessable EntityOcorreram erros de validação
500 Internal Server ErrorOcorreu um erro no servidor

Exemplos de respostas de erro

401 Não autorizadojson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "message": "Unauthenticated."
}
422 Erro de validaçãojson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Capacidade insuficientejson
Copie esta estrutura para parsing no cliente e tratamento de erros.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Limites de taxa

Para garantir uso justo da API, limites são aplicados com base no seu plano de assinatura:

  • Usuários premium: 100 solicitações por minuto
  • Tamanho máximo do arquivo: 100MB por arquivo
  • Máximo de arquivos por solicitação: 5

Exemplos de código

Exemplos ponta a ponta do fluxo de conversão: enviar, consultar e baixar.

1. Enviar2. Consultar status3. Baixar
JavaScript exemplojavascript
Usa axios e form-data para enviar, consultar e baixar o arquivo convertido.
1// Upload a bank statement file
2const axios = require('axios');
3const FormData = require('form-data');
4const fs = require('fs');
5
6// Your API token from the dashboard
7const API_TOKEN = 'your_api_token_here';
8
9// Create a form data object
10const formData = new FormData();
11formData.append('document_type', 'bank_statement');
12formData.append('format', 'csv');
13formData.append('statement[]', fs.createReadStream('bank_statement.pdf'));
14formData.append('separate_debit_credit', 'true');
15formData.append('combine_files', 'false');
16
17// Make the API request
18const BASE_URL = 'https://bank-statement-conversion.com/api';
19
20axios.post(`${BASE_URL}/upload`, formData, {
21  headers: {
22    'Authorization': `Bearer ${API_TOKEN}`,
23    ...formData.getHeaders()
24  }
25})
26.then(response => {
27  const jobId = response.data.jobId;
28  console.log(`Conversion job started with ID: ${jobId}`);
29
30  // Poll for job status
31  checkJobStatus(jobId);
32})
33.catch(error => {
34  console.error('Error uploading file:', error.response ? error.response.data : error.message);
35});
36
37// Function to check job status
38function checkJobStatus(jobId) {
39  axios.get(`${BASE_URL}/conversion-status/${jobId}`, {
40    headers: {
41      'Authorization': `Bearer ${API_TOKEN}`
42    }
43  })
44  .then(response => {
45    const data = response.data;
46    console.log('Job stage:', data.stage);
47
48    if (data.success && data.previews && data.previews.length > 0) {
49      const downloadToken = data.previews[0].download_token;
50      downloadFile(`${BASE_URL}/download/${downloadToken}`);
51    } else if (data.stage === 'pending' || data.stage === 'processing') {
52      // Check again after 5 seconds
53      setTimeout(() => checkJobStatus(jobId), 5000);
54    } else {
55      console.error('Conversion failed:', data.error || data.message || data);
56    }
57  })
58  .catch(error => {
59    console.error('Error checking job status:', error.response ? error.response.data : error.message);
60  });
61}
62
63// Function to download the converted file
64function downloadFile(url) {
65  const outputPath = 'converted_statement.csv';
66
67  axios({
68    method: 'get',
69    url: url,
70    responseType: 'stream',
71    headers: {
72      'Authorization': `Bearer ${API_TOKEN}`
73    }
74  })
75  .then(response => {
76    response.data.pipe(fs.createWriteStream(outputPath));
77    console.log(`File downloaded to ${outputPath}`);
78  })
79  .catch(error => {
80    console.error('Error downloading file:', error.message);
81  });
82}