API ドキュメント - Bank-Statement-Conversion

Bank Statement Conversion API

アップロード、ステータス確認、ダウンロードの流れで銀行明細変換を追加できます。

概要

Bank Statement Conversion API は、自社アプリに変換機能を追加したい開発者向けです。公開されている変換フローとして、必要に応じたアカウント容量の確認、ファイルのアップロード、ジョブ状態のポーリング、返されたトークンによる完了済み出力のダウンロードを説明します。

このリファレンスは、公開変換ワークフローに意図的に限定されています。

クイックスタート

ステップ 1

API トークンを作成

ダッシュボードでトークンを生成し、Authorization: Bearer YOUR_API_TOKEN として送信します。

ステップ 2

ファイルをアップロード

/api/upload に statement[]、format、任意の変換設定を含めて POST します。

ステップ 3

ジョブ状態をポーリング

返された jobId を /api/conversion-status/{jobId} に指定し、プレビューに download_token が含まれるまで確認します。

ステップ 4

出力をダウンロード

/api/download/{downloadToken} に GET し、バイナリレスポンスを変換済みファイルとして保存します。

認証

API トークン認証

すべての API リクエストには認証用の API トークンが必要です。トークンはアカウントダッシュボードの API Tokens セクションで生成できます。

API トークンの作成方法

  1. アカウントにログインします
  2. ダッシュボードの API Tokens セクションへ移動します
  3. "Create New Token" をクリックしてトークン名を入力します
  4. 生成されたトークンをコピーして安全に保管します。表示されるのは一度だけです。

API トークンの使用

リクエストの Authorization ヘッダーに API トークンを含めます:

Authorization: Bearer YOUR_API_TOKEN

AI エージェント

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 を使います。

一度だけのトークン設定

  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 クライアントは、同じ endpoint URL と Authorization bearer token を使用してください。
  • ChatGPT Actions やカスタムエージェントビルダーで OpenAPI schema が必要な場合は、MCP ではなく /api/openapi.json を使用してください。
  • 知識ファイルをサポートするエージェントには、製品コンテキストとして /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, .xlsxformat が csv_clean の場合のみ使用します。
支払ファイル生成CSV, XLS, XLSX.csv, .xls, .xlsxCSV または 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はい変換するファイル。1 つ以上のファイルを statement[] として送信します。
conversion_modestringいいえ変換モード: precision または fast。既定値は precision です。
separate_debit_creditbooleanいいえデビット列とクレジット列を分離するかどうか。既定値: false。
combine_filesbooleanいいえ複数ファイルを 1 つの出力にまとめるかどうか。既定値: 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 の公平な利用を保証するため、サブスクリプションプランに応じてレート制限が適用されます:

  • プレミアムユーザー: 1 分あたり 100 リクエスト
  • 最大ファイルサイズ: 1 ファイルあたり 100MB
  • 1 リクエストあたり最大 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}