こんにちは。KYです。
現在は会計システムの開発に携わっています。
銀行法の改正で金融機関の許可のないスクレイピングが禁止されて数年が経ちました。
APIの利用も一般的になっており今更解説することもあまりないような気はしますが、ちょっと概要などを書いてみようと思います。
業務で担当した範囲でのまとめになりますので至らない部分もあるかと思いますが、初心者用の超概要くらいの感覚で見て頂けると幸いです。
APIとは
APIは「アプリケーション・プログラミング・インターフェース」の略で、銀行等が外部にデータを連携するための仕様を公開したものです。
プログラマの皆様は普段のプログラミングでクラスの仕様を調べるのにAPIリファレンスを参照していると思いますがそれと同じようにインプット、アウトプットの仕様がまとめられており、金融機関のサーバとリクエスト、レスポンスの形でやりとりをします。
NTTデータのOpenCanvasや三菱UFJ銀行のAPI開発者ポータルなどを調べてみると開発者向けに公開された仕様が見られるので雰囲気が掴めると思います。
銀行APIだと大体、照会系、振込系、認証系の3種類のAPIがあります。
照会系API
ユーザの持っている口座情報、残高情報、取引明細情報などを照会する機能です。
大抵はGETで、URLに照会対象となるアカウントIDや照会期間等のパラメータを指定して該当データをリクエストします。
リクエストヘッダにAPIを使うための詳細情報（後述するアクセストークン等）を指定したりもします。
ヘッダやレスポンスボディはJSON形式が多いので実装の際はレスポンスに合わせたモデルを作っておくと受領した情報を扱いやすくなります。
また、json-serverを使って各APIのモックを作ると手元でAPI接続のテストが出来て便利です。
振込系API
銀行によっては振込依頼をAPI経由で出来たりもします。
振込先の口座情報や名義の指定に間違いがないか、エラー発生時の対処等、照会系に比べて少し気を付けるところが多くなります。
認証系API
APIの利用する際には、認可されたリクエストだと分かるようにアクセストークンが必要になります。
アクセストークンは認証系APIを使って発行します。
アクセストークンの発行にはOAuthという仕組みが良く使われていて、Rubyだとoauth2というGemを使って実装したりします。
処理の流れは以下のようになります。
- 利用者がアプリケーションの認証ボタンを押して
- API連携認証APIを呼び出す
主に以下のようなパラメータを指定する
- クライアントID：API利用契約をした事業者に発行されるID
- リダイレクトURL：認証後にアプリケーション側に戻ってくるときのURL（手順5の戻り先）
- スコープ：認可対象機能の指定（口座照会、取引明細照会、等） - ログイン画面のようなページにリダイレクトされて
- ID/Password等を入力して認証を行う
- 認証が成功するとアプリケーションに認可コードが返され
- それを使ってアクセストークン発行APIを呼び出し
- アクセストークンとリフレッシュトークンが発行される
- アクセストークン：各種APIを実行するときに使用。有効期限は短いことが多い
- リフレッシュトークン：アクセストークンの再発行に使用。こちらの有効期限は長めで、期限が切れたら認可をやり直すことになる
APIを使う際に気を付けること
最後に銀行APIを使う際の注意点などを挙げてみます。
一部はAPIに限った話でもないかもしれません。
- 取引に関わる日付の違いに注意する
銀行系だと起算日と勘定日を混同しやすく、APIの照会期間にはどちらの日付を指定するのか等を把握しておかないと期待した情報が取れません。 - APIですべての取引が照会できるか
口座一覧照会ではどんな種別の口座が照会対象になるか、取引明細の照会期間は何カ月前まで指定できるか、1リクエストでの上限件数など。
上限オーバーしたときの続きの取り方は金融機関ごとに結構違いがあります（取引IDを指定したり、next_flagのようなものを次のリクエストに渡したり） - 項目名とデータ形式がイメージ通りでない場合がある
日付項目だとYYYY/MM/DD形式とか、金額項目だと数値が来ると思い込みがちですが「M月D日」のような形式だったり、金額にカンマや円を含んだ文字列だったりすることもあります。
場合によっては通帳で見るような入金額、出金額の使われなかった方に取引内容の文字列が返されることもあります。
（インターネットバンキングで表示される形で来ることが多い印象） - API呼び出しのログは大事
APIではエラー原因の切り分けが難しく金融機関への問い合わせが必要になる場面があるため、リクエスト、レスポンスのログは必須です。
リクエストを特定する情報（リクエストIDや時間など）も問い合わせの際に求められることが多いです。
特に認可処理に関しては金融機関側の動作環境（ブラウザの制限等）も影響してくるためUser-Agentも残しておくと便利です。 - 情報の管理はしっかり
ログファイルも含めて取得した情報の管理もきちんと考慮しましょう。
リクエストに含まれるアクセストークンは漏洩すると不正なAPI利用をされてしまう恐れがありますし、レスポンスは個人情報のかたまりなので誰でも自由に見れて良いものではありません。 - 未知のエラーを想定しておく
現実問題としてすべてのエラーパターンを仕様書に載せるのは難しく、原因不明のエラーは発生します。
万が一に備えて安全に落ちるロジックを組みましょう（取引明細照会APIを繰り返し呼ぶ処理などで無限ループにならないように構える、等）
