概览
Bank Statement Conversion API 面向希望在自己的应用中加入转换功能的开发者。本文档说明公开转换流程:可先检查账户容量,上传文件,轮询作业状态,然后使用返回的令牌下载完成的输出。
本参考文档有意仅限于公开转换流程。
https://bank-statement-conversion.com/api快速开始
创建 API 令牌
在控制台生成令牌,并以 Authorization: Bearer YOUR_API_TOKEN 发送。
上传文件
向 /api/upload 发送 POST,包含 statement[]、format 和可选转换设置。
轮询作业状态
使用返回的 jobId 调用 /api/conversion-status/{jobId},直到预览中包含 download_token。
下载输出
请求 GET /api/download/{downloadToken},并将二进制响应保存为转换后的文件。
认证
API 令牌认证
所有 API 请求都必须包含用于认证的 API 令牌。令牌可在账户控制台的 API Tokens 区域生成。
如何生成 API 令牌
- 登录账户
- 进入控制台的 API Tokens 区域
- 点击 "Create New Token" 并为令牌命名
- 复制并安全保存生成的令牌。它只会显示一次。
使用 API 令牌
在请求的 Authorization 头中包含 API 令牌:
Authorization: Bearer YOUR_API_TOKENAI 代理
将 API 用于 AI 代理
AI 工具可以与开发人员使用的同一公共转换工作流集成。使用 OpenAPI 架构、LLM 发现文件或 MCP 端点,让代理知道要调用哪些转换端点以及哪些操作需要确认。
代理发现
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- 将
/api/openapi.json用于支持架构的工具,例如 ChatGPT Actions 或自定义代理构建器。 - 使用
/llms.txt和/llms-full.txt为代理提供标准的产品和 API 上下文。 - 对于支持远程 MCP 服务器的 MCP 兼容代理客户端,请使用
/mcp/bank-statement-conversion。
一次性令牌设置
- 登录一次,并在仪表板中创建 API 令牌。
- 除非需要受限令牌,否则保持所有转换权限启用。
- 在 MCP 客户端环境中将令牌设置为 BSC_API_TOKEN。
- 当需要停止代理访问时,可在仪表板中撤销该令牌。
连接 Codex、Claude、Cursor 和其他 AI 客户端
所有兼容 MCP 的 AI 客户端都使用同一个远程端点和 bearer token。请将令牌保存在环境变量中,不要放入提示词或源代码。
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENCodex 设置
将此服务器配置添加到你的 Codex 配置中。
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"在 shell 或系统环境中设置令牌,然后重启 AI 客户端。
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"其他 AI 客户端
- Claude、Cursor 和其他 MCP 客户端应使用相同的端点 URL 和 Authorization bearer token。
- ChatGPT Actions 和自定义代理构建器在需要 OpenAPI 架构时,应使用 /api/openapi.json,而不是 MCP。
- 对于支持知识文件的代理,可使用 /llms.txt 和 /llms-full.txt 作为产品上下文。
有范围的令牌权限
流程端点
这些是将文档转换加入应用所需的唯一端点。
| 端点 | 方法 | 说明 |
|---|---|---|
/api/user-status | GET | 可选的额度、页数和订阅套餐预检 |
/api/upload | POST | 上传银行对账单进行转换 |
/api/conversion-status/{jobId} | GET | 检查转换作业状态 |
/api/download/{downloadToken} | GET | 使用状态响应中返回的令牌下载完成的转换结果 |
账户状态端点
GET /api/user-status
当应用需要确认 API 令牌是否有可用额度、页数或付费套餐访问权限时,请在上传前使用此可选端点。
有用的响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
remaining_credits | integer | 基于额度转换可用的额度。 |
remaining_daily_pages | integer | 已认证用户剩余的每日页数额度。 |
remaining_premium_pages | integer | 当前套餐剩余的每月高级页数额度。 |
plan_type | string | API 令牌对应的有效订阅套餐。 |
响应示例
{
"success": true,
"remaining_credits": 42,
"remaining_daily_pages": 100,
"remaining_premium_pages": 950,
"plan_type": "premium"
}上传端点
POST /api/upload
此端点用于上传银行对账单进行转换。转换过程是异步的,你会收到一个作业 ID,之后可用它检查状态。
支持的输入格式
| 用途 | 格式 | 扩展名 | 备注 |
|---|---|---|---|
| 标准转换 | 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 | 用于银行对账单、发票和收据转换。 |
| CSV 清理 | CSV, XLS, XLSX | .csv, .xls, .xlsx | 仅在 format 为 csv_clean 时使用。 |
| 付款文件生成 | CSV, XLS, XLSX | .csv, .xls, .xlsx | 用于 CSV 或 Excel 付款行,生成银行可审查的 ACH/NACHA、CPA005、SEPA XML、BACS、ABA 或 NZ 付款文件。 |
支持的输出格式
document_type | 文档 | 允许的 format 值 |
|---|---|---|
bank_statement | 银行对账单 | 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 | 发票 | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | 收据 | csvexceljson |
payment_file | 银行付款文件 | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
将 document_type=payment_file 与 payment_nacha、payment_cpa005、payment_sepa_pain001、payment_bacs、payment_aba 或 payment_nz 一起使用。将 CSV、XLS 或 XLSX 作为 statement[] 上传;生成流程使用现有的 credits、history 和 download-token 工作流。
打开付款文件生成器Use 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 generator请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
format | string | 是 | 输出格式。请为所选 document_type 使用上方允许的 format 值之一。 |
document_type | string | 否 | 文档类别:bank_statement、invoice、receipt 或 payment_file。默认值:bank_statement。 |
statement | file array | 是 | 要转换的文件。以 statement[] 发送一个或多个文件。 |
conversion_mode | string | 否 | 转换模式:precision 或 fast。默认值为 precision。 |
separate_debit_credit | boolean | 否 | 是否拆分借方和贷方列。默认值:false。 |
combine_files | boolean | 否 | 是否将多个文件合并为单个输出。默认值:false。 |
响应示例
{
"stage": "pending",
"jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}状态端点
GET /api/conversion-status/{jobId}
此端点用于检查转换作业状态。应持续轮询,直到作业完成。
路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
jobId | string | 上传端点返回的作业 ID |
待处理响应示例
{
"stage": "processing",
"success": false,
"previews": []
}完成响应示例
{
"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
}失败响应示例
{
"stage": "complete",
"success": false,
"error": "An error occurred during the conversion process.",
"message": "The uploaded file could not be processed.",
"previews": []
}下载端点
GET /api/download/{downloadToken}
使用完成状态响应中的 download_token。不要自行构造下载令牌。
路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
downloadToken | string | 状态响应中为转换文件返回的 download_token。 |
请求示例
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"响应示例
200 OK响应头示例
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
}错误处理
API 使用标准 HTTP 状态码表示请求成功或失败。
| 状态码 | 说明 |
|---|---|
| 200 OK | 请求成功 |
| 400 Bad Request | 请求无效或缺少必填参数 |
| 401 Unauthorized | 认证失败或令牌无效 |
| 403 Forbidden | 已认证用户无权访问该资源 |
| 422 Unprocessable Entity | 发生验证错误 |
| 500 Internal Server Error | 服务器发生错误 |
错误响应示例
{
"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."
}速率限制
为确保 API 公平使用,将根据你的订阅套餐应用速率限制:
- 高级用户:每分钟 100 个请求
- 最大文件大小:每个文件 100MB
- 每次请求最多 5 个文件
代码示例
转换流程的端到端示例:上传、轮询,然后下载。
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}