在自建前端串接線上表單

當您自己打造網站前端時，不需要為了做一張「聯絡我們」或「預約諮詢」表單而另外串接第三方表單服務。您可以直接在後台「行銷 › 線上表單」建立表單，再從自建前端透過 Content Delivery API 讀取題目並送出回答。

表單送出後，Kanorio 會自動幫您完成防機器人驗證、垃圾訊息過濾、建立或合併顧客聯絡人、寄送填表者確認信與團隊通知信，並觸發 customers.form.submitted Webhook。

完整端點與錯誤碼規格（SSOT）：表單三支端點的參數、欄位結構與錯誤碼，請查閱 Content Delivery API 參考頁（Forms 分組）。

串接前準備

1. 建立表單並取得表單 ID：前往後台「行銷 › 線上表單」建立表單，從網址或「數據與資料 › 資料表」取得 formId。
2. 登記跨網域允許來源（CORS）：若您的前端直接從瀏覽器呼叫 API（非透過您自己的後端轉發），請先到「網站設定 › 開發者」將外部前端的正式網域（例如 https://www.example.com）加入「允許的來源」（本機開發 localhost 預設放行，免設定）。

三步驟完成表單串接

第一步：讀取表單定義（GET /api/v1/forms/{id}）

在頁面載入或建置時讀取表單的標題、題目欄位（fields）、隱私權與行銷同意勾選設定（consent），以及表單目前是否開放收件（availability）：

• 若 availability.accepting 為 false（例如表單已封存或已超過截止時間），前端可直接顯示關閉提示，不必渲染輸入框。
• 您也可以在自己的前端寫死固定表單欄位，只需將題目的英文 field.id 對齊後台設定即可。

第二步：取得防灌水挑戰（GET /api/v1/forms/{id}/challenge）

為了在不要求訪客輸入繁瑣圖形驗證碼的前提下擋下自動化垃圾機器人，Kanorio 採用輕量級簽章工作量證明（Proof-of-Work）挑戰：

• 當訪客聚焦表單或按下送出前，從瀏覽器呼叫 GET /api/v1/forms/{id}/challenge（此端點為 no-store，每次回傳全新挑戰）。
• 將取得的挑戰交給前端驗證器計算出解答字串 solution（或使用 @kanorio/sdk 內建的輔助函式），連同答案一起送出。

第三步：提交表單回覆（POST /api/v1/forms/{id}/submit）

將訪客填寫的 answers（以題目 id 為鍵的物件）、防灌水解答與行銷同意狀態 POST 至 /api/v1/forms/{id}/submit：

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. 聯絡人歸戶：若表單內有 Email 或電話欄位，自動比對或建立，並將其餘自訂題目寫入聯絡人屬性或存於表單回覆中。
2. 確認信與團隊通知：依您在的設定，自動寄信給填表訪客與您的團隊成員。
3. Webhook 推播：若您有訂閱 customers.form.submitted 事件，系統會立即將答案推送至您的外部系統或自動化流程。

相關文件