swagger: "2.0"
info:
description: 銀行共通API
version: 0.5.0
title: 銀行共通API
tags:
- name: SystemAuth
description: "システム認証"
- name: UserAuth
description: "ユーザー認証"
- name: BankInfo
description: "銀行情報"
- name: AccountInfo
description: "口座情報"
- name: TransactionInfo
description: "取引情報"
securityDefinitions:
Bearer:
type: "apiKey"
name: "Authorization"
in: "header"
paths:
/auth/system_token:
post:
tags:
- SystemAuth
description: "システム認証用のアクセストークンを発行します。
アクセストークンは、APIの呼び出しごとに、システム全体でユニークかつランダムな文字列として生成します。
また、アクセストークンにはリクエスト元の「AP」と「認可した権限情報」を紐づけて保存します。
本APIの成功時も、既存のアクセストークンは継続して使用可能です。"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
api_key:
type: "string"
description: "APIキーを指定します。"
example: "apikey123456"
password:
type: "string"
description: "パスワードを指定します。"
example: "password123456"
grants:
type: "string"
description: "本認証において認可する権限を指定します。
複数の権限を指定する場合は「,」区切りとします。
ワイルドカードとして「*」を指定可能とします。
※権限の種別は、FGAPIでは定義しません。"
example: "read,write"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
access_token:
type: "string"
description: "発行されたアクセストークン。
有効期限は任意で、60分程度を推奨。"
example: "token123456"
created_at:
type: "integer"
description: "アクセストークンの生成時間。
UNIX時間で表記。"
example: "1577840400"
expired_at:
type: "integer"
description: "アクセストークンの期限切れ時間。
UNIX時間で表記。"
example: "1577844000"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
/auth/login:
get:
tags:
- UserAuth
description: "ブラウザに認証用のWeb画面を表示し、エンドユーザーの認証・認可を行います。
認証方法に指定はありません。ID・パスワード認証に加え、2要素認証やパズル認証等、任意の認証方法を使用可能です。
認証に成功した場合、認証トークンを生成し、クエリパラメータで指定されたコールバック先にリダイレクトします。
コールバック先には、GETパラメータ\"auth_token\"で認証トークンを通知します。
認証トークンは、APIの呼び出しごとに、システム全体でユニークかつランダムな文字列として生成します。
また、認証トークンには「認証したエンドユーザー情報」と「認可した権限情報」を紐づけて保存します。
コールバックの例) https://app-url.com/callback.html?auth_token=GiKsxaXsQsUJRbFcAFLetbib
※1)ユーザー認証の認証・認可の仕組みは、基本的に「OAuth 2.0 Authorization Framework (RFC6749)」に従います。
※2)本APIはHTMLで実装したWeb画面が必要です。"
consumes:
- "text/html"
produces:
- "text/html"
parameters:
- name: "api_key"
in: "query"
required: true
type: "string"
description: "APIキーを指定します。"
- name: "redirect_uri"
in: "query"
required: true
type: "string"
description: "リダイレクト先のURIを指定します。
認証サーバのドメイン名と異なる場合、HTTPレスポンスコード401が返却されます。"
- name: "grants"
in: "query"
required: false
type: "string"
description: "本認証において認可する権限を指定します。
複数の権限を指定する場合は「,」区切りとします。
ワイルドカードとして「*」を指定可能とします。
※権限の種別は、FGAPIでは定義しません。"
responses:
"200":
description: "成功"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
post:
tags:
- UserAuth
description: "/auth/login@GETの機能をRestAPIとして提供し、エンドユーザーの認証・認可を行います。
※ GET版と比較してセキュリティレベルが劣るため、このAPI の実装は必須ではありません。実装しない場合は、APIの呼び出し時にHTTPレスポンスコード404を返却してください。"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
api_key:
type: "string"
description: "APIキーを指定します。"
example: "apikey123456"
grants:
type: "string"
description: "本認証において認可する権限を指定します。
複数の権限を指定する場合は「,」区切りとします。
ワイルドカードとして「*」を指定可能とします。
※権限の種別は、FGAPIでは定義しません。"
example: "read,write"
id:
type: "string"
description: "ログインIDを指定します。
複数のIDを組み合わせる必要がある場合、任意の文字列で連結して送付します。(店番+口座番号など)"
example: "userid123456"
password:
type: "string"
description: "ログインパスワードを指定します。
複数のパスワードを組み合わせる必要がある場合、任意の文字列で連結して送付します。"
example: "userpassword123456"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
auth_token:
type: "string"
description: "認証トークン。
有効期限は任意で、3分以内を推奨。"
example: "token123456"
"400":
description: "Bad Request"
"404":
description: "Method Not Supported"
"500":
description: "Internal Server Error"
/auth/token:
post:
tags:
- UserAuth
description: "/auth/login@GETで認証したエンドユーザーに対応する、アクセストークンとリフレッシュトークンを発行します。
アクセストークン・リフレッシュトークンは、APIの呼び出しごとに、システム全体でユニークかつランダムな文字列として生成します。
また、アクセストークン・リフレッシュトークンには「認証したエンドユーザー情報」と「認可した権限情報」を紐づけて保存します。
本APIの成功時、既存のアクセストークンとリフレッシュトークンは即時に無効化されます。
※以降の各種APIでは、ここで発行したアクセストークンを認証キーとして使用します。"
consumes:
- "application/json"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
api_key:
type: "string"
description: "APIキーを指定します。"
example: "apikey123456"
password:
type: "string"
description: "パスワードを指定します。"
example: "password123456"
auth_token:
type: "string"
description: "/auth/login@GETのコールバック先が受け取った、認証トークンを指定します。"
example: "auth123456"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
access_token:
type: "string"
description: "発行されたアクセストークン。
有効期限は任意で、60分程度を推奨。"
example: "token123456"
created_at:
type: "integer"
description: "アクセストークンの生成時間。
UNIX時間で表記。"
example: "1577840400"
expired_at:
type: "integer"
description: "アクセストークンの期限切れ時間。
UNIX時間で表記。"
example: "1577844000"
refresh_token:
type: "string"
description: "発行されたリフレッシュトークン。
有効期間は任意で、180日程度を推奨。"
example: "refresh123456"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
put:
tags:
- UserAuth
description: "/auth/token@GETで発行したリフレッシュトークンから、アクセストークンとリフレッシュトークンを再発行します。
本APIの成功時、既存のアクセストークンとリフレッシュトークンは即時に無効化されます。
"
consumes:
- "application/json"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
api_key:
type: "string"
description: "APIキーを指定します。"
example: "apikey123456"
refresh_token:
type: "string"
description: "再発行対象のリフレッシュトークンを指定します。"
example: "refresh123456"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
access_token:
type: "string"
description: "発行されたアクセストークン。
有効期限は任意で、60分程度を推奨。"
example: "token123456"
created_at:
type: "integer"
description: "アクセストークンの生成時間。
UNIX時間で表記。"
example: "1577840400"
expired_at:
type: "integer"
description: "アクセストークンの期限切れ時間。
UNIX時間で表記。"
example: "1577844000"
refresh_token:
type: "string"
description: "発行されたリフレッシュトークン。
有効期間は任意で、180日程度を推奨。"
example: "refresh123456"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
delete:
tags:
- UserAuth
description: "アクセストークン・リフレッシュトークンを無効化します。
当該エンドユーザーからのアクセスを停止する際に使用します。
本APIの成功時、既存のアクセストークンとリフレッシュトークンは即時に無効化されます。"
consumes:
- "application/json"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
api_key:
type: "string"
description: "APIキーを指定します。"
example: "apikey123456"
refresh_token:
type: "string"
description: "削除対象のリフレッシュトークンを指定します。"
example: "refresh123456"
responses:
"200":
description: "成功"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
/branches:
get:
tags:
- BankInfo
description: "支店情報の一覧を取得します。"
consumes:
- "text/html"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "page"
in: "query"
type: "integer"
description: "取得対象のページ番号"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
bank_code:
type: "string"
description: "銀行コード"
example: "9999"
bank_name:
type: "string"
description: "銀行の名称"
example: "フィンテックガーデン銀行"
branches:
type: "array"
description: "支店情報のデータ一覧。
支店情報が0件の場合、空の配列を返却します。"
items:
type: object
properties:
id:
type: "string"
description: "支店情報のID。
すべての支店情報間でユニークであり、IDから支店情報を一意に特定できる必要があります。
※既存システム上にて複合キーで管理している場合、複合キーを連結した値をIDとして使用しても構いません。"
example: "999"
branch_code:
type: "string"
description: "支店コード"
example: "900"
branch_name:
type: "string"
description: "支店名"
example: "秋葉原支店"
branch_name_kana:
type: "string"
description: "支店名のフリガナ"
example: "アキハバラ"
address_code:
type: "string"
description: "支店の所在地コード。
総務省の規定する「都道府県コード及び市区町村コード」より、該当する「団体コード」を選択します。"
example: "131016"
tel:
type: "string"
description: "支店の電話番号。"
example: "0311112222"
params:
type: "object"
description: "パラメータ情報"
properties:
page:
type: "integer"
description: "取得対象のページ番号。"
example: "3"
next_page:
type: "integer"
description: "次ページのページ番号。
次ページが存在しない場合は「0」とします。"
example: "4"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
/accounts:
get:
tags:
- AccountInfo
description: "エンドユーザーが保有する、口座情報の一覧を取得します。
クレジットカード情報が含まれる場合、クレジットカードの情報も独立した口座として扱うことが可能です。
口座情報の件数が多い場合、レスポンスは200件/ページでページングされます。"
consumes:
- "text/html"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "page"
in: "query"
type: "integer"
description: "取得対象のページ番号"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
bank_code:
type: "string"
description: "銀行コード"
example: "9999"
bank_name:
type: "string"
description: "銀行の名称"
example: "フィンテックガーデン銀行"
accounts:
type: "array"
description: "口座情報のデータ一覧。
口座情報が0件の場合、空の配列を返却します。"
items:
type: object
properties:
id:
type: "string"
description: "口座情報のID。
すべての口座情報間でユニークであり、IDから口座番号を一意に特定できる必要があります。
※既存システム上にて複合キーで管理している場合、複合キーを連結した値をIDとして使用しても構いません。"
example: "10099"
account_number:
type: "string"
description: "口座番号
口座番号を非公開にする場合、全体もしくは一部を*等でマスクしても良い。"
example: "999999999"
owner_type:
type: "string"
description: "口座の保有者の種別を表す。
・c:法人
・p:個人"
example: "c"
account_type1:
type: "string"
description: "口座の大分類を表す。
・bank:銀行口座
・cc:クレジットカード口座"
example: "bank"
account_type2:
type: "string"
description: "普通預金、当座預金などの、口座の中分類を表す。
任意の値を返却可能ですが、預金口座である場合は、以下の値を推奨します。
・普通:普通預金の場合
・当座:当座預金の場合
・総合:総合預金の場合
・定期:定期預金の場合"
example: "普通"
account_type3:
type: "string"
description: "システム予約。
常に空欄となります。"
example: ""
branch_code:
type: "string"
description: "口座の所属する支店コード。"
example: "900"
branch_name:
type: "string"
description: "口座の所属する支店名。"
example: "秋葉原支店"
params:
type: "object"
description: "パラメータ情報"
properties:
page:
type: "integer"
description: "取得対象のページ番号。"
example: "3"
next_page:
type: "integer"
description: "次ページのページ番号。
次ページが存在しない場合は「0」とします。"
example: "4"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
/transactions:
get:
tags:
- TransactionInfo
description: "指定した期間内の取引明細の一覧を取得します。"
consumes:
- "text/html"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "account_id"
in: "query"
required: true
type: "string"
description: "取得対象の口座ID。"
- name: "start_date"
in: "query"
required: true
type: "string"
format: date
description: "取得対象とする取引日の開始日。
指定した日付も取得対象に含みます。"
- name: "end_date"
in: "query"
required: true
type: "string"
format: date
description: "取得対象とする取引日の終了日。
指定した日付も取得対象に含みます。"
- name: "page"
in: "query"
type: "integer"
description: "取得対象のページ番号"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
transactions:
type: "array"
description: "取引明細のデータ一覧。
取得対象の取引明細が0件の場合は、空の配列を返却します。
※取り消された取引明細は返却対象から除外してください。"
items:
type: object
properties:
id:
type: "string"
description: "取引明細のID。
すべての取引明細間でユニークであり、IDから取引明細を一意に特定できる必要があります。
※既存システム上のIDと同一の値である必要はありません。"
example: "2000150"
date:
type: "string"
format: date
description: "取引日
。
書式はISO8601の拡張形式に従います。"
example: "2020-01-10T13:15:35+09:00"
amount:
type: "integer"
description: "金額。
入金の場合は正の値、出金の場合は負の値とします。"
example: "-108000"
description:
type: "string"
description: "取引内容。
振込人名義や摘要など、エンドユーザーが取引内容を理解できる値を返却します。"
example: "カブ)フィンテックガーデン"
balance:
type: "integer"
description: "取引終了時点における口座残高。"
example: "950000"
params:
type: "object"
description: "パラメータ情報"
properties:
account_id:
type: "string"
description: "取得対象の口座ID。"
example: "10099"
start_date:
type: "string"
format: date
description: "取得対象の開始日。"
example: "2020-10-01"
end_date:
type: "string"
format: date
description: "取得対象の開始日。"
example: "2020-10-31"
page:
type: "integer"
description: "取得対象のページ番号。"
example: "3"
next_page:
type: "integer"
description: "次ページのページ番号。
次ページが存在しない場合は「0」とします。"
example: "4"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"
/balances:
get:
tags:
- TransactionInfo
description: "指定した期間内の日次の残高情報を取得します。
日次の残高とは、当該の日付中で、最後の取引後の残高を指します。"
consumes:
- "text/html"
produces:
- "application/json"
security:
- Bearer: []
parameters:
- name: "account_id"
in: "query"
required: true
type: "string"
description: "取得対象の口座ID。"
- name: "start_date"
in: "query"
required: true
type: "string"
format: date
description: "取得対象とする取引日の開始日。
指定した日付も取得対象に含みます。"
- name: "end_date"
in: "query"
required: true
type: "string"
format: date
description: "取得対象とする取引日の終了日。
指定した日付も取得対象に含みます。"
- name: "page"
in: "query"
type: "integer"
description: "取得対象のページ番号"
responses:
"200":
description: "成功"
schema:
type: "object"
properties:
balances:
type: "array"
description: "口座情報のデータ一覧。
口座情報が0件の場合、空の配列を返却します。"
items:
type: object
properties:
date:
type: "string"
format: date-time
description: "残高の取得対象の日付。
書式はISO8601の拡張形式に従います。
例)2020-01-10T13:15:35+09:00"
example: "2020-01-10T13:15:35+09:00"
balance:
type: "integer"
description: "date中、最後の取引後の残高。"
example: "53000000"
params:
type: "object"
description: "パラメータ情報"
properties:
account_id:
type: "string"
description: "取得対象の口座ID。"
example: "10099"
start_date:
type: "string"
format: date
description: "取得対象の開始日。"
example: "2020-10-01"
end_date:
type: "string"
format: date
description: "取得対象の開始日。"
example: "2020-10-31"
page:
type: "integer"
description: "取得対象のページ番号。"
example: "3"
next_page:
type: "integer"
description: "次ページのページ番号。
次ページが存在しない場合は「0」とします。"
example: "4"
"400":
description: "Bad Request"
"500":
description: "Internal Server Error"