ヘッドレスフロントエンドへのオンラインフォーム統合

独自のウェブサイトフロントエンドを構築する際、「お問い合わせ」や「相談申し込み」フォームを作成するためにサードパーティのフォームサービスを統合する必要はありません。ダッシュボードの「マーケティング › オンラインフォーム」から直接フォームを作成し、Content Delivery APIを通じてカスタムフロントエンドからフィールドを取得し、回答を送信できます。

フォームが送信されると、Kanorioは自動的にボット保護、スパムフィルタリング、連絡先の作成または統合、送信者への確認メール送信、チームへの通知を行い、同時に customers.form.submitted ウェブフックをトリガーします。

エンドポイントおよびエラーコードの完全仕様（SSOT）: 3つのフォームエンドポイントのパラメータ詳細、フィールド構造、エラーコードについては、Content Delivery APIリファレンス（フォームグループ）を参照してください。

準備

1. フォームを作成し、フォームIDを取得する: ダッシュボードの「マーケティング › オンラインフォーム」に移動してフォームを作成します。formIdはURLまたは「データと記録 › データテーブル」で確認できます。
2. CORS許可オリジンを登録する: ブラウザから直接APIを呼び出す場合（独自のバックエンドを介してプロキシしない場合）、「ウェブサイト設定 › 開発者」に移動し、本番環境のドメイン（例: https://www.example.com）を「許可されたオリジン」に追加してください（ローカル開発用のlocalhostはデフォルトで許可されており、設定は不要です）。

統合の3ステップ

ステップ1: フォーム定義を取得する (GET /api/v1/forms/{id})

ページ読み込み時またはビルド時に、フォームのタイトル、フィールド、プライバシーおよびマーケティング同意設定、現在の利用可能ステータスを取得します。

• availability.accepting が false の場合（フォームがアーカイブされている、または期限切れの場合など）、フロントエンドで入力フィールドを表示する代わりに、受付終了メッセージを表示できます。
• フォームフィールドをフロントエンドにハードコードすることも可能です。その場合は、field.idがダッシュボードの設定と一致していることを確認してください。

ステップ2: アンチスパムチャレンジを取得する (GET /api/v1/forms/{id}/challenge)

訪問者に面倒なCAPTCHAを解かせることなく自動スパムボットをブロックするため、Kanorioは軽量なProof-of-Workチャレンジを使用します。

• 訪問者がフォームにフォーカスする前、または送信ボタンをクリックする前に、ブラウザから GET /api/v1/forms/{id}/challenge を呼び出します（このエンドポイントは no-store であり、毎回新しいチャレンジを返します）。
• チャレンジをフロントエンドのバリデーターに渡し、solution 文字列を計算して（または @kanorio/sdk に含まれるヘルパー関数を使用して）、送信時に含めます。

ステップ3: フォーム回答を送信する (POST /api/v1/forms/{id}/submit)

訪問者の answers（フィールド id をキーとするオブジェクト）、アンチスパムソリューション、およびマーケティング同意ステータスを /api/v1/forms/{id}/submit に POST します。

async function submitContactForm(siteUrl: string, formId: string, answers: Record<string, unknown>) {
  // 1. アンチスパムチャレンジを取得し、ソリューションを計算する
  const challengeRes = await fetch(`${siteUrl}/api/v1/forms/${formId}/challenge`, {
    cache: "no-store",
  });
  const challenge = await challengeRes.json();
  const token = await solveFormChallenge(challenge);

  // 2. フォーム回答を送信する
  const res = await fetch(`${siteUrl}/api/v1/forms/${formId}/submit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      answers,
      challengeToken: token,
      marketingConsent: true,
      pagePath: window.location.pathname,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error?.message ?? "送信に失敗しました");
  }
  return res.json();
}

自動バックエンドワークフロー

/submit が 200 OK を返すと、Kanorioはバックグラウンドで自動的に以下を実行します。

1. 連絡先の紐付け: フォームにメールアドレスや電話番号フィールドが含まれている場合、自動的にと照合または作成し、カスタムフィールドを連絡先属性にマッピングするか、フォーム回答として保存します。
2. 確認と通知: の設定に基づき、送信者およびチームに自動的にメールを送信します。
3. ウェブフックプッシュ: customers.form.submitted イベントを購読している場合、システムは即座に回答を外部システムや自動化ワークフローにプッシュします。

関連ドキュメント