公開API仕様（銀行・支店マスタAPI）

ginconnectが外部提供する銀行・支店マスタ取得APIの仕様。

注意: 旧ドキュメントサイト（docs.ginconnect.jp）は廃止予定です。旧サイトの記載は旧ginconnectの仕様のままで現行のAPIと差異があります（末尾の一覧を参照）。本ページが現行の正となる仕様です。

共通仕様

• ベースURL: https://api.ginconnect.jp

• メソッド: GETのみ

• 文字コード: UTF-8（レスポンスはJSON。sheet系のみ text/plain）

• CORS: 全オリジン許可

• レートリミット: IPごとに15分あたり100リクエスト。超過時は 429 と以下を返す:

  { "success": false, "error": { "message": "Too many requests", "retryAfter": 900 } }
  

認証

/v1/banks 系はAPIキー認証が必須。APIキーは会員ページから発行する（gk_ プレフィックス）。

• キーが無い・無効・有効期限切れの場合は 401
• 有効なサブスクリプション（active / trialing）が無いユーザーのキーは 402
• キーに許可オリジンが設定されている場合、許可リスト外の Origin ヘッダー付きリクエストは 403（Origin ヘッダーの無いサーバー間通信は制限対象外）

ページング

レスポンスの data.pagination にページング情報が入る:

{ "page": 1, "limit": 100, "total": 1234, "hasMore": true }

• data.count はそのページに含まれる件数、総件数は data.pagination.total。

filter パラメータ

絞り込み条件を フィールド:値 形式で指定する。複数条件はカンマ区切り（AND条件）。

GET /v1/banks?filter=code:0001
GET /v1/banks?filter=name:みずほ*,code:00*

対応フィールド:

ワイルドカード:

• ワイルドカードを含まない値は完全一致
• マッチングは大文字小文字を区別しない
• 未対応フィールドや形式不正の条件は無視される（エラーにはならない）

エンドポイント

GET /v1/banks — 金融機関一覧

クエリ: page / limit / filter（上記共通仕様）

レスポンス（200）:

{
  "success": true,
  "data": {
    "banks": [
      {
        "code": "0001",
        "name": "みずほ銀行",
        "katakana": "ミズホギンコウ",
        "hiragana": "みずほぎんこう",
        "halfKatakana": "ﾐｽﾞﾎｷﾞﾝｺｳ"
      }
    ],
    "count": 1,
    "pagination": { "page": 1, "limit": 100, "total": 1, "hasMore": false }
  },
  "metadata": { "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/banks/{code} — 金融機関詳細

• {code}: 4桁数字の金融機関コード。形式不正は 400 INVALID_PARAMETER、存在しない場合は 404 NOT_FOUND

レスポンス（200）:

{
  "success": true,
  "data": { "bank": { "code": "0001", "name": "みずほ銀行", "katakana": "...", "hiragana": "...", "halfKatakana": "..." } },
  "metadata": { "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/banks/{code}/branches — 支店一覧

• {code}: 4桁数字の金融機関コード。形式不正は 400、銀行が存在しない場合は 404
• クエリ: page / limit / filter（code は3桁の支店コード）

レスポンス（200）:

{
  "success": true,
  "data": {
    "branches": [
      {
        "code": "001",
        "name": "東京営業部",
        "katakana": "トウキョウエイギョウブ",
        "hiragana": "とうきょうえいぎょうぶ",
        "halfKatakana": "ﾄｳｷｮｳｴｲｷﾞｮｳﾌﾞ"
      }
    ],
    "count": 1,
    "pagination": { "page": 1, "limit": 100, "total": 1, "hasMore": false }
  },
  "metadata": { "bankCode": "0001", "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/sheet/bank — Excel / Spreadsheet向け 金融機関単一値取得

セル関数（WEBSERVICE / IMPORTDATA 等）からの利用を想定した、単一値を text/plain で返すAPI。

• 成功時: 指定フィールドの値を text/plain で返す。フィールドの値が空文字の場合は空文字をそのまま返す（#N/A にはしない）。フィールドが欠落している（undefined / null）場合のみ 200 + #N/A を返す
• 失敗時: ステータス（401 / 402 / 403 / 400 / 404 / 500）に応じて本文は常に #N/A（セル関数でエラー値として扱えるようにするため）
• APIキーに許可オリジンが設定されている場合、許可リスト外の Origin ヘッダー付きリクエストは 403 + #N/A で拒否される（/v1/sheet/banks/{code}/branch も同様）。Origin ヘッダーが付かないリクエスト（curl / Excel / Google Spreadsheet 等のサーバー間・アプリ間通信）は従来どおり利用できる
• 例外: レートリミット超過（429）時はsheet系でも #N/A ではなく共通仕様のJSON形式で返る

GET /v1/sheet/banks/{code}/branch — Excel / Spreadsheet向け 支店単一値取得

• {code}: 金融機関コード
• クエリは /v1/sheet/bank と同じ（code は支店コード、name は支店名の部分一致）

GET /health — ヘルスチェック

認証不要。{ "success": true, "message": "...", "timestamp": "...", "version": "..." } を返す。

エラーレスポンス

/v1/banks 系のエラーは原則以下の形式:

{ "success": false, "error": { "code": "エラーコード", "message": "説明" } }

※ 認証エラー（401/402/403）は {"error": "メッセージ"} という簡略形式で、他と形が揃っていない。

旧ドキュメント（docs.ginconnect.jp）との差異

旧ドキュメントサイトは旧ginconnectの仕様のまま廃止予定。旧サイトを参照していた利用者向けに、現行仕様との差異をまとめる: