# 폼 제출 (POST)

응답을 보냅니다. 제출된 내용은 소유자 계정의 메시지가 되고 소유자의 휴대폰으로 푸시 알림이 전송됩니다. [웹훅](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회 |
| 소유자 할당량 | 제출 1건당 소유자의 일일 메시지 할당량에서 메시지 1개를 사용 |

소유자의 일일 메시지 한도를 초과하는 제출은 `429` 헤더와 함께 `Retry-After`를 받습니다. 응답에는 요금제에 대한 언급이 없습니다.

### 오류 응답

| 상태 | 설명 |
|:------:|-------------|
| `400` | 잘못된 본문이거나, 수정해야 할 응답을 `fields`에서 알려 줍니다 |
| `403` | 이 사이트에서의 제출을 폼이 허용하지 않습니다. [허용된 출처](https://info.pocketalert.app/api/forms/create.md#allowed-origins)를 참고하세요 |
| `404` | 폼을 찾을 수 없습니다 |
| `410` | 폼이 마감되었습니다 |
| `429` | 제출이 너무 많거나, 소유자의 오늘 메시지 한도를 모두 사용했습니다 |
| `500` | 폼 설정에 문제가 있거나, 메시지를 생성할 수 없습니다 |
