外部連携API 共通仕様
外部システム連携APIに共通仕様を以下に示す。
1. 認証
外部システム連携APIではOAuth2.0を使用した認証を行う。
認証が成功するとアクセストークンが取得できる。アクセストークンはリクエストヘッダ情報の「Authorization」に設定する。
アクセストークンの取得方法については以下の資料を参照。
インフォマートAPI利用におけるOAuth2.0による認証手順（PDF）
2. リクエスト
2.1. HTTPメソッド
GET、POST、PUTのいずれを指定する。
指定するメソッドは各APIの仕様を参照。
2.2. ヘッダ情報
ヘッダ情報には下記の値を指定する。
「Authorization」は必須指定項目。
「Content-type」はHTTPメソッドがPOSTとPUTの場合、必須指定項目。
| キー | 設定値 | 備考 |
|---|---|---|
| Authorization | Bearer + アクセストークンex) Bearer 1234a567-b890-1c23-4567-89d01e2f3a45 | 認可情報を設定する。 認証時に取得したアクセストークンをBearerに付加し設定する。 |
| Content-type | application/json | HTTPメソッドがPOST,PUTの場合、ボディ情報の形式を設定する。 ボディ情報がJSON形式の場合は「application/json」、XML形式の場合は「text/xml」を設定する。 |
| text/xml | ||
| Accept | application/json | レスポンスで受信する形式を設定する。 JSON形式で受信する場合は「application/json」、XML形式で受信する場合は「text/xml」を設定する。 当項目を指定する際はクエリ文字列やボディ情報の「レスポンス形式（response_type）」と合わせる必要がある。 当項目はクエリ文字列やボディ情報が不正だった場合（JSONのカンマやXMLのタグの漏れなど）、クエリ文字列やボディ情報の「レスポンス形式（response_type）」が不正だった場合に適用される。 |
| text/xml |
2.3. クエリ文字列
HTTPメソッドがGETの場合は、URLにパラメータをクエリ文字列として付加し、リクエストする。
その際のパラメータは文字コードを「UTF-8」にし、適切にURLエンコードすること。
レスポンスのボディ形式を決定する「レスポンス形式（response_type）」は下記の値を設定する。
その他項目は各APIの仕様を参照。
| パラメータ名 | 設定値 | 備考 |
|---|---|---|
| response_type | json | レスポンスのボディ形式をJSON形式にする。 |
| xml | レスポンスのボディ形式をXML形式にする。 |
2.4. ボディ情報
HTTPメソッドがPOST,PUTの場合は、ボディ情報にパラメータを設定し、リクエストする。
パラメータはJSON形式またはXML形式で設定する。
その際のパラメータは文字コードを「UTF-8」にすること。
レスポンスのボディ形式を決定する「レスポンス形式（response_type）」は下記の値を設定する。
その他項目は各APIの仕様を参照。
| パラメータ名 | 設定値 | 備考 |
|---|---|---|
| response_type | json | レスポンスのボディ形式をJSON形式にする。 |
| xml | レスポンスのボディ形式をXML形式にする。 |
2.5. 利用不可文字
クエリ文字列、ボディ情報には以下の文字は使用できない。含まれていた場合、自動で除去を行う。
| 利用不可文字 | ||
|---|---|---|
| % | パーセント | |
| ^ | キャレット | |
| * | アスタリスク | |
| ( | ) | 丸括弧 |
| [ | ] | 角括弧 |
| < | > | 山括弧 |
| ' | シングルクォーテーション | |
| " | ダブルクォーテーション | |
| \t | タブ | |
3. レスポンス
3.1. HTTPステータスコード
HTTPステータスコードとAPIの実行結果の関係は以下のとおり。
| No | HTTPステータスコード | エラーの内容 |
|---|---|---|
| 1 | 200（ok） | 成功。 |
| 2 | 400（Bad request） | リクエストが不正 ex)JSON/XMLの書式不正やJSON/XMLに必要な要素が記述されていない。 |
| 3 | 401（Unauthorized） | 認証エラー ex)アクセストークンの不正や期限切れ。 |
| 4 | 403 (Forbbiden) | 権限なしエラー ex)有料会員の資格なし。 |
| 5 | 404（Not Found） | リソースなし ex)URLに誤りがある。 |
| 6 | 405（Method Not Allowed） | 許可されていないメソッド ex)POSTが許可されていないURIに対してPOSTメソッドを利用する。 |
| 7 | 415(Unsupported Media Type) | サポートしていないメディアタイプ ex)リクエストヘッダ情報の「Content-type」に「application/json」、「text/xml」以外を設定した。 |
| 8 | 500（Internal Server Error） 502（Bad Gateway ） |
サーバー内部エラー ex)サーバーの内部的な問題で処理が完了しない。 発生時はシステム管理者にお問い合わせください。 |
| 9 | 503（Service unavailable） | サービス利用不可 ex)メンテナンス中のため要求を受け付けられない。 |
3.2.ヘッダ情報
ヘッダ情報には下記の値が返却される。
| ヘッダ名 | 設定値 | 備考 |
|---|---|---|
| Content-type | application/json; charset=UTF-8 | ボディ情報がJSON形式の場合、設定される。 |
| text/xml; charset=UTF-8 | ボディ情報がXML形式の場合、設定される。 |
3.3.ボディ情報
ボディ情報の形式はリクエストのクエリ文字列（GETの場合）またはボディ情報（POST,PUTの場合）の 「レスポンス形式（response_type）」によって決定される。
リクエストのクエリ文字列またはボディ情報が不正だった場合（JSONのカンマやXMLのタグの漏れなど）や クエリ文字列またはボディ情報の「レスポンス形式（response_type）」が不正だった場合、 リクエストのヘッダ情報の「Accept」によって決定される（「Accept」が未設定ならJSON形式）。
3.3.1.JSON形式
基本フォーマットは以下のとおり。
| 要素名・階層 | 要素内容 | 型 | 備考 |
|---|---|---|---|
| result | 処理結果 | 文字列 | 成功時:"ok" 失敗時:"ng" |
| error_list[] | エラーリスト | 配列 | 成功時:null 失敗時:以下の要素を設定 ※エラーリストは複数件出力されることもある |
| error_item | エラー項目名 | 文字列 | 特定の項目に紐付かないエラーの場合はnull |
| error_code | エラーコード | 文字列 | エラーメッセージ一覧参照 |
| error_detail | エラー内容 | 文字列 | エラーメッセージ一覧参照 |
結果サンプル （便宜上、コメントや改行・空白を入れている。）
{
"result" : "ng",
"error_list" : [{
"error_item" : null,
"error_code" : "E100006",
"error_detail" : "請求書書式設定が取得できません。"
}, {
"error_item" : "details",
"error_code" : "E000021",
"error_detail" : "明細情報は1000件以内にしてください。"
}, {
"error_item" : "depositor_kana",
"error_code" : "E000023",
"error_detail" : "預金者名カナは半角カナ大文字、半角英数字記号30文字以内で入力してください。"
}]
}
3.3.2.XML形式
基本フォーマットは以下のとおり。
| 要素名・階層 | 要素内容 | 型 | 備考 |
|---|---|---|---|
| result | 処理結果 | 文字列 | 成功時:"ok" 失敗時:"ng" |
| error_list[] | エラーリスト | 配列 | 成功時:ブランク 失敗時:以下の要素を設定 ※エラーリストは複数件出力されることもある |
| error_item | エラー項目名 | 文字列 | 特定の項目に紐付かないエラーの場合はnull |
| error_code | エラーコード | 文字列 | エラーメッセージ一覧参照 |
| error_detail | エラー内容 | 文字列 | エラーメッセージ一覧参照 |
結果サンプル （便宜上、コメントや改行・空白を入れている。）
<?xml version="1.0" encoding="UTF-8"?>
<DataRoot>
<result>ng</result>
<error_list>
<error_item />
<error_code>E100006</error_code>
<error_detail>請求書書式設定が取得できません。</error_detail>
</error_list>
<error_list>
<error_item>details</error_item>
<error_code>E000021</error_code>
<error_detail>明細情報は1000件以内にしてください。</error_detail>
</error_list>
<error_list>
<error_item>depositor_kana</error_item>
<error_code>E000023</error_code>
<error_detail>預金者名カナは半角カナ大文字、半角英数字記号30文字以内で入力してください。</error_detail>
</error_list>
</DataRoot>
注）XMLの場合は、レスポンスでnullが設定される箇所はブランクをリターンする。
上記のサンプルだと、5行目の
