銀行エンジニアリング 30：資源APIと振込の「依頼」（範囲・所有者検査・冪等）

Level 1 基礎：アプリが読めるのは、同意された範囲の、本人の情報だけ

トークンがあっても、何でも読めるわけではありません。読む前に、次を毎回確かめます。

①トークンが有効か。②その同意がまだ有効か（取り消されていないか）。③アプリが停止されていないか。④必要な範囲が同意されているか。⑤読もうとしている口座が、その顧客のものか。

Level 2 銀行業務：依頼と承認を分ける

第三者のアプリは、顧客に代わって『この人に1,500円送りたい』と依頼できます。しかし、実際にお金を動かすのは、顧客がMiniBankの画面で内容を確かめ、ワンタイムコード（TOTP）で承認したときだけです。アプリの依頼だけでは、資金は1円も動きません。

依頼の状態は、PENDING_CUSTOMER_APPROVAL（顧客の承認待ち）、COMPLETED、FAILED、EXPIRED、CANCELLEDなどです。顧客が何もしなければ期限で EXPIRED になります。

Level 3 システム：MiniBankでの実装

• public.ob_gateway は匿名でも呼べる入口だが、openbanking.resolve_token が毎回、トークン→同意→顧客とクライアントの状態を確かめる。無効なトークンはすべて OB010、範囲の不足は OB011。他人の口座IDは『見つからない』（OB030）
• 振込の依頼（openbanking.initiate_transfer）は、既存の public.request_transfer を呼ぶ。限度額・KYC・宛先の検査・呼出し回数の制限・冪等性は、既存の契約のまま。API側では再実装しない
• 同じ Idempotency-Key と同じ内容は、元の依頼をそのまま返す。同じキーで内容が違えば OB020（409）。新しいキーで再依頼しない
• 依頼の状態はイベント（transfer.initiated、transfer.status_changed）として、状態の変更と同じトランザクションで記録する
• アプリは依頼の承認も取消もできない。承認のAPIは存在せず、承認は顧客の既存の操作だけ
• トークンは監査ログにも残さない。監査には client と consent の識別子を入れ、外部アプリ経由であること（via=open_banking）も残す
• 1つの同意が残せる未承認の依頼は3件まで（OB021）。外部のアプリが、顧客本人の振込の依頼枠（1分5件）を使い切れないようにするため
• 同意が失効したあとは、そのアプリの依頼の状態変更をイベントにしない（顧客の承認は通常どおり完了する）

異常時：依頼の応答が届かなかった

Level 4 アーキテクチャ：既存の契約を再利用する

新しい入口ができるたびに、限度額やKYCの検査を作り直すと、入口ごとに抜けが生まれます。MiniBankは、外部からの依頼も、顧客本人が画面から行う依頼と同じ関数を通します。検査は1か所にあり、テストも1か所です。

どこを確認すればよいか

• 管理画面「Open Banking」の同意とイベント
• 顧客画面「振込の依頼と結果」（/app/transfer/requests）：アプリが依頼した振込を、認証アプリ（TOTP）で承認する。心当たりのない依頼は承認せず、期限で失効させる