Tài liệu API - Bank-Statement-Conversion
Tham chiếu API

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.

Xác thực Endpoint tải lên Endpoint quy trình
api.bsc / v1
URL cơ sở
https://bank-statement-conversion.com/api
Endpoint quy trình
POST/uploadEndpoint tải lên
GET/conversion-status/{jobId}Endpoint trạng thái
GET/download/{downloadToken}Endpoint tải xuống

Tổ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.

Bắt đầu nhanh

Bước 1

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.

Bước 2

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.

Bước 3

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.

Bước 4

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

  1. Đăng nhập vào tài khoản
  2. Mở phần API Tokens trong bảng điều khiển
  3. Nhấp "Create New Token" và đặt tên token
  4. 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_TOKEN

Tá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.json cho 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.txt/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-conversion cho 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

  1. Đăng nhập một lần và tạo API token trong bảng điều khiển.
  2. Giữ mọi quyền chuyển đổi được bật trừ khi bạn muốn token bị giới hạn.
  3. Đặt token làm BSC_API_TOKEN trong môi trường client MCP.
  4. 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.

Endpoint MCP từ xa
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Header xác thực
Authorization: Bearer YOUR_API_TOKEN
Thiết lập Codex

Thêm mục server này vào cấu hình 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"

Đặt token trong shell hoặc môi trường hệ thống, rồi khởi động lại client AI.

Token environment variablebash
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

account:statusconversion:uploadconversion:readconversion:download

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.

EndpointPhương thứcMô tả
/api/user-statusGETKiểm tra trước tùy chọn cho credit, hạn mức trang và gói đăng ký
/api/uploadPOSTTải sao kê ngân hàng lên để chuyển đổi
/api/conversion-status/{jobId}GETKiểm tra trạng thái công việc chuyển đổi
/api/download/{downloadToken}GETTả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ườngKiểuMô tả
remaining_creditsintegerCredit còn lại cho chuyển đổi theo credit.
remaining_daily_pagesintegerHạn mức trang hằng ngày còn lại của người dùng đã xác thực.
remaining_premium_pagesintegerHạn mức trang premium hằng tháng còn lại của gói hiệu lực.
plan_typestringGói đăng ký hiệu lực cho token API.

Ví dụ phản hồi

Phản hồi JSONjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗ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ạngPhần mở rộngGhi chú
Chuyển đổi tiêu chuẩnPDF, 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, .camt053Dùng cho sao kê ngân hàng, hóa đơn và biên lai.
Làm sạch CSVCSV, XLS, XLSX.csv, .xls, .xlsxChỉ dùng khi format là csv_clean.
Tạo tệp thanh toánCSV, XLS, XLSX.csv, .xls, .xlsxDù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_typeTài liệuGiá trị format cho phép
bank_statementSao 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
invoiceHóa đơn
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptBiên lai
csvexceljson
payment_fileTệp thanh toán ngân hàng
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Tham số yêu cầu

Tham sốKiểuBắt buộcMô tả
formatstringĐị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_typestringKhôngLoại tài liệu: bank_statement, invoice, receipt hoặc payment_file. Mặc định: bank_statement.
statementfile arrayTệp cần chuyển đổi. Gửi một hoặc nhiều tệp dưới dạng statement[].
separate_debit_creditbooleanKhôngCó tách cột ghi nợ và ghi có hay không. Mặc định: false.
combine_filesbooleanKhôngCó 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

Phản hồi JSONjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗ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ểuMô tả
jobIdstringID công việc trả về từ endpoint upload

Ví dụ phản hồi đang chờ

Phản hồi JSONjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗi.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Ví dụ phản hồi hoàn tất

Phản hồi JSONjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗi.
{
  "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

Phản hồi JSONjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗ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ểuMô tả
downloadTokenstringdownload_token trả về cho tệp đã chuyển đổi trong phản hồi trạng thái.

Ví dụ yêu cầu

Tải xuống bằng cURLbash
Chạy trong terminal sau khi thay token và token tải xuống.
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 OK
Trả về tệp đã chuyển đổi dưới dạng tải xuống nhị phân với Content-Disposition: attachment. Phần mở rộng phụ thuộc định dạng đầu ra như .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt hoặc .aba.

Ví dụ header phản hồi

Header phản hồihttp
Endpoint tải xuống trả về luồng tệp thay vì body 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
}

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áiMô tả
200 OKYêu cầu thành công
400 Bad RequestYêu cầu không hợp lệ hoặc thiếu tham số bắt buộc
401 UnauthorizedXác thực thất bại hoặc token không hợp lệ
403 ForbiddenNgườ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

401 Chưa được phépjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗi.
{
  "message": "Unauthenticated."
}
422 Lỗi xác thực dữ liệujson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗi.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Không đủ dung lượngjson
Sao chép cấu trúc này để phân tích phía client và xử lý lỗi.
{
  "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.

1. Tải lên2. Hỏi trạng thái3. Tải xuống
JavaScript ví dụjavascript
Dùng axios và form-data để tải lên, poll và tải tệp đã chuyển đổi.
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}