工单入口

工单入口用于接收来自外部的报告——来自客户网站的联系表单、App 或服务器。三种方式都会在相应项目中创建工单，并带有客户合同中的响应期限。

此外还有电子邮件和监控——见下文。

所有设置都集中在一处：设置 › 工单入口（仅限所有者）。那里列出了每个项目及其入口的实测状态；点击展开后显示三张卡片：“服务器与应用”（入口密钥）、“公开工单入口”（表单和浏览器）和 “邮件入口”（邮箱）。在项目页面上，概览中“工单入口”一行的 “设置” 可直接跳转到已展开的项目。VentionDesk 根据工单被投递到的 URL 识别其来源方式——而不是根据发送方声明的任何内容。

设置之前： 通过表单或 App 提交内容的人，会将个人数据提供给您，因而也提供给作为服务商的 VentionDesk。请在与客户签订数据处理协议之后，再为客户网站设置入口，并在网站上加以说明——下方的表单代码为此包含一句话，并附有指向客户隐私政策的链接。

设置公开密钥和来源

在 设置 › 工单入口 下展开项目，打开 “公开工单入口” 卡片：

1. “设置入口” 创建公开密钥 vd_pub_…。“复制”将其放入剪贴板。
2. 在 “允许的来源” 下填入所有允许发送浏览器报告的地址——只包含协议、主机和端口，即 https://kunde.de，不带路径，也不带结尾斜杠。VentionDesk 按字面比对。
3. 未填写来源时，浏览器方式 不接受任何内容。HTML 表单和服务器方式不受影响。
4. “关闭入口” 会再次删除该密钥。

公开密钥并非机密——它就在客户网站的源代码中。它只能在这一个项目中创建工单。

方式 1：HTML 表单

一个普通表单，提交到 https://in.ventiondesk.com/f/<public key>。现成的代码可在 VentionDesk 的 工单 › “?” › “复制表单代码” 中复制：

<form method="post" action="https://in.ventiondesk.com/f/DEIN_PUBLIC_KEY">
  <input name="name" placeholder="Ihr Name" required />
  <input name="email" type="email" placeholder="Ihre E-Mail" required />
  <input name="subject" placeholder="Betreff" required />
  <textarea name="message" placeholder="Ihre Nachricht" required></textarea>
  <p>Mit dem Absenden werden Ihre Angaben zur Bearbeitung an unseren Dienstleister
    übermittelt. Mehr dazu in unserer <a href="DEINE_DATENSCHUTZERKLAERUNG">Datenschutzerklärung</a>.</p>
  <button type="submit">Absenden</button>
</form>

将 DEIN_PUBLIC_KEY 替换为公开密钥，将 DEINE_DATENSCHUTZERKLAERUNG 替换为客户网站的隐私政策。

可选：

• _redirect——提交后浏览器重定向到的绝对 URL（303）。其来源必须列在“允许的来源”中，否则 VentionDesk 以 JSON 响应。
• _hp——防机器人的蜜罐：一个隐藏的空字段。如果它被填写，VentionDesk 会礼貌地响应，但不创建任何内容。
• cf-turnstile-response——Cloudflare Turnstile 令牌，见下文。

没有 _redirect 时，VentionDesk 返回 201 和 { "ok": true, "ticket": { "id": "…", "key": "TK-1044" } }。

方式 2：从浏览器报告

POST https://api.ventiondesk.com/v1/intake/reports，在 x-ventiondesk-key 请求头中携带公开密钥——从来源已列在“允许的来源”中的 Web 应用发出：

await fetch('https://api.ventiondesk.com/v1/intake/reports', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-ventiondesk-key': 'vd_pub_…' },
  body: JSON.stringify({
    text: 'Saving does nothing',
    email: 'user@customer.com',
    screenshot: 'data:image/png;base64,…',
    meta: { url: location.origin + location.pathname, severity: 'high' },
  }),
});

