フォーム

KREISELのフォーム機能をAPI経由で利用する方法について解説します。

アンケートフォームの作成

APIを利用して外部にアンケートフォームを設置し、入力された情報をKREISELに登録する方法を解説します。これは、KREISELの「登録フォーム」をAPI経由で実行することに相当します。

備考

フォームから送信されたデータを処理するには、do_member_form_action APIを利用します。

概念図

外部サーバーにアンケート回答用のフォーム（HTML）と、そのデータを受け取ってKREISEL APIを呼び出すプログラム（PHP）を設置する構成です。

KREISEL管理画面での準備

1. データベースと項目の作成

まず、アンケートの受け皿となるデータベースと、回答を保存する項目を作成します。今回は音楽に関するアンケートを例とします。

性別（単一選択）
年齢（単一選択）
職業（単一選択）
好きなジャンル（複数選択）
1日あたりの鑑賞時間（単一選択）
好きなアーティストや楽曲（テキストエリア）

単一選択や複数選択の項目には、あらかじめ選択肢を登録しておく必要があります。

2. API用フォームの作成

次に、APIから利用するためのフォームを作成します。

[フォーム] > [フォーム設定] から「新規作成」をクリックします。
「フォームのタイプ」で 「API連携」 を選択します。
「公開」を 「公開する」 に設定します。
任意の「フォームの名称」を入力し、作成を完了します。

作成が完了すると、フォーム一覧に「フォームID」が表示されます。このIDはAPI呼び出し時に必要です。

3. フォーム項目の設定

作成したフォームの「項目の設定」画面に進みます。各項目には、データベース項目IDとは別に 「フォーム項目ID」 が割り振られています。APIで値を送信する際は、このIDをキーとして使用します。各項目の「表示」設定を「必須」にすると、その項目が未入力の場合にAPIから登録しようとするとエラーになります。

最後に、フォーム一覧画面で「タイプ」が「登録」のフォームを 「有効」 にします。

実装サンプル

1. フロントエンド（HTMLフォーム）

ユーザーが回答を入力するためのHTMLフォームです。

<html>
<head>
    <title>どんな音楽を聴いていますか？アンケートフォーム</title>
</head>
<body>
    <h1>どんな音楽を聴いていますか？</h1>
    <p>アンケートにご協力ください！</p>
    <form action="send_kreisel.php" method="post">
        <table>
            <tr>
                <th>性別</th>
                <td>
                    <select name="sex">
                        <option value="1">男性</option>
                        <option value="2">女性</option>
                    </select>
                </td>
            </tr>
            <tr>
                <th>年齢</th>
                <td>
                    <select name="age">
                        <option value="1">10歳未満</option>
                        <option value="2">10代</option>
                        <option value="3">20代</option>
                        <option value="4">30代</option>
                        <option value="5">40代</option>
                        <option value="6">50代以上</option>
                    </select>
                </td>
            </tr>
            <tr>
                <th>ご職業</th>
                <td>
                    <select name="job">
                        <option value="1">会社員</option>
                        <option value="2">経営・管理職</option>
                        <option value="3">公務員</option>
                        <option value="4">自営業</option>
                        <option value="5">自由業</option>
                        <option value="6">学生</option>
                        <option value="7">パート・アルバイト</option>
                        <option value="8">専業主婦</option>
                        <option value="9">無職</option>
                        <option value="10">その他</option>
                    </select>
                </td>
            </tr>
            <tr>
                <th>好きなジャンル（複数回答可）</th>
                <td>
                    <input type="checkbox" name="genres[]" value="1">J-POP
                    <input type="checkbox" name="genres[]" value="2">ロック
                    <input type="checkbox" name="genres[]" value="3">ヒップホップ
                    <input type="checkbox" name="genres[]" value="4">R&B
                    <input type="checkbox" name="genres[]" value="5">アニメソング
                </td>
            </tr>
            <tr>
                <th>一日当たりどれくらい音楽を聴きますか？</th>
                <td>
                    <select name="time">
                        <option value="1">30分未満</option>
                        <option value="2">30分～1時間</option>
                        <option value="3">1時間～3時間</option>
                        <option value="4">3時間～5時間</option>
                        <option value="5">5時間以上</option>
                    </select>
                </td>
            </tr>
            <tr>
                <th>好きなアーティストや楽曲を教えてください</th>
                <td><textarea name="freetext"></textarea></td>
            </tr>
            <tr>
                <td colspan="2">
                    <input type="submit" value="送信する">
                </td>
            </tr>
        </table>
    </form>
</body>
</html>

注意

チェックボックスのような複数選択項目では、name属性を genres[] のように配列形式にしておくと、PHPで値を受け取りやすくなります。

2. バックエンド（API呼び出しプログラム）

