在自建前端集成在线表单

当您自行打造网站前端时，无需为了制作“联系我们”或“预约咨询”表单而额外集成第三方表单服务。您可以直接在后台“营销 › 在线表单”建立表单，再从自建前端通过 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 事件，系统会立即将答案推送至您的外部系统或自动化流程。

相关文档