概要
Bank Statement Conversion API は、自社アプリに変換機能を追加したい開発者向けです。公開されている変換フローとして、必要に応じたアカウント容量の確認、ファイルのアップロード、ジョブ状態のポーリング、返されたトークンによる完了済み出力のダウンロードを説明します。
このリファレンスは、公開変換ワークフローに意図的に限定されています。
https://bank-statement-conversion.com/apiクイックスタート
API トークンを作成
ダッシュボードでトークンを生成し、Authorization: Bearer YOUR_API_TOKEN として送信します。
ファイルをアップロード
/api/upload に statement[]、format、任意の変換設定を含めて POST します。
ジョブ状態をポーリング
返された jobId を /api/conversion-status/{jobId} に指定し、プレビューに download_token が含まれるまで確認します。
出力をダウンロード
/api/download/{downloadToken} に GET し、バイナリレスポンスを変換済みファイルとして保存します。
認証
API トークン認証
すべての API リクエストには認証用の API トークンが必要です。トークンはアカウントダッシュボードの API Tokens セクションで生成できます。
API トークンの作成方法
- アカウントにログインします
- ダッシュボードの API Tokens セクションへ移動します
- "Create New Token" をクリックしてトークン名を入力します
- 生成されたトークンをコピーして安全に保管します。表示されるのは一度だけです。
API トークンの使用
リクエストの Authorization ヘッダーに API トークンを含めます:
Authorization: Bearer YOUR_API_TOKENAI エージェント
AI エージェントで API を使う
AI ツールは、開発者と同じ公開変換ワークフローに統合できます。OpenAPI スキーマ、LLM 検出ファイル、または MCP エンドポイントを使用して、エージェントが呼び出す変換エンドポイントと確認が必要な操作を把握できるようにします。
エージェント discovery
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- ChatGPT Actions やカスタムエージェントビルダーなど、スキーマ対応ツールには
/api/openapi.jsonを使います。 - エージェントに正規の製品コンテキストと API コンテキストを渡すには
/llms.txtと/llms-full.txtを使います。 - リモート 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 クライアントは、同じ endpoint URL と Authorization bearer token を使用してください。
- ChatGPT Actions やカスタムエージェントビルダーで OpenAPI schema が必要な場合は、MCP ではなく /api/openapi.json を使用してください。
- 知識ファイルをサポートするエージェントには、製品コンテキストとして /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 | はい | 変換するファイル。1 つ以上のファイルを statement[] として送信します。 |
conversion_mode | string | いいえ | 変換モード: precision または fast。既定値は precision です。 |
separate_debit_credit | boolean | いいえ | デビット列とクレジット列を分離するかどうか。既定値: false。 |
combine_files | boolean | いいえ | 複数ファイルを 1 つの出力にまとめるかどうか。既定値: 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 の公平な利用を保証するため、サブスクリプションプランに応じてレート制限が適用されます:
- プレミアムユーザー: 1 分あたり 100 リクエスト
- 最大ファイルサイズ: 1 ファイルあたり 100MB
- 1 リクエストあたり最大 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}