BBankcodeJP API Reference
Batch Lookup API v1

銀行・支店コードをまとめて照合

銀行コード、または銀行コードと支店コードの組を完全一致で照合します。1回のHTTPリクエストで1〜100件を送り、入力順に各項目の結果を取得できます。

Search APIのStandard・Proプランに同梱されています。追加料金・リクエストごとの従量課金はありません。Freeプランは対象外です。現在の契約で有効なAPIキーを利用してください。

プランBatch Lookupの日次枠
Free対象外
Standard100リクエスト/日
Pro500リクエスト/日

料金・提供条件 / APIキーの取得

リクエスト

操作メソッドとURL
銀行の照合POST https://apis.bankcode-jp.com/batch/v1/banks
支店の照合POST https://apis.bankcode-jp.com/batch/v1/branches

Content-Type: application/json と x-api-key ヘッダーを設定します。コードは先頭の0を保持する文字列で指定してください。銀行コードは半角数字4桁、支店コードは半角数字3桁です。自動ゼロ埋め・名前検索・部分一致は行いません。

items は1〜100件、JSON本文は65,536バイト（64 KiB）以下です。未知のフィールドはHTTP 400になります。

銀行リクエスト

curl --request POST 'https://apis.bankcode-jp.com/batch/v1/banks' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${BANKCODEJP_API_KEY}" \
  --data '{"items":[{"bankCode":"0001","reference":"row-1"},{"bankCode":"0001","reference":""},{"bankCode":"1","reference":"row-3"}]}'

支店リクエストの本文

{"items":[{"bankCode":"0001","branchCode":"001","reference":"row-1"},{"bankCode":"0001","branchCode":"999","reference":"row-2"}]}
項目指定方法
bankCode銀行コードを文字列で指定。数値はHTTP 400。
branchCode支店照合の場合に支店コードを文字列で指定。数値はHTTP 400。
reference任意の対応付け文字列。空文字列もそのまま返し、省略した場合は結果でも省略。null・数値・配列等はHTTP 400。

文字列のコード形式不正は項目単位の invalid_code です。現実装ではnull項目・コードの省略/nullも空コードとして invalid_code になります。クライアントはコードを常に文字列で指定してください。

結果の読み方

HTTP 200は全項目の照合成功を意味しません。results は入力と同じ順序・件数です。index は0始まりの入力位置です。

status意味
found対象を取得できた。
bank_not_found形式は正しいが銀行が存在しない。
branch_not_found銀行は存在するが支店が存在しない（支店照合のみ）。
invalid_codeコード形式が不正。

found の銀行照合には bank、支店照合には bank と branch が入ります。branch_not_found には銀行情報が入ります。取得できない情報のフィールドは省略されます。

同一リクエスト内の形式が正しい同一コード（支店は銀行コードと支店コードの組）の再出現には、最初の入力位置を示す duplicateOf が付きます。不在のコードも重複対象です。形式不正の項目は重複判定しません。重複でも結果行を省略しません。duplicateOf: 0 は有効な値です。

次の例は架空のfixtureデータであり、現在の収録内容を保証しません。

{
  "dataVersion": "fixture-version",
  "datasetId": "fixture-dataset",
  "summary": {
    "requestedCount": 3,
    "validCount": 2,
    "uniqueLookupCount": 1,
    "duplicateCount": 1,
    "statusCounts": {"found": 2, "bankNotFound": 0, "branchNotFound": 0, "invalidCode": 1}
  },
  "results": [
    {"index": 0, "reference": "row-1", "bankCode": "0001", "status": "found", "bank": {"code": "0001", "name": "サンプル銀行"}},
    {"index": 1, "reference": "", "bankCode": "0001", "status": "found", "duplicateOf": 0, "bank": {"code": "0001", "name": "サンプル銀行"}},
    {"index": 2, "reference": "row-3", "bankCode": "1", "status": "invalid_code"}
  ]
}

validCount は形式が正しい件数で、不在と重複を含みます。uniqueLookupCount はそのうち一意なキー数、duplicateCount は再出現数です。statusCounts は重複を含む全結果行を数えます。dataVersion と datasetId は応答に使用したデータの識別子です。問い合わせ時には両方を保存してください。

エラーと再試行

HTTP主な意味・対応
400JSON不正、未知フィールド、型不正、items件数不正。入力を修正してください。
401 / 403キーまたは利用権限の問題。キー・契約状態を確認してください。
413本文が64 KiBを超過。件数やreferenceの長さを減らしてください。
429日次上限到達。上限の更新を待ち、即時連続再試行しないでください。
503データ未準備、またはGatewayの利用上限設定未反映等。一時停止し、応答ヘッダーを確認してください。

アプリケーションのエラーは {"error":{"code":"invalid_request","message":"..."}} 形式です。413のcodeは payload_too_large、アプリケーションの503は dataset_not_ready です。Gatewayのエラー本文はこの形式と異なる場合があります。利用上限設定を確認できない場合のGatewayの503には Retry-After: 1 が付きます。

通信切断・タイムアウトで結果が不明な場合、自動再送すると別リクエストとして再計上される可能性があります。リクエスト単位の冪等キーはありません。再試行する場合は回数・待機時間を制限し、エラーを記録してください。

利用回数・日次枠

入力件数や重複数によらず、1回のHTTPリクエストを1リクエストとして数えます。100項目の照合でも項目数に応じた追加料金は発生しません。

銀行・支店照合の2経路と同一アカウントの複数APIキーで日次枠を共有します。Search APIの利用枠とは別枠です。Batch Lookup専用の秒間上限は設けていません。日次上限到達時はHTTP 429になります。

失敗したリクエストについても日次枠の返還を保証しません。再送は新たなリクエストです。応答のレート制限ヘッダーを確認し、上限到達後の連続再試行を避けてください。

OpenAPI

リクエスト・レスポンスの機械可読仕様は OpenAPIリファレンス のBatch Lookup API v1、または OpenAPI YAML を参照してください。