API do Bank Statement Conversion
Adicione conversão ao seu software com um fluxo claro de upload, status e download.
https://bank-statement-conversion.com/api/uploadEndpoint de upload/conversion-status/{jobId}Endpoint de status/download/{downloadToken}Endpoint de downloadVisã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.
https://bank-statement-conversion.com/apiInício rápido
Crie um token de API
Gere um token no painel e envie-o como Authorization: Bearer YOUR_API_TOKEN.
Envie um arquivo
Faça POST para /api/upload com statement[], format e configurações opcionais.
Consulte o status do trabalho
Use o jobId retornado com /api/conversion-status/{jobId} até que uma prévia inclua download_token.
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
- Entre na sua conta
- Acesse a seção API Tokens no painel
- Clique em "Create New Token" e informe um nome para o token
- 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_TOKENAgentes 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.jsonpara ferramentas compatíveis com schema, como ChatGPT Actions ou construtores de agentes personalizados. - Use
/llms.txte/llms-full.txtpara dar aos agentes o contexto canônico do produto e da API. - Use
/mcp/bank-statement-conversionpara clientes de agentes compatíveis com MCP que ofereçam suporte a servidores MCP remotos.
Configuração única do token
- Faça login uma vez e crie um token de API no painel.
- Mantenha todas as permissões de conversão ativadas, a menos que queira um token restrito.
- Defina o token como BSC_API_TOKEN no ambiente do cliente MCP.
- 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.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENConfiguração do Codex
Adicione esta entrada de servidor à sua configuração do Codex.
[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.
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
Endpoints do fluxo
Estes são os únicos endpoints necessários para adicionar conversão de documentos ao seu aplicativo.
| Endpoint | Método | Descrição |
|---|---|---|
/api/user-status | GET | Verificação opcional de créditos, limite de páginas e plano de assinatura |
/api/upload | POST | Enviar extratos bancários para conversão |
/api/conversion-status/{jobId} | GET | Verificar o status de um trabalho de conversão |
/api/download/{downloadToken} | GET | Baixar 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
| Campo | Tipo | Descrição |
|---|---|---|
remaining_credits | integer | Créditos disponíveis para conversões baseadas em crédito. |
remaining_daily_pages | integer | Limite diário de páginas restante para o usuário autenticado. |
remaining_premium_pages | integer | Limite mensal premium de páginas restante para o plano efetivo. |
plan_type | string | Plano de assinatura efetivo do token de API. |
Exemplo de resposta
{
"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
| Uso | Formatos | Extensões | Notas |
|---|---|---|---|
| Conversões padrão | PDF, 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, .camt053 | Use para conversões de extratos bancários, faturas e recibos. |
| Limpador de CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Use somente quando format for csv_clean. |
| Geração de arquivos de pagamento | CSV, XLS, XLSX | .csv, .xls, .xlsx | Use 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_type | Documento | Valores de format permitidos |
|---|---|---|
bank_statement | Extrato 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 |
invoice | Fatura | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Recibo | csvexceljson |
payment_file | Arquivo de pagamento bancário | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Use document_type=payment_file com payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba ou payment_nz. Envie CSV, XLS ou XLSX como statement[]; a geração usa o fluxo existente de créditos, histórico e tokens de download.
Abrir gerador de arquivos de pagamentoUse document_type=positive_pay_file with format=positive_pay. Upload CSV, XLS, or XLSX check rows as statement[] and pass positive_pay_settings for Chase, TD, generic CSV, or fixed-width profiles.
Open Positive Pay file generatorParâmetros da solicitação
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
format | string | Sim | Formato de saída. Use um dos valores de format permitidos acima para o document_type escolhido. |
document_type | string | Não | Categoria de documento: bank_statement, invoice, receipt ou payment_file. Padrão: bank_statement. |
statement | file array | Sim | Arquivos para converter. Envie um ou mais arquivos como statement[]. |
separate_debit_credit | boolean | Não | Se deve separar colunas de débito e crédito. Padrão: false. |
combine_files | boolean | Não | Se deve combinar vários arquivos em uma única saída. Padrão: false. |
Exemplo de resposta
{
"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âmetro | Tipo | Descrição |
|---|---|---|
jobId | string | O ID do trabalho retornado pelo endpoint de upload |
Exemplo de resposta pendente
{
"stage": "processing",
"success": false,
"previews": []
}Exemplo de resposta concluída
{
"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
{
"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âmetro | Tipo | Descrição |
|---|---|---|
downloadToken | string | O download_token retornado para um arquivo convertido na resposta de status. |
Exemplo de solicitação
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Exemplo de resposta
200 OKExemplo de cabeçalhos de resposta
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 status | Descrição |
|---|---|
| 200 OK | A solicitação foi bem-sucedida |
| 400 Bad Request | A solicitação era inválida ou faltavam parâmetros obrigatórios |
| 401 Unauthorized | A autenticação falhou ou o token é inválido |
| 403 Forbidden | O usuário autenticado não tem permissão para acessar o recurso |
| 422 Unprocessable Entity | Ocorreram erros de validação |
| 500 Internal Server Error | Ocorreu um erro no servidor |
Exemplos de respostas de erro
{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"statement": [
"The statement field is required."
],
"format": [
"The selected format is invalid."
]
}
}{
"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.
npm install axios form-dataPython: pip install requestsPHP: PHP cURL extension enabledcURL: curl and jq installedGo: Go 1.20+Ruby: gem install multipart-postC#: .NET 7+npm install axios form-data1// 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}