API/Webhookについて


ゲーオクConnectでは、ユーザ情報とオークション情報をゲームと連動できるよう、APIとWebhookを提供します。
これらをゲームに実装することにより、ゲーオクConnectで操作できることは一部の機能を除きゲーム内から操作できるようになります。
以降のページで仕様を掲載しますので、仕様に基づいた実装をお願いします。


APIとWebhookの定義

ゲーオクConnectでは、APIとWebhookを次の意味で定義します。

API ゲーム側からゲーオクConnectへパラメータを送付し、情報を取得したりゲーオクConnect側で処理を実行させたりする場合に使用します。
送信時は指定のURLに指定のパラメータをPOST方式で送信します。
戻り値はJSONで送信します。

▼ゲーム側実装例(PHPの場合)

						<?php

						function PostToAuction ($param1, $param2) {
						  $result = '';

						  // パラメータのチェック
						  if ($param1 < 0) {
						    return $result;
						  }
						  if (strlen($param2)) > 20) {
						    return $result;
						  }

						  // 送信先と送信データの設定
						  $url = 'https://(ホスト名)/connect_ja/auctionapi/xxx.php';
						  $data = array (
						    'param1' => $param1,
						    'param2' => $param2
						  );

						  // cURLを使ってPOST送信
						  $ch = curl_init ();
						  curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, false);
						  curl_setopt ($ch, CURLOPT_URL, $url);
						  curl_setopt ($ch, CURLOPT_POSTFIELDS, http_build_query($data));
						  curl_setopt ($ch, CURLOPT_POST, true);
						  curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
						  $response = curl_exec ($ch);
						  curl_close ($ch);

						  // 戻り値により結果分岐
						  if ($response !== false) {
						    $response_decode = json_decode ($response, false);
						    if ($response_decode->rcode == 0) {
						      $result = 'success';
						    } else {
						      switch ($response_decode->errorcode) {
						        case 1:
						          $result = 'param1_error';
						          break;
						        case 2:
						          $result = 'param2_error';
						          break;
						        default:
						          break;
						      }
						    }
						  }

						  return $result;
						}
					
Webhook ゲーオクConnectからゲーム側へパラメータを送付し、ゲーム側で処理を実行させる場合に使用します。
送信時は指定のURLに指定のパラメータをPOST方式で送信します。
戻り値はJSONで送信します。

▼ゲーム側実装例(PHPの場合)

						<?php

						$result = new stdClass;

						// POSTパラメータを格納
						if (isset($_POST['param1'])) {
						  $param1 = $_POST['param1'];
						}
						if (isset($_POST['param2'])) {
						  $param2 = $_POST['param2'];
						}

						・
						・
						・

						// 結果をJSONで出力
						if ($process == true) {
						  $result->rcode = 0;
						} else {
						  $result->rcode = -1;
						}
						$result_encode = json_encode($result);
						echo $result_encode;
					


認証

API/Webhookには、通信が不正ではないことを確認するため認証を付ける場合があります。
使用する認証は以下の2種類です。
どの認証を使用するかは各API/Webhookの詳細をご参照ください。

署名認証 ゲーオクConnectが発行する「ゲームKey」を使って、ゲーオクConnectとゲーム側だけが認識できる文字列を署名として送信する方式の認証です。
POST送信するデータとゲームKeyを連結させた文字列をSHA256でハッシュ値を生成し、そのハッシュ値を「Signature」パラメータとしてHeaderに付加して送信します。
受信した側は、同様にデータとゲームKeyを連結させた文字列をSHA256でハッシュ値を生成し、そのハッシュ値とHeaderのSignatureの値とを比較し、一致していれば正しい通信であると判断します。

▼ゲーム側実装例(送信時、PHPの場合)

						<?php

						function SignaturePostToAuction ($param1, $param2) {

						  ・
						  ・
						  ・

						  // 送信先と送信データの設定
						  $url = 'https://(ホスト名)/connect_ja/auctionapi/xxx.php';
						  $data = array (
						    'param1' => $param1,
						    'param2' => $param2,
						    'gameid' => 'xxxx'     // ゲーオクConnectが発行するゲームID
						  );

						  // 署名設定
						  $gamekey = 'xxxxxxxx'     // ゲーオクConnectが発行するゲームKey
						  $signature = hash('sha256', http_build_query($data) . $gamekey);
						  $headers = array(
	    				    "Signature:".$signature
						  );

						  // cURLを使ってPOST送信
						  $ch = curl_init ();
						  curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, false);
						  curl_setopt ($ch, CURLOPT_URL, $url);
						  curl_setopt ($ch, CURLOPT_POSTFIELDS, http_build_query($data));
						  curl_setopt ($ch, CURLOPT_HTTPHEADER, $headers);
						  curl_setopt ($ch, CURLOPT_POST, true);
						  curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
						  $response = curl_exec ($ch);
						  curl_close ($ch);

						  ・
						  ・
						  ・

						}
					

