共通リファレンス (1.0.0)

Download OpenAPI specification:Download

API 共通仕様

外部システム連携 API の共通仕様を以下に示す。

概要

API を利用する際の共通仕様は以下のとおりです。

項目	説明
プロトコル	`HTTPS`
ポート	`443`
文字コード	`UTF‒8`
タイムアウト	`300` 秒

認証

外部システム連携 API では OAuth2.0 を使用した認証を行う
認証が成功するとアクセストークンが取得できる
アクセストークンはリクエストヘッダ情報の「Authorization」に設定する
アクセストークンの取得方法については以下の資料を参照
- インフォマート API 利用における OAuth2.0 による認証手順（PDF）

リクエスト

1. HTTP メソッド

GET,POST,PUTのいずれかを指定する
指定するメソッドは各 API の仕様を参照

2. ヘッダ情報

ヘッダ情報には下記の値を指定する

キー	値	必須
`Authorization`	`Bearer` + アクセストークン	`○`
`Content-type`	`application/json` or `text/xml`	`POST` or `PUT`の場合`○`
`Accept`	`application/json` or `text/xml`	`×`
`accept-encoding`	`gzip`	契約書の API のみ設定可能 `POST`,`PUT`

Authorization
- 認可情報を設定する
- 認証時に取得したアクセストークンをBearerに付加し設定する
- 例：Bearer 1234a567-b890-1c23-4567-89d01e2f3a45
Content-type
- HTTP メソッドがPOST,PUTの場合、ボディ情報の形式を設定する
- JSON 形式の場合は「application/json」を設定する
- XML 形式の場合は「text/xml」を設定する
Accept
- レスポンスで受信する形式を設定する
- JSON 形式で受信する場合は「application/json」を設定する
- XML 形式で受信する場合は「text/xml」を設定する
- 指定する際はクエリ文字列やボディ情報の「レスポンス形式（response_type）」と合わせる必要がある
- クエリ文字列やボディ情報が不正だった場合（JSON のカンマや XML のタグの漏れなど）、又はクエリ文字列やボディ情報の「レスポンス形式（response_type）」が不正だった場合に適用される
accept-encoding
- メソッドを利用する際にレスポンスで受信するボディ情報を圧縮する際に設定

3. レスポンス形式の設定

レスポンスのボディ形式を決定する「レスポンス形式（response_type）」は下記の値を設定する
その他項目は各 API の仕様を参照

パラメータ	値
`response_type`	`json` or `xml`

パラメータは文字コードを「UTF-8」にし、適切に URL エンコードすること
HTTP メソッドがGETの場合
- URL にパラメータをクエリ文字列として付加しリクエストする
HTTP メソッドがPOST,PUTの場合
- ボディ情報にパラメータを設定しリクエストする
- パラメータは JSON 形式または XML 形式で設定する

レスポンス

1. HTTP ステータスコード

HTTP ステータスコードと API の実行結果の関係は以下のとおり

ステータスコード	実行結果	例
`200(OK)`	成功
`400(Badrequest)`	リクエスト不正	JSON/XML の書式不正や JSON/XML に必要な要素が記述されていない
`401(Unauthorized)`	認証エラー	アクセストークンの不正や期限切れ
`403(Forbidden)`	権限無エラー	有料会員の資格無
`404(NotFound)`	リソース無	URL に誤りがある
`405(MethodNotAllowed)`	許可されていないメソッド	`POST`が許可されていない URI に対して`POST`メソッドを利用する
`415(UnsupportedMediaType)`	サポートしていないメディアタイプ	`Content-type`に`application/json`,`text/xml`以外を設定した
`500(InternalServerError)`	サーバー内部エラー	サーバーの内部的な問題で処理が完了しない発生時はシステム管理者にお問い合わせください
`503(Serviceunavailable)`	サービス利用不可	メンテナンス中のため要求を受け付けられない

2. ヘッダ情報

ヘッダ情報には下記の値が返却される

ヘッダ名	値	備考
`authorization`	`Bearer` + アクセストークン	リクエストで指定した形式が設定
`Content-type`	`application/json; charset=UTF-8` or `text/xml; charset=UTF-8`	リクエストで指定した形式が設定
`accept`	`application/json; charset=UTF-8` or `text/xml; charset=UTF-8`	リクエストで指定した形式が設定
`accept-Encoding`	`gzip`	リクエストで指定した形式が設定

3. ボディ情報

基本的にボディ情報の形式は以下の「レスポンス形式（response_type）」によって決定される
- GETの場合：リクエストのクエリ文字列
- POST,PUTの場合：ボディ情報
例外的に以下の場合はリクエストのヘッダ情報の「Accept」によって決定される（「Accept」が未設定の場合は JSON 形式）
- リクエストのクエリ文字列またはボディ情報が不正だった場合（JSON のカンマや XML のタグの漏れなど）
- リクエストのクエリ文字列またはボディ情報の「レスポンス形式（response_type）」が不正だった場合

4. レスポンス形式

1. JSON

基本フォーマット

要素	子要素	内容	型	備考
`result`		処理結果	文字列	成功時:`ok` 失敗時:`ng`
`error_list[]`		エラーリスト	配列	成功時:`null` 失敗時:子要素を設定 ※複数件出力されることもある
	`error_item`	エラー項目名	文字列	特定の項目に紐付かないエラーの場合は`null`
	`error_code`	エラーコード	文字列	各 API エラーメッセージ一覧参照
	`error_detail`	エラー内容	文字列	各 API エラーメッセージ一覧参照

結果サンプル(便宜上、コメントや改行・空白を入れている)

{
  "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文字以内で入力してください。"
    }
  ]
}

2. XML

基本フォーマット

要素	子要素	内容	型	備考
`result`		処理結果	文字列	成功時:`ok` 失敗時:`ng`
`error_list[]`		エラーリスト	配列	成功時:ブランク失敗時:子要素を設定 ※複数件出力されることもある
	`error_item`	エラー項目名	文字列	特定の項目に紐付かないエラーの場合はブランク
	`error_code`	エラーコード	文字列	各 API エラーメッセージ一覧参照
	`error_detail`	エラー内容	文字列	各 API エラーメッセージ一覧参照

結果サンプル(便宜上、コメントや改行・空白を入れている)
- ※XML の場合は、レスポンスで null が設定される箇所はブランクをリターンする。
- サンプルだと、5 行目の <error_item /> がそれにあたる。

<?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>

利用不可文字

クエリ文字列、ボディ情報には以下の文字は使用できない
含まれていた場合、自動で除去を行う
利用不可のものは以下
- %：パーセント
- ^：キャレット
- *：アスタリスク
- (,)：丸括弧
- [,]：角括弧
- <,>：山括弧
- '：シングルクォーテーション
- "：ダブルクォーテーション
- \t：タブ
- ,：カンマ