接続仕様

ここでは、INFINI Virtual Card Payments XML APIシステム(以後本システム)においてINFINI内に設置されたアプリケーションサーバ(以後サーバ)とユーザ敷地内に設置されたサーバ(以後クライアント)との間のインタフェース仕様を記述する。
なお、ここではプロトコル層以上について記述し、ネットワークの物理層については範囲外とする。

基本仕様

1. サーバとクライアント間の通信はHTTP/1.0、1.1 仕様に基づくHTTP プロトコルを用いるものとする。

2. 通信はすべてクライアントからの接続とし、サーバからの応答をもって完結する。
  また、メソッドは POST のみ使用する。
  ※ソケットの接続状態(Keep-Alive制御)についてはIISの実装に準じる。

3. セッションの概念を持たない HTTP上においてセッション管理を実現するため、
  HTTPヘッダを用いたセッション管理を行う(いわゆるクッキー方式を使用する)

4. また、クッキーのみでは制御できないプロトコルを実現するために、HTTP拡張ヘッダを定義して使用する。

5. メッセージはヘッダ、コンテンツともすべてUTF-8(BOM無し)で構成されるものとする
  (現時点で本システムにおいて日本語などのマルチバイト文字などは使用しない)。

6. 本サービスは下記のURLで提供される。
  本番環境:https://www.infini-hostlink.com/HostLinkService/infiniAPI.asp
  テスト環境:https://testsite.infini-hostlink.com/HostLinkService/infiniAPI.asp

構成

本仕様を実現するための、構成(案)を付図に示す。
※ なお、クライアント側構成については想像に基づくものである。

はじめに

<XmlLoginId / LoginIdの取得>
XMLメッセージを送信するためには<XmlLoginId>及び <LoginId>のパラメータが必要である。この値は以下のリクエストメッセージを送信することで取得可能である。
取得した<LoginId>パラメータは一度取得すれば半永久的に有効であるため、セッションの開始毎に下記リクエストを行わないようにご注意ください。

  X-XML-Booking-Session: SESSION=START
  X-XML-Booking-PCC: PCC=XXXX
  X-XML-Booking-Host: HOST=TFCORE
  X-XML-Booking-TfConfig: TFLOGIN=TRUE

  ※XXXXには店舗コード(PCC)を指定してください。
  ※テスト用の店舗コードと本番用の店舗コードは同一です。


当該リクエストに対し、以下のレスポンスが返却され、<LoginId>を取得する。

セッションの管理

本システムの各リクエストを行うにあたってのセッション管理は以下の通り。

<セッションの開始>
1. セッションの開始時にクライアントは、下記 HTTPヘッダを持つリクエストメッセージを送信する。
  X-XML-Booking-Session: SESSION=START
  X-XML-Booking-PCC: PCC=XXXX
  X-XML-Booking-Host: HOST=TFCORE

2. 上記要求に対しサーバは、クライアントとのセッションを確立し、その結果を、下記HTTPヘッダを持つ
  レスポンスメッセージによりクライアントに送信する。
  X-XML-Booking-Status: STATUS=XXXX
  Set-Cookie: ASPSESSIONIDYYYYY=ZZZZZ; ....

  ※XXXXは通信の確立、およびサイン・インの結果を示すステータス・コードである。
   このステータス・コードが異常の場合には Set-Cookie ヘッダは送られない。
  ※クライアントは通知されたクッキー情報(ASPSESSIONIDYYYY=ZZZZZ)を記憶しておく。
   (ZZZZZは任意の長さの文字列である)
  ※「ASPSESSIONIDYYYYY」のCookie名については本システムのセッションの場合は
   基本的に「ASPSESSIONIDTFAPI」を戻すが、名称を変更する可能性があるため
   「ASPSESSIONIDから始まるCookie」という条件で取得できる様に実装する必要がある。
  ※クッキー情報内の";"以降の文字列についてはクライアントで無視する。(付かない場合もある)

3. セッション開始時にコマンドの実行は許可しない。
  「SESSION=START」時にリクエストにコンテンツの送信は許可しない。
  「SESSION=START_END」でのリクエストコンテンツの送信も許可しない。


<セッションの維持(各APIリクエスト)>

