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

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

備考

フォームから送信されたデータを処理するには、POST /api/v1/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 されたデータを受け取り、POST /api/v1/do_member_form_action API を呼び出して KREISEL にデータを登録します。

<?php
// send_kreisel.php

// 環境情報
$environmentId = getenv('ENV_ID');
$apiToken = getenv('API_TOKEN');
$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) {
    $memberId = json_decode($response, true);
    echo 'アンケート回答ありがとうございました。', PHP_EOL;
    echo '会員ID : ', $memberId;
} 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による最低限のサニタイズのみを行っています。

概念図​

KREISEL管理画面での準備​

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

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

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

実装サンプル​

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

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

概念図