提交表单 POST
发送响应。提交的内容会在所有者的账户中生成一条消息,并推送到其手机,走的是与 Webhook 调用相同的流程。无需身份验证。
端点
POST https://api.pocketalert.app/v1/forms/{tid}/submit身份验证
无需身份验证
任何持有链接的人都可以提交。所有者可以控制谁能提交:参见允许的来源以及下方的限制。
请求
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tid | string | ✅ | 表单标识符 |
请求体参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
values | object | ✅ | 以字段 id 为键的回答 |
website | string | ❌ | 蜜罐字段。请不要填写;任何非空值都会被视为机器人提交 |
各字段类型对应的值:
| 类型 | 值 |
|---|---|
text、textarea、email、phone、number、url | 字符串。其中 email、phone、number 和 url 会校验格式 |
date | 字符串,格式为 YYYY-MM-DD |
dropdown、radio | 字符串,必须是字段 options 中的一项 |
checkboxes | 字符串数组,元素取自 options |
checkbox | 布尔值 |
rating | 数字,1–5 |
nps | 数字,0–10 |
hidden | 字符串,通常取自页面 URL |
布局字段(heading、paragraph、divider)不接受值,未知的键会被忽略。请求体上限为 64 KB。
请求示例
bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
-H "Content-Type: application/json" \
-d '{
"values": {
"name": "Jane Doe",
"email": "[email protected]",
"message": "Do you ship to Canada?",
"src": "newsletter"
}
}'javascript
const response = await fetch(
'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
values: {
name: 'Jane Doe',
email: '[email protected]',
message: 'Do you ship to Canada?'
}
})
}
);
const result = await response.json();
if (response.status === 400) {
// result.fields = { email: "Enter a valid email address" }
console.log(result.fields);
}python
import requests
response = requests.post(
'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
json={
'values': {
'name': 'Jane Doe',
'email': '[email protected]',
'message': 'Do you ship to Canada?',
}
}
)
print(response.status_code, response.json())响应
成功响应
200 OK
json
{ "status": "ok" }所有者会收到一条由回答内容生成的推送。访客无法看到所有者的任何信息,包括其套餐、设备和配额。
校验错误
400 Bad Request
fields 将字段 id 映射到被拒绝的原因,表单页面会将其显示在对应输入框下方。
json
{
"error": "Please check the highlighted fields.",
"fields": {
"email": "Enter a valid email address",
"name": "This field is required"
}
}表单已关闭
410 Gone
json
{
"error": "This form is no longer accepting responses.",
"closed": true
}error 字段返回所有者自定义的 closed_message。
限制
| 限制 | 值 |
|---|---|
| 每个 IP | 每分钟 10 次提交 |
| 每个表单 | 每分钟 60 次,每小时 300 次 |
| 所有者配额 | 每次提交占用所有者每日额度中的一条消息 |
如果某次提交会超出所有者的每日消息上限,将返回中性的 429 响应,附带 Retry-After 响应头,且不会提及套餐信息。
错误响应
| 状态码 | 说明 |
|---|---|
400 | 请求体无效,或 fields 列出了需要修正的回答 |
403 | 该表单不接受来自此站点的提交,参见允许的来源 |
404 | 未找到表单 |
410 | 表单已关闭 |
429 | 提交过于频繁,或所有者今日消息已用完 |
500 | 表单配置有误,或无法创建消息 |