• text（必填）：5 到 5,000 个字符。email：可选。
• screenshot：可选，以 data URL 形式（Base64 编码的 data:image/png、image/jpeg 或 image/webp），小于 500 kB。图片会附加到工单上。
• meta：可选——device、version、user、url 和 severity（low、normal、high、critical）。critical 会将工单优先级设为“紧急”。
• turnstileToken：可选，见下文。

软件包 @ventiondesk/sdk 封装的正是这个调用（ventiondesk.init({ publicKey })，然后 ventiondesk.report({ text, screenshot })）；它目前尚未发布到 npm。上面的 fetch 效果相同。

方式 3：服务器到服务器

如果客户网站有自己的后端，则使用 入口密钥 提交。在 设置 › 工单入口 中创建：点击该区域右上角的 “+”，然后选择项目——一个入口密钥只适用于 一个 项目，随后列在该项目的 “服务器与应用” 下。该密钥是机密，只能放在服务器上，绝不能放在浏览器中。

curl -X POST https://api.ventiondesk.com/v1/intake/tickets \
  -H "Authorization: Bearer vd_intake_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Miller","email":"j.miller@customer.com","subject":"Login does not work","message":"Since this morning I can no longer get into my account."}'

字段与表单相同，另外可选 screenshot（同上）和 meta（最多 20 个简单值）。入口密钥只能提交——不能读取任务，也看不到工单。

用 Turnstile 防机器人

如果 VentionDesk 一侧启用了 Cloudflare Turnstile，表单和浏览器方式就需要 Turnstile 令牌（cf-turnstile-response 或 turnstileToken）。缺少令牌时，VentionDesk 返回 403。默认情况下，此项检查对接收入口是关闭的：表单和浏览器方式位于你的页面上，而 Turnstile 小组件只在其站点密钥所对应的域名上有效。只有经过约定才会开启——届时你的页面需要自己的小组件，并使用对其域名有效的站点密钥。如果 Cloudflare 本身没有响应，VentionDesk 会放行报告并将其标记为未验证——Cloudflare 的故障不应让客户的请求丢失。服务器到服务器方式不需要 Turnstile。

检查：是否有内容到达？

“设置 › 工单入口”中的公开密钥和每个入口密钥都会显示“最近一次报告 …”或“尚无报告”——依据真实的尝试测得。如果最近一次尝试被拒绝，会显示原因：

限制

每种入口方式对每个 IP 地址每分钟最多接受 10 次报告；单个请求最大 1 MB。

电子邮件

发到工作区邮箱的邮件会变成工单；邮箱名称在 设置 › 邮件发件人 中设置。如果客户回复 VentionDesk 发出的邮件，回复会进入同一个工单——通过邮件头、地址中的工单编号（mailbox+TK-1044@…）或主题中的 [TK-1044] 识别。在 设置 › 工单入口 下项目的 “邮件入口” 卡片中，可以为该项目分配地址；其他域名下的地址需要设置转发到这里。

哪些地址会创建新工单： 只有已登记的地址。包括工作区的邮箱（也包括以前的邮箱名称及其所有加号地址）、各项目“邮件入口”卡片中的地址，以及工作区成员的登录地址。发到其他任何地址的邮件 不会 变成工单，也不会出现在任何地方——因此垃圾邮件机器人发到虚构地址的邮件不会进入入口。对现有工单的回复总能到达，无论发到哪个地址。如果缺少某封邮件，请将其地址填入对应项目的“邮件入口”卡片。

邮件收件确认： 只发给已知的发件人——工单已分配给客户，或该地址属于工作区的某个客户或门户账户。对于未知发件人，不会发出自动邮件；而是在历史记录中出现一条内部备注，如果请求属实，再手动回复。通过表单、App 组件和服务器方式提交的新潜在客户也会收到确认。

监控

在项目的 分析 标签页中创建监控（URL、类型“可用性”或“证书”、间隔）。如果监控 连续两次 失败，VentionDesk 会创建一个工单；恢复可达后，该工单即被解决。