1. クライアントはセッション継続中のリクエストメッセージには、下記 HTTPヘッダを付けて送信する。
  各リクエストメッセージには事前に取得した<XmlLoginId>及び <LoginId>を付与すること。
  X-XML-Booking-Host: HOST=TFCORE
  Cookie: ASPSESSIONIDYYYYY=ZZZZZ

  ※
Cookie情報はセッション開始時にサーバから返された情報であること。

2. 上記要求に対しサーバは、コンテンツデータを処理し、その結果を、下記HTTPヘッダを持つレスポンス
  メッセージによりクライアントに送信する。
  X-XML-Booking-Status: STATUS=XXXX

<セッションの終了>

1. クライアントはセッションを終了させるために、下記 HTTPヘッダを持つリクエストメッセージを送信する。
  X-XML-Booking-Host: HOST=TFCORE
  Cookie: ASPSESSIONIDYYYYY=ZZZZZ
  X-XML-Booking-Session: SESSION=END

  ※ Cookie情報はセッション開始時にサーバから返された情報であること。


2. 上記要求に対しサーバは、Travelfusionとの接続を切断し、下記HTTPヘッダを持つレスポンスメッセージを
  送信する。
  X-XML-Booking-Status: STATUS=XXXX

  ※ XXXXはセッションの切断、およびサイン・アウトの結果を示すステータス・コードである。

<サーバー障害に伴うセッション終了>

1. サーバにおいてリクエスト受信後に、処理を継続できない状況が生じた場合、サーバは下記HTTPヘッダを持つ
  レスポンスメッセージを送信する。

  X-XML-Booking-Session: SESSION=END
  X-XML-Booking-Status: STATUS=XXXX

  ※ XXXXは障害を示すステータス・コードとする。
  ※ ホストのタイムアウト、対ホスト接続の切断などを想定しているため、セッションは切断されることを
   前提とする。
  ※
セッション開始リクエスト受信時に障害が起きた場合、レスポンスメッセージに上記のヘッダ以外に
   Set-Cookie: が指定されるかもしれないが、クライアントはこれを用いたリクエストを行ってはならない。
  ※ クライアントより受信したリクエストのHTTPヘッダが不適当な場合はエラー応答を行い、   
   セッションを切断する。

2. 
同様にリクエスト受信後に、応答も返せない状況が生じた場合、クライアントは一定時間受信  
  待ち後切断を切断すること。

<クライアント障害に伴うセッションタイムアウト>

1. クライアントにおいて処理を継続できない状況が生じた場合、上記「セッションの終了」と同じ手順により
  セッション終了要求を行うこと。

2. 
セッション終了要求も送信できない状況が生じた場合、サーバは一定時間セッションを維持した後、
  セッションを終了させる。

コンテンツ

通常コンテンツには、XMLメッセージあるいはテキストメッセージが含まれるが、下記のヘッダが付いた
場合には、そのメッセージのコンテンツは無視するものとする。(サーバ、クライアント双方において)

※ 下記ヘッダがついたメッセージのコンテンツは本システム、仕様に含まれない独自XML、もしくは
 空が返される。
 X-XML-Booking-Contents: CONTENTS=IGNORE

例 1: クライアントから、セッション開始/セッション終了のみ行う場合のリクエスト/レスポンスメッセージ
例 2: サーバにて障害が発生した場合のレスポンスメッセージ

通信例

上記仕様に基づいた通信例は以下の通りである。

通常パターン



セッション開始要求のみ先行するパターン



セッション終了要求のみクライアントから送信するパターン



セッションタイムアウト終了後にクライアントから要求を送信するパターン



クライアントからセッション開始要求と終了要求の両方が指定されたパターン



 

セキュリティ

1. 本システムにおいて、INFINI側LANとユーザ側LAN間の通信(WAN)については物理層によって 
  十分セキュリティが確保されていることを前提とし、この部分のセキュリティ対策は本設計書では記述しない。
2. INFINI側LAN内部およびユーザ側LAN内部におけるセキュリティ保持のため、サーバにおいて 
  下記の対策を取る。

