API 文档 - Bank-Statement-Conversion

Bank Statement Conversion API

通过上传、状态查询和下载流程把银行对账单转换加入您的软件。

概览

Bank Statement Conversion API 面向希望在自己的应用中加入转换功能的开发者。本文档说明公开转换流程:可先检查账户容量,上传文件,轮询作业状态,然后使用返回的令牌下载完成的输出。

本参考文档有意仅限于公开转换流程。

快速开始

步骤 1

创建 API 令牌

在控制台生成令牌,并以 Authorization: Bearer YOUR_API_TOKEN 发送。

步骤 2

上传文件

向 /api/upload 发送 POST,包含 statement[]、format 和可选转换设置。

步骤 3

轮询作业状态

使用返回的 jobId 调用 /api/conversion-status/{jobId},直到预览中包含 download_token。

步骤 4

下载输出

请求 GET /api/download/{downloadToken},并将二进制响应保存为转换后的文件。

认证

API 令牌认证

所有 API 请求都必须包含用于认证的 API 令牌。令牌可在账户控制台的 API Tokens 区域生成。

如何生成 API 令牌

  1. 登录账户
  2. 进入控制台的 API Tokens 区域
  3. 点击 "Create New Token" 并为令牌命名
  4. 复制并安全保存生成的令牌。它只会显示一次。

使用 API 令牌

在请求的 Authorization 头中包含 API 令牌:

Authorization: Bearer YOUR_API_TOKEN

AI 代理

将 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

一次性令牌设置

  1. 登录一次,并在仪表板中创建 API 令牌。
  2. 除非需要受限令牌,否则保持所有转换权限启用。
  3. 在 MCP 客户端环境中将令牌设置为 BSC_API_TOKEN。
  4. 当需要停止代理访问时,可在仪表板中撤销该令牌。

连接 Codex、Claude、Cursor 和其他 AI 客户端

所有兼容 MCP 的 AI 客户端都使用同一个远程端点和 bearer token。请将令牌保存在环境变量中,不要放入提示词或源代码。

远程 MCP 端点
https://bank-statement-conversion.com/mcp/bank-statement-conversion
认证请求头
Authorization: Bearer YOUR_API_TOKEN
Codex 设置

将此服务器配置添加到你的 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"

在 shell 或系统环境中设置令牌,然后重启 AI 客户端。

Token environment variablebash
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 作为产品上下文。

有范围的令牌权限

account:statusconversion:uploadconversion:readconversion:download

流程端点

这些是将文档转换加入应用所需的唯一端点。

端点方法说明
/api/user-statusGET可选的额度、页数和订阅套餐预检
/api/uploadPOST上传银行对账单进行转换
/api/conversion-status/{jobId}GET检查转换作业状态
/api/download/{downloadToken}GET使用状态响应中返回的令牌下载完成的转换结果

账户状态端点

GET /api/user-status

当应用需要确认 API 令牌是否有可用额度、页数或付费套餐访问权限时,请在上传前使用此可选端点。

有用的响应字段

字段类型说明
remaining_creditsinteger基于额度转换可用的额度。
remaining_daily_pagesinteger已认证用户剩余的每日页数额度。
remaining_premium_pagesinteger当前套餐剩余的每月高级页数额度。
plan_typestringAPI 令牌对应的有效订阅套餐。

响应示例

JSON 响应json
复制此结构用于客户端解析和错误处理。
{
  "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

请求参数

参数类型必填说明
formatstring输出格式。请为所选 document_type 使用上方允许的 format 值之一。
document_typestring文档类别:bank_statement、invoice、receipt 或 payment_file。默认值:bank_statement。
statementfile array要转换的文件。以 statement[] 发送一个或多个文件。
conversion_modestring转换模式:precision 或 fast。默认值为 precision。
separate_debit_creditboolean是否拆分借方和贷方列。默认值:false。
combine_filesboolean是否将多个文件合并为单个输出。默认值:false。

响应示例

JSON 响应json
复制此结构用于客户端解析和错误处理。
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

状态端点

GET /api/conversion-status/{jobId}

此端点用于检查转换作业状态。应持续轮询,直到作业完成。

路径参数

参数类型说明
jobIdstring上传端点返回的作业 ID

待处理响应示例

JSON 响应json
复制此结构用于客户端解析和错误处理。
{
  "stage": "processing",
  "success": false,
  "previews": []
}

完成响应示例

JSON 响应json
复制此结构用于客户端解析和错误处理。
{
  "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
}

失败响应示例

JSON 响应json
复制此结构用于客户端解析和错误处理。
{
  "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。不要自行构造下载令牌。

路径参数

参数类型说明
downloadTokenstring状态响应中为转换文件返回的 download_token。

请求示例

使用 cURL 下载bash
替换令牌和下载令牌后在终端运行。
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

响应示例

200 OK
以带有 Content-Disposition: attachment 的二进制下载返回转换后的文件。文件扩展名取决于请求的输出格式,例如 .csv、.xlsx、.qbo、.ofx、.xml、.json、.ach、.txt 或 .aba。

响应头示例

响应头http
下载端点返回文件流,而不是 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
}

错误处理

API 使用标准 HTTP 状态码表示请求成功或失败。

状态码说明
200 OK请求成功
400 Bad Request请求无效或缺少必填参数
401 Unauthorized认证失败或令牌无效
403 Forbidden已认证用户无权访问该资源
422 Unprocessable Entity发生验证错误
500 Internal Server Error服务器发生错误

错误响应示例

401 未认证json
复制此结构用于客户端解析和错误处理。
{
  "message": "Unauthenticated."
}
422 验证错误json
复制此结构用于客户端解析和错误处理。
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 容量不足json
复制此结构用于客户端解析和错误处理。
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

速率限制

为确保 API 公平使用,将根据你的订阅套餐应用速率限制:

  • 高级用户:每分钟 100 个请求
  • 最大文件大小:每个文件 100MB
  • 每次请求最多 5 个文件

代码示例

转换流程的端到端示例:上传、轮询,然后下载。

1. 上传2. 轮询状态3. 下载
JavaScript 示例javascript
使用 axios 和 form-data 上传、轮询并下载转换后的文件。
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}