HTMLフォームからPOSTされたデータを受け取り、do_member_form_action APIを呼び出してKREISELにデータを登録します。

<?php
// send_kreisel.php

// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID'; // ご自身の環境IDに書き換えてください
$apiToken = 'YOUR_API_TOKEN'; // APIトークンに書き換えてください
$formId = 1; // KREISELで作成したAPIフォームのID

// APIエンドポイント
$url = "https://krs.bz/{$environmentId}/api/v1/do_member_form_action";

// POSTされた値を整形
// フォーム項目IDはKREISELの管理画面で確認した値を使用します
$memberInfo = [
    'e_14' => (int)$_POST['sex'],
    'e_15' => (int)$_POST['age'],
    'e_16' => (int)$_POST['job'],
    'e_17' => array_map('intval', $_POST['genres'] ?? []),
    'e_18' => (int)$_POST['time'],
    'e_19' => htmlspecialchars($_POST['freetext'], ENT_QUOTES, 'UTF-8'),
];

// リクエストボディを作成
// 登録フォームの場合、会員IDは 0 を指定します
$requestBody = [
    'member_form_id' => $formId,
    'member_id'      => 0,
    'member_info'    => $memberInfo,
];

// cURLセッションを初期化
$ch = curl_init($url);

// cURLオプションを設定
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

// APIリクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// cURLセッションを終了
curl_close($ch);

// レスポンスを処理
if ($httpCode === 200) {
    $result = json_decode($response, true);
    echo 'アンケート回答ありがとうございました。', PHP_EOL;
    echo '会員ID : ', $result['member_id'];
} else {
    // エラー処理
    $error = json_decode($response, true);
    echo 'エラーが発生しました。', PHP_EOL;
    echo 'HTTPコード: ', $httpCode, PHP_EOL;
    echo 'エラーコード: ', $error['error_code'] ?? 'N/A', PHP_EOL;
    echo 'エラー詳細: ', $error['error_desc'] ?? 'N/A', PHP_EOL;
    // KR_API_F0116: Action Is Not Finished. (入力値のバリデーションエラーなど)
    // KR_API_F0111: FormGroup Is Not Enabled. (フォームが非公開)
    // KR_API_F0112: Form Is Not Enabled. (フォームが無効)
    // KR_API_F0110: Not API Form. (APIフォームではない)
}

?>

セキュリティ

実際の運用では、入力値のバリデーションやサニタイズを必ず行ってください。このサンプルでは、htmlspecialcharsによる最低限のサニタイズのみを行っています。

フォーム入力値の形式チェック

do_member_form_action を呼び出す前に、入力された値が各項目の形式に合っているかを事前にチェックできます。これにより、ユーザーに即座にフィードバックを返すUIを実装できます。

APIの紹介

validate_member_form_parameter: 1項目ずつチェックします。
validate_member_form_parameters: 複数項目をまとめてチェックします。

ヒント

複数項目をチェックする場合は、APIの呼び出し回数が1回で済む validate_member_form_parameters の利用を推奨します。

実装サンプル

validate_member_form_parameters を使って、複数の入力値を一度にチェックする例です。

<?php
// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';
$formId = 1; // チェック対象のフォームID

// APIエンドポイント
$url = "https://krs.bz/{$environmentId}/api/v1/validate_member_form_parameters";

// チェックしたい値（ユーザーの入力値を想定）
$formElementValues = [
    'e_7' => 'text', // 不正なメールアドレス
    'e_8' => [], // 必須項目なのに空
    'e_9' => 'ｶﾅ①', // 半角カナと機種依存文字を含む
];

// リクエストボディを作成
$requestBody = [
    'form_id' => $formId,
    'form_element_values' => $formElementValues,
];

// cURLセッション
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

// APIリクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// レスポンスを処理
if ($httpCode === 200) {
    $result = json_decode($response, true);
    if (!empty($result['errors'])) {
        foreach($result['errors'] as $elementName => $errorMessages) {
            if (!empty($errorMessages)) {
                echo "項目「{$elementName}」のエラー:", PHP_EOL;
                foreach($errorMessages as $message) {
                    echo "- ", $message, PHP_EOL;
                }
            }
        }
    } else {
        echo "すべての項目が正常です。", PHP_EOL;
    }
} else {
    // エラー処理
    $error = json_decode($response, true);
    echo 'API呼び出しでエラーが発生しました。', PHP_EOL;
    echo 'HTTPコード: ', $httpCode, PHP_EOL;
    echo 'エラーコード: ', $error['error_code'] ?? 'N/A', PHP_EOL;
    // KR_API_F0110: Not API Form. (APIフォームではない)
    // KR_API_F0121: Invalid Form Element Name. (存在しない項目名を指定)
}
?>

実行結果の例

