# FormPostbox 提交契约（纯 Markdown）

本文档描述把现有网站表单提交到 FormPostbox 的公开 HTTP 契约，与框架无关；各技术栈的参考实现见文末链接的 Skill 文件。

## 端点

`POST https://formpostbox.com/f/{formId}` — 每个表单一个路径。把 `{formId}` 替换为表单页上给出的表单 id。

## 请求

- 内容类型：`application/json` 或 `application/x-www-form-urlencoded`，其他类型返回 `415`。
- 参考实现使用带 `Accept: application/json` 的 `fetch`，以便确认 `saved: true`。原生浏览器表单提交则在保存成功时跳转、被拒绝时返回 HTML 错误页；它不提供 JSON 确认流程。
- 字段：任意带名称的字符串字段。必需：
  - `_intent_id` — 16–128 个字符。每条消息生成一次；网络重试复用它（幂等）；保存确认或新消息后换新。
  - 受保护的网站需提供 `cf-turnstile-response`，即一次性 Cloudflare Turnstile 令牌。未开启防护的网站不需要令牌；如果提供了该字段，长度不超过 2048 个字符的响应会被忽略。更长的响应超过请求限制，会被拒绝。
- 页面必须运行在表单“允许的来源”中的确切来源上：协议、主机名和端口完全一致（不支持通配符）。每次请求（包括重试）都会校验 `Origin`。
- 来源不允许时，浏览器可能显示 CORS 或网络错误，因为响应可能会被浏览器隐藏。请先核对页面的协议、主机名和端口是否与允许来源一致；FormPostbox 表单页会显示被拒绝的来源。修正后用同一 intent 重试。
- 限制：业务字段名为 1–128 个字符；最多 50 个业务字段（任何情况下都不含 `_intent_id` 和 `cf-turnstile-response`）；每个值最多 32768 个字符；JSON 和 URL 编码请求体都最多 65536 字节（超大返回 `413`）；规范化后的业务字段 JSON 也最多 65536 字节；提供的 `cf-turnstile-response` 最多 2048 个字符；受保护的网站需要非空令牌（1–2048 个字符）。

## 响应

保存成功（新消息）：`201`

```json
{"saved":true,"id":"…","replayed":false,"notification":"queued"}
```

保存成功（同一 intent + 相同内容的重试）：`200`，`"replayed":true` 且返回原 `id`；不会重复保存，也不多消耗额度。

被拒绝：`{"saved":false,"error":"…"}`

| 状态码 | error | 含义 |
|---|---|---|
| `400` | invalid | 请求体不是合法 JSON/对象，或字段超出限制 |
| `400` | origin | 页面的来源不在该表单的允许来源中 |
| `400` | captcha | 受保护的网站上，Turnstile 令牌缺失、已使用、过期或验证失败 |
| `400` | paused | 表单未启用 |
| `400` | configuration | 已开启通知的收件人未验证，或请求进行期间防护设置发生变化 |
| `404` | not_found | 表单 id 不存在 |
| `404` | expired | 引用的记录已删除或超出保留期 |
| `409` | conflict | 同一 intent 携带了修改后的内容。恢复原内容可在原提交仍保留时重放。若确实是新消息，用户必须明确开始新消息并生成新 intent。 |
| `413` | too_large | 请求体超过 65536 字节 |
| `415` | unsupported | 内容类型不是 JSON 或表单编码 |
| `429` | quota | 工作区当月提交额度已用完 |
| `429` | rate_limit | 请求速率超限；请稍后重试 |
| `503` | unavailable | 临时不可用，稍后重试 |

`notification` 描述邮件侧：开启邮件通知时新保存为 `queued`，关闭时为 `off`，重放为 `unchanged`。保存成功不代表邮件已送达。

## 能力边界

- 浏览器接入只使用公开值——不需要 API Key，也不需要服务端代理。
- 不支持附件、multipart 上传和非字符串字段值。
- 只有在表单已启用且来源完全匹配时，提交才会被接受。防护按站点可选：受保护的网站需提供有效且一次性的 Turnstile 响应；未开启防护的网站无需 widget 或响应即可保存提交。只有开启邮件通知时才要求收件人已验证。

## 链接

- AI 接入指南：https://formpostbox.com/docs/ai-integration
- 各技术栈 Skill：https://formpostbox.com/skills/html/SKILL.zh-CN.md · https://formpostbox.com/skills/react/SKILL.zh-CN.md · https://formpostbox.com/skills/astro/SKILL.zh-CN.md
- 面向 AI 工具的索引：https://formpostbox.com/llms.txt
