Master Export API

銀行・支店マスタの全件データを取得する

Master Exportは、ご契約で許諾されたサービスで利用する銀行・支店マスタの全件ZIPを取得するAPIです。GET /master/v1/latest で公開データを確認し、必要な場合は POST /master/v1/download-url で期限付きURLを発行してZIPをダウンロードします。お客様のシステムへの取り込みは、お客様側で行います。

概要・利用条件

GET /master/v1/latest で最新データセットの dataset_id、件数、ZIPのSHA-256を取得します。
保存済みの dataset_id と異なる場合、POST /master/v1/download-url にそのIDを渡します。
返された download_url から期限内にZIPを取得し、内容を確認してからお客様のマスタデータに反映します。

両APIのベースURLは https://apis.bankcode-jp.com です。契約アカウントのAPIキーを x-api-key ヘッダーで指定してください。Master Exportの契約と利用権限が必要です。APIキーや署名付きURLをブラウザ、公開コード、ログ、問い合わせ文に残さないでください。

契約対象となるサービス、利用環境、料金、上限はOfferで確認してください。利用するには、お客様のアカウントでMaster Export契約が有効化されている必要があります。BankcodeJP API利用規約とMaster Export商品利用特約も参照してください。

データの更新には新しい全件ZIPを取得し、お客様のシステムへ取り込んでください。Change History APIを使った差分更新は前提にしていません。

GET /master/v1/latest

現在公開済みのデータセットについて、ZIPの検証に使うメタデータを返します。リクエストボディはありません。

curl -sS "https://apis.bankcode-jp.com/master/v1/latest" \
  -H "x-api-key: YOUR_API_KEY"

リクエストヘッダー	必須	用途
`x-api-key`	必須	契約アカウントのAPIキー
`If-None-Match`	任意	前回受け取った `ETag` をそのまま指定

200 OK の場合はJSONと ETag: "<dataset_id>" を返します。

フィールド	型	内容
`dataset_id`	string	公開データセットの識別子。前回保存したIDとの一致で更新を判定します。
`history_through_update_id`	string	作成時に取り込み済みだった更新ID。
`generated_at`, `published_at`	string (date-time)	生成日時、公開日時。時刻はUTCのISO 8601形式です。
`zip_sha256`	string	ダウンロードするZIPファイル全体のSHA-256（16進64文字）。
`zip_size_bytes`	integer	ZIPのサイズ（バイト）。
`bank_row_count`, `branch_row_count`	integer	CSVのデータ行数（ヘッダーを除く）。

If-None-Match が現在のETagと完全一致した場合は 304 Not Modified を返し、レスポンスボディはありません。dataset_id を文字列として大小比較して新旧判定しないでください。

POST /master/v1/download-url

指定した公開済みデータセットのZIPを取得するための署名付きURLを発行します。

curl -sS "https://apis.bankcode-jp.com/master/v1/download-url" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"dataset_id":"work_20260924_075613_ok"}'

リクエスト	必須	内容
`x-api-key` ヘッダー	必須	契約アカウントのAPIキー。
`Content-Type: application/json`	必須	JSONを送信。
`dataset_id` 本文	必須	GETで得た公開済みID。本文にはこの項目以外を含めないでください。
`x-request-id` ヘッダー	任意	追跡用ID。指定しない場合はサーバーが生成します。

200 OK で次の値を返します。

フィールド	型	内容
`issuance_id`	string (UUID)	URL発行記録の識別子。
`dataset_id`	string	発行対象のデータセットID。
`download_url`	string (URI)	ZIPのGETに使う一時URL。URLそのものが認証情報です。
`expires_at`	string (date-time)	そのURLの失効時刻。発行から約10分の設定で運用中です。常に応答値を優先してください。

同じ dataset_id を再送すると別の発行としてカウントされます。URLが期限切れになった場合は、必要な分だけ再発行してください。発行数には日次の上限があります。

ZIPの取得・検証

返された download_url に期限内に GET し、ZIPを保存します。ダウンロード時はBankcodeJP APIの x-api-key ヘッダーを付けないでください。

curl -sS --fail --output master-export.zip "$DOWNLOAD_URL"

このURLを外部のログ・監視データへ送信しないでください。期限切れやダウンロード失敗時はURLの再発行が必要です。

ZIP内のファイル	内容
`banks.csv`	`bank_code, bank, bank_half_kana, bank_full_kana, bank_full_hira, business_type_code, business_type`
`branches.csv`	`bank_code, branch_code, branch, branch_half_kana, branch_full_kana, branch_full_hira`
`manifest.json`	`schema_version` = 1、`dataset_id`、`generated_at`、`effective_at`、`history_through_update_id`、各CSVの `row_count` と `sha256`。

CSVはUTF-8、BOMなし、CRLF、ヘッダー付きです。銀行コード・支店コードは先頭ゼロを保持するため文字列として読み込んでください。

ZIPのバイト数とSHA-256を GET /master/v1/latest の zip_size_bytes / zip_sha256 と照合します。
ZIPの展開とCRCを確認し、manifest.json の dataset_id が要求したIDと一致することを確認します。
確認済みのZIPをお客様のシステムに取り込みます。ZIPの確認や取込処理でエラーが発生した場合は、新しいデータを利用せず、原因を確認してください。

BankcodeJPはZIPの生成時に銀行・支店コードの重複を検査し、CSVの行数を manifest.json に記録します。お客様側では、取得したZIPがAPIの示したファイルと一致することを確認してください。

利用制限

利用上限の回数は契約時のOfferで定めます。お客様に適用される上限はOfferと管理画面で確認してください。以下は各APIに適用される制限の種類です。

制限	`GET /master/v1/latest`	`POST /master/v1/download-url`
1秒あたりのAPI呼び出し回数（両API共通枠）	対象	対象
1日あたりのAPI呼び出し回数（両API共通枠）	対象	対象
1日あたりのダウンロードURL発行回数（POST専用枠）	対象外	対象

共通枠はGETとPOSTの合計です。POSTは共通枠に加えて日次URL発行枠も使用します。日次上限はUTC 00:00（日本時間09:00）に切り替わります。

上限と残枠は X-RateLimit-Limit-Second、X-RateLimit-Remaining-Second、X-RateLimit-Limit-Day、X-RateLimit-Remaining-Day に表示されます。POSTにはさらに X-RateLimit-Limit-Download-Url-Day、X-RateLimit-Remaining-Download-Url-Day が表示されます。429 の場合は Retry-After があれば従い、日次残枠が0なら次のUTC日まで待ってください。

エラーと再試行

HTTP	主な意味	対応
`200`	メタデータ取得またはURL発行成功	返却値を照合してください。
`304`	`If-None-Match` と最新ETagが一致	ZIPの再取得は不要です。
`401`	APIキーなし・無効、認証済みアカウント識別子の欠落	キーと契約アカウントを確認してください。
`403`	Master Export利用権限なし	契約・有効化・APIキーの権限を確認してください。
`404`	公開済みの対象データセットなし	最新の `dataset_id` を再取得してください。
`422`	POST本文の不正	JSONに `dataset_id` のみを指定してください。
`429`	API呼び出し回数またはURL発行回数の上限超過	残枠と `Retry-After` を確認してください。
`503`	一時的に利用不可	時間を置いて再試行してください。

エラー本文の形式はGatewayなど発生箇所で異なります。HTTPステータスを基準に処理し、APIキーとURLを含む診断ログは残さないでください。