API Bank Statement Conversion
Thêm chuyển đổi với luồng tải lên, kiểm tra trạng thái và tải xuống rõ ràng.
https://bank-statement-conversion.com/api/uploadEndpoint tải lên/conversion-status/{jobId}Endpoint trạng thái/download/{downloadToken}Endpoint tải xuốngTổng quan
API Bank Statement Conversion dành cho nhà phát triển muốn thêm chuyển đổi vào ứng dụng của mình. Tài liệu mô tả quy trình công khai: có thể kiểm tra dung lượng tài khoản, tải tệp lên, hỏi trạng thái công việc rồi tải kết quả hoàn tất bằng token được trả về.
Tài liệu tham chiếu này được cố ý giới hạn trong quy trình chuyển đổi công khai.
https://bank-statement-conversion.com/apiBắt đầu nhanh
Tạo token API
Tạo token trong bảng điều khiển và gửi dưới dạng Authorization: Bearer YOUR_API_TOKEN.
Tải tệp lên
POST tới /api/upload với statement[], format và các thiết lập tùy chọn.
Hỏi trạng thái công việc
Dùng jobId trả về với /api/conversion-status/{jobId} cho đến khi preview có download_token.
Tải kết quả xuống
GET /api/download/{downloadToken} và lưu phản hồi nhị phân thành tệp đã chuyển đổi.
Xác thực
Xác thực bằng token API
Mọi yêu cầu API phải có token API để xác thực. Token có thể được tạo trong phần API Tokens của bảng điều khiển tài khoản.
Cách tạo token API
- Đăng nhập vào tài khoản
- Mở phần API Tokens trong bảng điều khiển
- Nhấp "Create New Token" và đặt tên token
- Sao chép và lưu token an toàn. Token chỉ hiển thị một lần.
Sử dụng token API
Thêm token API vào header Authorization của yêu cầu:
Authorization: Bearer YOUR_API_TOKENTác nhân AI
Dùng API với tác nhân AI
Các công cụ AI có thể tích hợp với cùng quy trình chuyển đổi công khai như nhà phát triển. Dùng lược đồ OpenAPI, tệp khám phá LLM hoặc endpoint MCP để tác nhân biết cần gọi endpoint chuyển đổi nào và hành động nào cần xác nhận.
Khám phá cho tác nhân
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- Dùng
/api/openapi.jsoncho công cụ hiểu schema như ChatGPT Actions hoặc trình tạo tác nhân tùy chỉnh. - Dùng
/llms.txtvà/llms-full.txtđể cung cấp ngữ cảnh sản phẩm và API chuẩn cho tác nhân. - Dùng
/mcp/bank-statement-conversioncho client tác nhân tương thích MCP có hỗ trợ máy chủ MCP từ xa.
Thiết lập token một lần
- Đăng nhập một lần và tạo API token trong bảng điều khiển.
- Giữ mọi quyền chuyển đổi được bật trừ khi bạn muốn token bị giới hạn.
- Đặt token làm BSC_API_TOKEN trong môi trường client MCP.
- Thu hồi token từ bảng điều khiển khi cần dừng quyền truy cập của tác nhân.
Kết nối Codex, Claude, Cursor và client AI khác
Tất cả client AI tương thích MCP dùng cùng endpoint từ xa và bearer token. Hãy giữ token trong biến môi trường, không đặt trong prompt hoặc mã nguồn.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENThiết lập Codex
Thêm mục server này vào cấu hình Codex.
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"Đặt token trong shell hoặc môi trường hệ thống, rồi khởi động lại client AI.
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"Client AI khác
- Claude, Cursor và các client MCP khác nên dùng cùng endpoint URL và Authorization bearer token.
- ChatGPT Actions và trình tạo tác nhân tùy chỉnh nên dùng /api/openapi.json thay vì MCP khi cần schema OpenAPI.
- Dùng /llms.txt và /llms-full.txt làm ngữ cảnh sản phẩm cho tác nhân hỗ trợ tệp kiến thức.
Quyền token có phạm vi
Endpoint quy trình
Đây là các endpoint duy nhất cần để thêm chuyển đổi tài liệu vào ứng dụng.
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/api/user-status | GET | Kiểm tra trước tùy chọn cho credit, hạn mức trang và gói đăng ký |
/api/upload | POST | Tải sao kê ngân hàng lên để chuyển đổi |
/api/conversion-status/{jobId} | GET | Kiểm tra trạng thái công việc chuyển đổi |
/api/download/{downloadToken} | GET | Tải bản chuyển đổi hoàn tất bằng token trả về trong phản hồi trạng thái |
Endpoint trạng thái tài khoản
GET /api/user-status
Dùng endpoint tùy chọn này trước khi tải lên khi ứng dụng cần xác nhận token API có credit, hạn mức trang hoặc quyền truy cập trả phí.
Trường phản hồi hữu ích
| Trường | Kiểu | Mô tả |
|---|---|---|
remaining_credits | integer | Credit còn lại cho chuyển đổi theo credit. |
remaining_daily_pages | integer | Hạn mức trang hằng ngày còn lại của người dùng đã xác thực. |
remaining_premium_pages | integer | Hạn mức trang premium hằng tháng còn lại của gói hiệu lực. |
plan_type | string | Gói đăng ký hiệu lực cho token API. |
Ví dụ phản hồi
{
"success": true,
"remaining_credits": 42,
"remaining_daily_pages": 100,
"remaining_premium_pages": 950,
"plan_type": "premium"
}Endpoint tải lên
POST /api/upload
Endpoint này cho phép tải sao kê ngân hàng lên để chuyển đổi. Quá trình chạy bất đồng bộ và bạn sẽ nhận ID công việc để kiểm tra trạng thái sau.
Định dạng đầu vào hỗ trợ
| Trường hợp dùng | Định dạng | Phần mở rộng | Ghi chú |
|---|---|---|---|
| Chuyển đổi tiêu chuẩn | 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 | Dùng cho sao kê ngân hàng, hóa đơn và biên lai. |
| Làm sạch CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Chỉ dùng khi format là csv_clean. |
| Tạo tệp thanh toán | CSV, XLS, XLSX | .csv, .xls, .xlsx | Dùng cho các dòng thanh toán CSV hoặc Excel để tạo tệp ACH/NACHA, CPA005, SEPA XML, BACS, ABA hoặc NZ sẵn sàng cho ngân hàng xem xét. |
Định dạng đầu ra hỗ trợ
document_type | Tài liệu | Giá trị format cho phép |
|---|---|---|
bank_statement | Sao kê ngân hàng | 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 | Hóa đơn | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Biên lai | csvexceljson |
payment_file | Tệp thanh toán ngân hàng | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Dùng document_type=payment_file với payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba hoặc payment_nz. Tải CSV, XLS hoặc XLSX lên dưới dạng statement[]; quá trình tạo dùng workflow credits, history và download-token hiện có.
Mở trình tạo tệp thanh toánUse 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 generatorTham số yêu cầu
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
format | string | Có | Định dạng đầu ra. Dùng một trong các giá trị format cho phép ở trên cho document_type đã chọn. |
document_type | string | Không | Loại tài liệu: bank_statement, invoice, receipt hoặc payment_file. Mặc định: bank_statement. |
statement | file array | Có | Tệp cần chuyển đổi. Gửi một hoặc nhiều tệp dưới dạng statement[]. |
separate_debit_credit | boolean | Không | Có tách cột ghi nợ và ghi có hay không. Mặc định: false. |
combine_files | boolean | Không | Có gộp nhiều tệp thành một đầu ra hay không. Mặc định: false. |
Ví dụ phản hồi
{
"stage": "pending",
"jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}Endpoint trạng thái
GET /api/conversion-status/{jobId}
Endpoint này cho phép kiểm tra trạng thái công việc chuyển đổi. Hãy poll cho đến khi công việc hoàn tất.
Tham số đường dẫn
| Tham số | Kiểu | Mô tả |
|---|---|---|
jobId | string | ID công việc trả về từ endpoint upload |
Ví dụ phản hồi đang chờ
{
"stage": "processing",
"success": false,
"previews": []
}Ví dụ phản hồi hoàn tất
{
"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
}Ví dụ phản hồi thất bại
{
"stage": "complete",
"success": false,
"error": "An error occurred during the conversion process.",
"message": "The uploaded file could not be processed.",
"previews": []
}Endpoint tải xuống
GET /api/download/{downloadToken}
Dùng download_token trả về trong phản hồi trạng thái đã hoàn tất. Không tự tạo token tải xuống.
Tham số đường dẫn
| Tham số | Kiểu | Mô tả |
|---|---|---|
downloadToken | string | download_token trả về cho tệp đã chuyển đổi trong phản hồi trạng thái. |
Ví dụ yêu cầu
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Ví dụ phản hồi
200 OKVí dụ header phản hồi
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
}Xử lý lỗi
API dùng mã trạng thái HTTP chuẩn để biểu thị yêu cầu thành công hay thất bại.
| Mã trạng thái | Mô tả |
|---|---|
| 200 OK | Yêu cầu thành công |
| 400 Bad Request | Yêu cầu không hợp lệ hoặc thiếu tham số bắt buộc |
| 401 Unauthorized | Xác thực thất bại hoặc token không hợp lệ |
| 403 Forbidden | Người dùng đã xác thực không có quyền truy cập tài nguyên |
| 422 Unprocessable Entity | Đã xảy ra lỗi xác thực dữ liệu |
| 500 Internal Server Error | Đã xảy ra lỗi trên máy chủ |
Ví dụ phản hồi lỗi
{
"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."
}Giới hạn tốc độ
Để đảm bảo sử dụng API công bằng, giới hạn được áp dụng theo gói đăng ký:
- Người dùng premium: 100 yêu cầu mỗi phút
- Kích thước tệp tối đa: 100MB mỗi tệp
- Tối đa 5 tệp mỗi yêu cầu
Ví dụ mã
Ví dụ đầy đủ cho quy trình chuyển đổi: tải lên, hỏi trạng thái, rồi tải xuống.
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}