リクエストメッセージ送信元の確認
1. リクエストメッセージ送信元のIPアドレスをチェックし、あらかじめ設定されたIPアドレス以外からの
  リクエストはエラー応答し、該当セッションを切断する。
2. セッション開始時の送信元IPアドレスを記憶しておき、セッション途中ではそのIPアドレス以外からの
  要求はエラー応答する。

セッションのタイムアウト
1. 一定時間リクエストの無いセッションについては、サーバでこれを無効化する。
2. 無効化されたセッションを指定したリクエストメッセージについては、エラー応答する。
  この場合の HTTPヘッダは下記のとおりとする。
   X-XML-Booking-Session: SESSION=END
   X-XML-Booking-Status: STATUS=9C00
   X-XML-Booking-Contents: CONTENTS=IGNORE

 ※ ただし、そのメッセージがセッション開始要求の場合は正常リクエストとみなし、新規セッションを開始する。
 ※ タイムアウト値は30 分とする。

受信コンテンツサイズの制限
ありえないサイズのリクエストを受信することによるメモリ不足や高負荷の発生を予防するため、受信中のコンテンツサイズが32KBを超えた時点で以降の受信を中止しエラー応答する。

受信コンテンツのGZIP圧縮
1. 本システムからのレスポンスコンテンツはTravelfusion社からのレスポンスをパススルーで返す。
2. Travelfusion社のレスポンスがGZIP圧縮されている場合、下記HTTPヘッダを付加してGZIP形式で
  コンテンツを戻す。この場合の HTTPヘッダは下記の通りとする。
  Content-Encoding: gzip
3. 上記レスポンスヘッダーが付加されている場合、クライアントでGZIP解凍してからコンテンツを 
  利用する必要がある。
4. クライアントからのGZIP圧縮のON/OFF指定は対応していない。
  Accept-Encodingによる圧縮の指定には対応しておらず、本システムからHTTPヘッダを一方的に戻す。

 

特記

1.  ステータス・コードについては、付録に一覧を添付する。
2.  本設計書のセッション管理方法は、RFC2109(HTTP State Management Mechanism)に準拠する。
3.  HTTP拡張ヘッダは、RFC822(STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES)に準拠し、
  先頭文字を "X-"とする。
4.  また、RFC2616に準拠し HTTPヘッダ識別子(":"の左側の文字列)において大文字/小文字は区別されないもの
  とする。
5.  特に断りの無い限り、サーバより送信するHTTPメッセージ仕様は IIS7.5の実装に依存する。

付録<INFINI Virtual Card Payments XML API版ステータス・コードについて>

現在のINFINI Virtual Card Payments XML API版に基づいて返されるステータス・コード(拡張ヘッダーのSTATUS に設定される値)は下記の定義に従った16 進4 桁数値である。

エラーコード

エラーコード       エラー内容       
0000 正常
9401 PCC エラー(末尾が6 でない、または長さが8 バイトより長い)
9402 不正なアクセス(途中で IP アドレスが未登録 IP アドレスに変更された)
9403 不正なアクセス(未登録 IP アドレスから受信)
9404 コンテンツが長すぎる(32KB を超えている)
9405 メソッドがPOST ではない
9406 認識できないヘッダーがある
9407
(Sxxx)
サイン・イン・エラー
xxxx はホスト・エラー・コード
9408 PCC セッション上限数オーバー
9409 許可されていないコマンド
940A コマンド、モード組み合わせ指定エラー
940B XML 解析エラー
940C 不正なクッキー
9C00 ホストとの接続時エラー
セッションが存在しない
9C02 ホストとの接続時エラー
接続タイムアウト
9C04 ホストとの接続時エラー
サインアウトエラー
A402 ホストからの受信エラー
受信タイムアウト
A405 ホスト、サーバータイムアウト
A887 ホストへの送信エラー
送信タイムアウト
A8FF 受信したレスポンス・データが空だった
AC01
(xxx)
SWS ホスト通信エラー
SWS ホストへのコマンド送受信時のHTTP ステータスコードが200 でない
xxx はステータスコード
AC02 ホストビジー
AC03
(TF)
ホストビジー
通信毎にスレッド数の上限数オーバー
B001 サーバーセッション数オーバー
FFFF 内部エラー