# 提交表单 (POST)

发送响应。提交的内容会在所有者的账户中生成一条消息，并推送到其手机，走的是与 [Webhook](https://info.pocketalert.app/api/webhooks/create.md) 调用相同的流程。**无需身份验证**。

## 端点

```
POST https://api.pocketalert.app/v1/forms/{tid}/submit
```

## 身份验证

> **Tip: 无需身份验证**
>
> 任何持有链接的人都可以提交。所有者可以控制谁能提交：参见[允许的来源](https://info.pocketalert.app/api/forms/create.md#allowed-origins)以及下方的限制。

## 请求

### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|:--------:|-------------|
| `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。

### 请求示例

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "message": "Do you ship to Canada?",
      "src": "newsletter"
    }
  }'
```

**JavaScript**

```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: 'jane@example.com',
        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**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
    json={
        'values': {
            'name': 'Jane Doe',
            'email': 'jane@example.com',
            'message': 'Do you ship to Canada?',
        }
    }
)

print(response.status_code, response.json())
```

## 响应

### 成功响应

> **Tip: 200 OK**
>
> ```json
> { "status": "ok" }
> ```

所有者会收到一条由回答内容生成的推送。访客无法看到所有者的任何信息，包括其套餐、设备和配额。

### 校验错误

> **Warning: 400 Bad Request**
>
> `fields` 将字段 `id` 映射到被拒绝的原因，表单页面会将其显示在对应输入框下方。

```json
{
  "error": "Please check the highlighted fields.",
  "fields": {
    "email": "Enter a valid email address",
    "name": "This field is required"
  }
}
```

### 表单已关闭

> **Danger: 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` | 该表单不接受来自此站点的提交，参见[允许的来源](https://info.pocketalert.app/api/forms/create.md#allowed-origins) |
| `404` | 未找到表单 |
| `410` | 表单已关闭 |
| `429` | 提交过于频繁，或所有者今日消息已用完 |
| `500` | 表单配置有误，或无法创建消息 |