項目「e_7」のエラー:
- エラー: 形式が正しくありません。
項目「e_8」のエラー:
- エラー: 選択されていません。
項目「e_9」のエラー:
- エラー: 半角カナが使われています。
- エラー: 機種依存文字が使われています。

会員の重複登録チェック

データベースの重複キー項目（例: メールアドレス）を基準に、登録しようとしている会員がすでに存在するかどうかをチェックできます。

APIの紹介

check_unique_member_confliction: 指定されたキー項目の値が、DB内で重複していないかを判定します。

実装サンプル

メールアドレス（フォーム項目ID: e_69）が重複キーに設定されている場合の実装例です。

<?php
// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';
$formId = 16; // 登録フォームのID

// APIエンドポイント
$url = "https://krs.bz/{$environmentId}/api/v1/check_unique_member_confliction";

// チェックしたい情報
$checkEmail = 'foo@example.com'; // ユーザーが入力したメールアドレス
$memberInfo = [
    'e_69' => $checkEmail, // 重複キーであるメールアドレス項目
];

// リクエストボディを作成
// 登録フォームでのチェックなので会員IDは 0
$requestBody = [
    'form_id'   => $formId,
    'member_id' => 0,
    'member_info' => $memberInfo,
];

// cURLセッション
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

// APIリクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// レスポンスを処理
if ($httpCode === 200) {
    $result = json_decode($response, true);
    if ($result['is_unique']) {
        echo "会員：{$checkEmail}は登録可能です。", PHP_EOL;
    } else {
        echo "会員：{$checkEmail}はすでに登録されています。", PHP_EOL;
    }
} else {
    // エラー処理
    $error = json_decode($response, true);
    echo 'API呼び出しでエラーが発生しました。', PHP_EOL;
    echo 'エラーコード: ', $error['error_code'] ?? 'N/A', PHP_EOL;
    // KR_API_F0123: Form Is Not For Either Regist or Update. (登録/更新フォーム以外を指定)
}
?>

ログインフォームの作成

KREISELに登録されている会員情報（重複キー項目とパスワード）を使って認証を行う、会員専用ページのような機能を実装できます。

APIの紹介

auth_member: 重複キー項目の値とパスワードで認証を行い、成功すれば会員IDを返します。

備考

この機能は、KREISELの「更新フォーム」の認証をエミュレートします。そのため、API連携用の 更新フォーム を事前に作成しておく必要があります。

実装サンプル

メールアドレス（フォーム項目ID: e_91）とパスワードで認証する例です。

<?php
// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';
$formId = 22; // 更新フォームのID

// APIエンドポイント
$url = "https://krs.bz/{$environmentId}/api/v1/auth_member";

// ユーザーの入力値
$loginId = 'foo@example.com';
$password = '12345678';

// リクエストボディを作成
$requestBody = [
    'member_form_id' => $formId,
    'member_info'    => [
        'e_91' => $loginId, // 重複キー項目
    ],
    'password'       => $password,
];

// cURLセッション
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

// APIリクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// レスポンスを処理
if ($httpCode === 200) {
    $result = json_decode($response, true);
    if ($result['member_id'] > 0) {
        echo '認証に成功しました。 会員ID : ', $result['member_id'];
        // ここでセッションを開始するなどのログイン後処理を行う
    } else {
        echo '会員が存在しないか、パスワードが間違っています。';
    }
} else {
    // エラー処理
    $error = json_decode($response, true);
    echo 'API呼び出しでエラーが発生しました。', PHP_EOL;
    echo 'エラーコード: ', $error['error_code'] ?? 'N/A', PHP_EOL;
    // KR_API_F0119: Form Is For Regist. (登録フォームを指定した場合など)
}
?>

パスワード再発行フォームの作成

「パスワード再発行フォーム」を利用して、ユーザーがパスワードをリセットする機能を提供できます。

フロー

ユーザーがメールアドレスを入力する。
lookup_member_id APIでメールアドレスから会員IDを検索する。
見つかった会員IDを使い、do_member_form_action APIでパスワード再発行処理を実行する。
KREISELの自動返信メール機能により、新しいパスワードがユーザーに通知される。

備考

この機能を利用するには、事前にKREISEL管理画面で 「パスワード再発行フォーム」 を作成し、自動返信メールを設定しておく必要があります。

実装サンプル

<?php
// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';
$dbId = 3; // データベースID
$formId = 30; // パスワード再発行フォームのID

// ユーザーが入力したメールアドレス
$email = 'foo@example.com';

// ----- 1. lookup_member_id で会員IDを検索 -----
$lookupUrl = "https://krs.bz/{$environmentId}/api/v1/lookup_member_id";
$lookupBody = [
    'member_table_id' => $dbId,
    'member_info' => [
        // メールアドレスの項目名は 'e_DB項目ID' 形式
        'e_49' => $email,
    ],
];