▼ゲーム側実装例(受信時、PHPの場合)

						<?php

						// 署名取得
						foreach (getallheaders() as $name => $value) {
						  if (mb_strtolower($name) == "signature") {
						    $signature = mb_strtolower($value);
						    break;
						  }
						}

						// 生成したハッシュ値と署名の比較
					    if ($signature) {
						  $gamekey = 'xxxxxxxx'     // ゲーオクConnectが発行するゲームKey
						  $data = file_get_contents('php://input');
						  $hash = hash('sha256', $data . $gamekey);
						  if ($hash != $signature) {

						    // Error

						  }
					    } else {

						  // Error

					    }
					
ユーザトークン認証 APIを送信する際、ゲーオクConnectが発行するユーザトークンを併せて送信する方式の認証です。
ユーザトークンは、ゲーム側がログインAPIを送信した際、正常にログインできた場合に戻り値としてゲーオクConnectが発行します。
ゲーム側ではこのユーザトークンをログインしたユーザIDと紐付けて保存し、その後のAPIで使用します。
APIでユーザIDとユーザトークンが認証できた場合は、正しい通信であると判断します。


API/Webhook用語定義

ゲーオクConnectではAPI/Webhookに関連する共通用語を以下の通り定義します。

ホスト名 ゲーオクConnectのサーバのホスト名を指します。各APIの送信先URLには「ホスト名」と記載しています。開発を申し込んでいただいた場合に実際のホスト名をお伝えします。
メールアドレス ユーザが所持するメールアドレスであり、ユーザがゲーオクConnectにログインするために必要なIDです。不正なメールアドレスでは利用できないような設計をする必要があります。
パスワード メールアドレスと一対になる、ユーザがゲーオクConnectにログインするために必要なパスワードです。ゲーオクConnectでは暗号化して管理するため把握はできません。
ユーザID ユーザを識別するための11桁のIDです。APIではユーザIDをキーとしてユーザを識別します。ユーザは使用しません。ユーザを新規登録した場合に発行されます。
ユーザトークン ユーザIDと一対になる、ユーザIDが不正なものではないことを認証するための文字列です。一部のAPIではユーザIDとユーザトークンをセットで送信し、認証を行います。ユーザは使用しません。ユーザがログインする度に発行されます。不正使用を防ぐため、部外者に漏れないように管理する必要があります。
ゲームKey ゲーオクConnectがゲームごとに発行する、署名認証に必要な文字列です。API/Webhookが不正な通信ではないことを証明するためのものなので、部外者に漏れないように管理する必要があります。発行後に変更を希望する場合はお問い合わせください。
ゲームID ゲーオクConnectがゲームごとに発行する、ゲームを識別するための文字列です。不正使用を防ぐため、部外者に漏れないように管理する必要があります。発行後に変更を希望する場合はお問い合わせください。
サブカテゴリID ゲーオクConnectがゲームごとに発行する、ゲーム内アイテムのカテゴリを識別するための文字列です。不正使用を防ぐため、部外者に漏れないように管理する必要があります。発行後に変更を希望する場合はお問い合わせください。
仮支払い 商品落札後、落札したユーザが落札代金の決済を行うことを指します。アイテムの取引が完了後に、ゲーオクConnectが出品したユーザへ振込を行うため、仮としています。尚、仮支払いはゲーオクConnect内でしか行えません。後述の方法でゲーオクConnectで決済を行うよう案内してください。


API非提供機能

ゲーオクConnectが保有する機能のうち、支払い機能はAPIとして提供していません。
商品落札後に落札者に支払いを行わせる場合は、以下のゲーオクConnectのURLにリダイレクトし、ログイン後に決済を行うよう誘導してください。

(ホスト名)/connect_ja/userlogin/?redirect_to=%2Fconnect_ja%2Fauction%2F%3Fult_auc_id%3D(出品ID)