$ch = curl_init($lookupUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($lookupBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

$lookupResponse = curl_exec($ch);
$lookupHttpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($lookupHttpCode !== 200) {
    die('会員IDの検索に失敗しました。');
}

$memberId = json_decode($lookupResponse, true)['member_id'];

// ----- 2. do_member_form_action でパスワードを再発行 -----
if ($memberId > 0) {
    $resetUrl = "https://krs.bz/{$environmentId}/api/v1/do_member_form_action";
    $resetBody = [
        'member_form_id' => $formId,
        'member_id'      => $memberId,
        'member_info'    => new stdClass(), // パスワード再発行時は空のオブジェクト
    ];

    $ch = curl_init($resetUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($resetBody));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ]);

    $resetResponse = curl_exec($ch);
    $resetHttpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($resetHttpCode === 200) {
        echo 'パスワード再発行のメールを送信しました。';
    } else {
        echo 'パスワードの再発行に失敗しました。';
        // エラー内容をログに出力するなどの処理
        // var_dump($resetResponse);
    }
} else {
    echo 'そのメールアドレスは登録されていません。';
}
?>

削除された会員データ（削除ログ）の取得

「削除フォーム」を通じてユーザー自身が退会した場合、その会員情報をログとして後から取得できます。

APIの紹介

get_deleted_member_list: 指定した削除フォームの削除ログを取得します。

実装サンプル

指定日時以降に削除された会員のログを、51件目から最大100件取得し、メールアドレスを一覧表示する例です。

<?php
// 環境情報
$environmentId = 'YOUR_ENVIRONMENT_ID';
$apiToken = 'YOUR_API_TOKEN';
$formId = 3; // 削除フォームのID

// APIエンドポイント
$url = "https://krs.bz/{$environmentId}/api/v1/get_deleted_member_list";

// リクエストボディを作成
$requestBody = [
    'member_form_id' => $formId,
    // 2009年5月1日 0時0分0秒以降のログを対象
    'after'          => mktime(0, 0, 0, 5, 1, 2009),
    // 51件目から取得 (オフセットは0から始まる)
    'offset'         => 50,
];

// cURLセッション
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestBody));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

// APIリクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// レスポンスを処理
if ($httpCode === 200) {
    $result = json_decode($response, true);
    $deletedMembers = $result['deleted_members'];

    if (count($deletedMembers) > 0) {
        echo "削除された会員のメールアドレス一覧:", PHP_EOL;
        foreach ($deletedMembers as $deletedMember) {
            $emailFound = false;
            // 各会員の項目情報をループ
            foreach ($deletedMember as $parameter) {
                // $parameter は [項目名, 値] の配列
                if ($parameter[0] === 'メールアドレス') {
                    echo $parameter[1], PHP_EOL;
                    $emailFound = true;
                    break; // メールアドレスが見つかったので次の会員へ
                }
            }
            if (!$emailFound) {
                echo "(メールアドレス項目が見つかりません)", PHP_EOL;
            }
        }
    } else {
        echo "該当する削除ログはありませんでした。", PHP_EOL;
    }
} else {
    // エラー処理
    $error = json_decode($response, true);
    echo 'API呼び出しでエラーが発生しました。', PHP_EOL;
    echo 'エラーコード: ', $error['error_code'] ?? 'N/A', PHP_EOL;
    // KR_API_F0217: Form Is Not For Delete. (削除フォーム以外を指定)
}
?>

アンケートフォームの作成​

概念図​

KREISEL管理画面での準備​

1. データベースと項目の作成​

2. API用フォームの作成​

3. フォーム項目の設定​

実装サンプル​

1. フロントエンド（HTMLフォーム）​

2. バックエンド（API呼び出しプログラム）​

フォーム入力値の形式チェック​

APIの紹介​

実装サンプル​

会員の重複登録チェック​

APIの紹介​

実装サンプル​

ログインフォームの作成​

APIの紹介​

実装サンプル​

パスワード再発行フォームの作成​

フロー​

実装サンプル​

削除された会員データ（削除ログ）の取得​

APIの紹介​

実装サンプル​

アンケートフォームの作成

概念図

KREISEL管理画面での準備

1. データベースと項目の作成

2. API用フォームの作成

3. フォーム項目の設定

実装サンプル

1. フロントエンド（HTMLフォーム）

2. バックエンド（API呼び出しプログラム）

フォーム入力値の形式チェック

APIの紹介

実装サンプル

会員の重複登録チェック

APIの紹介

実装サンプル

ログインフォームの作成

APIの紹介

実装サンプル

パスワード再発行フォームの作成

フロー

実装サンプル

削除された会員データ（削除ログ）の取得

APIの紹介

実装サンプル