# Создание формы (POST)

Создайте размещённую форму. Она сразу публикуется по адресу `https://frms.click/{tid}`, а каждая отправка становится сообщением в вашем аккаунте — см. [Формы](https://info.pocketalert.app/features/forms.md).

## Эндпоинт

```
POST https://api.pocketalert.app/v1/forms
```

## Аутентификация

> **Info: Обязательно**
>
> Добавьте в запрос один из этих заголовков:
> - `Token: <your-api-key>` — получите его в разделе [API-ключи](https://pocketalert.app/account/apikeys)
> - `Authorization: Bearer <jwt-token>` — из [входа](https://info.pocketalert.app/api/user/login.md)

## Запрос

### Заголовки

| Заголовок | Обязательный | Описание |
|--------|:--------:|-------------|
| `Token` | ✅ | Ваш API-ключ |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

### Параметры тела запроса

| Параметр | Тип | Обязательный | Описание |
|-----------|------|:--------:|-------------|
| `name` | string | ✅ | Внутреннее название, до 191 символа. Также используется как заголовок push-уведомления по умолчанию |
| `fields` | array | ✅ | Поля формы, не более 30. Хотя бы одно должно заполняться посетителем |
| `settings` | object | ❌ | Заголовок, тексты и оформление. У каждого ключа есть значение по умолчанию |
| `application_tid` | string | ❌ | Приложение, к которому относятся отправки |
| `device_tid` | string | ❌ | TID целевого устройства или `all`. Если не указать, уведомления придут на все устройства |
| `default_level` | int | ❌ | Уровень приоритета (`-2`..`2`) для отправок. См. [Уровни приоритета сообщений](https://info.pocketalert.app/api/messages/create.md#priority-levels) |
| `push_title` | string | ❌ | Шаблон заголовка push-уведомления с токенами `{Field label}`, до 191 символа |
| `allowed_origins` | array | ❌ | Хосты, которым разрешено встраивать форму и отправлять её, не более 10. Пустое значение означает, что ограничений нет |
| `max_responses` | int | ❌ | Закрыть форму после этого количества ответов. `0` (по умолчанию) — без ограничений |
| `closes_at` | string | ❌ | Время закрытия, RFC 3339. Хранится в UTC |
| `is_active` | boolean | ❌ | `false` сразу закрывает форму. По умолчанию `true` |

### Поля

Каждый элемент `fields`:

| Параметр | Тип | Обязательный | Описание |
|-----------|------|:--------:|-------------|
| `id` | string | ✅ | Уникален в пределах формы: буквы, цифры, `_` и `-`, до 40 символов |
| `type` | string | ✅ | Один из типов, перечисленных ниже |
| `label` | string | ✅ | Отображается над полем ввода, до 200 символов (2000 для `paragraph`) |
| `placeholder` | string | ❌ | Только для text, textarea, email, phone, number, url и dropdown |
| `required` | boolean | ❌ | Игнорируется полями оформления |
| `options` | array | ✅ для полей выбора | До 50 вариантов для `dropdown`, `radio` и `checkboxes` |
| `param` | string | ✅ для `hidden` | Параметр URL, из которого читается значение, например `utm_source` |

| Группа | Типы | Отправляемое значение |
|-------|-------|-----------------|
| Текст | `text`, `textarea`, `email`, `phone`, `number`, `url`, `date` | Строка. `text` ограничен 1000 символами, `textarea` — 5000 |
| Выбор | `dropdown`, `radio` | Один из `options` |
| Выбор | `checkboxes` | Массив из `options` |
| Выбор | `checkbox` | Логическое значение, отображается как `Yes` / `No` |
| Оценка | `rating` (1–5), `nps` (0–10) | Число |
| Оформление | `heading`, `paragraph`, `divider` | Никогда не отправляются |
| Отслеживание | `hidden` | Берётся из URL страницы, а не от посетителя |

Значения email, телефона, числа, URL и даты проверяются на сервере; проверка в браузере — это удобство, а не защита.

### Настройки

Все ключи необязательны — то, что вы не укажете, сохраняет значение по умолчанию.

| Параметр | Тип | По умолчанию | Описание |
|-----------|------|---------|-------------|
| `title` | string | `""` | Заголовок над формой, до 200 символов |
| `top_text` | string | `""` | Вводный текст, до 2000 символов. Простой текст; ссылки становятся кликабельными |
| `bottom_text` | string | `""` | Текст под кнопкой, до 2000 символов |
| `success_message` | string | `Thanks! Your response has been sent.` | Показывается после отправки, до 500 символов |
| `closed_message` | string | `This form is no longer accepting responses.` | Показывается, когда форма закрыта |
| `background_color` | string | `#f5f5f4` | Фон страницы, `#rrggbb` |
| `card_color` | string | `#ffffff` | Фон формы |
| `text_color` | string | `#1c1917` | Цвет текста |
| `primary_color` | string | `#3f5cad` | Акцентный цвет и, если не переопределён, цвет кнопки |
| `font_family` | string | `Inter` | Шрифт Google Fonts по названию |
| `font_size` | int | `16` | 12–24 |
| `font_weight` | int | `400` | 300, 400, 500, 600 или 700 |
| `border_radius` | int | `10` | 0–48 |
| `hide_branding` | boolean | `false` | Скрывает ссылку «Powered by Pocket Alert». Только для платных тарифов — на бесплатном тарифе API сбрасывает значение в `false` |
| `submit` | object | — | `{ "text": "Submit", "color": "", "size": "md" }`. `size` — `sm`, `md` или `lg`; пустой `color` следует за `primary_color` |

### Шаблон заголовка push-уведомления

`push_title` формирует заголовок уведомления из ответов:

```
New lead: {Name} ({Email})
```

Токены ссылаются на поля **по названию** без учёта регистра, а также `{form}` — для названия формы. Токены без ответа пропускаются; если ничего не осталось, заголовок становится `Form: {name}`. Шаблон никогда не показывается на публичной странице.

### Разрешённые источники

Идентификатор формы передаётся в её публичной ссылке, поэтому по умолчанию встроить форму может любой, у кого она есть. `allowed_origins` это ограничивает: встраивать форму могут только перечисленные хосты, а отправка, у которой `Origin` (или `Referer`) не входит в список, отклоняется с ответом `403`.

Указывайте хосты, а не URL: `example.com`, `app.example.com`, `*.example.com` для всех поддоменов, `localhost:3000` при разработке. Префикс `www.` игнорируется.

### Пример запроса

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/forms" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact form",
    "push_title": "New lead: {Name}",
    "fields": [
      { "id": "name", "type": "text", "label": "Name", "required": true },
      { "id": "email", "type": "email", "label": "Email", "required": true },
      { "id": "message", "type": "textarea", "label": "Message" },
      { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
    ],
    "settings": {
      "title": "Get in touch",
      "top_text": "We reply within one business day.",
      "primary_color": "#3f5cad"
    }
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/forms', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Contact form',
    push_title: 'New lead: {Name}',
    fields: [
      { id: 'name', type: 'text', label: 'Name', required: true },
      { id: 'email', type: 'email', label: 'Email', required: true },
      { id: 'message', type: 'textarea', label: 'Message' }
    ],
    settings: { title: 'Get in touch' }
  })
});

const form = await response.json();
console.log('Form link:', `https://frms.click/${form.tid}`);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'Contact form',
        'push_title': 'New lead: {Name}',
        'fields': [
            {'id': 'name', 'type': 'text', 'label': 'Name', 'required': True},
            {'id': 'email', 'type': 'email', 'label': 'Email', 'required': True},
            {'id': 'message', 'type': 'textarea', 'label': 'Message'},
        ],
        'settings': {'title': 'Get in touch'},
    }
)

form = response.json()
print(f"Form link: https://frms.click/{form['tid']}")
```

**PHP**

```php
$form = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/forms', [
    'name' => 'Contact form',
    'push_title' => 'New lead: {Name}',
    'fields' => [
        ['id' => 'name', 'type' => 'text', 'label' => 'Name', 'required' => true],
        ['id' => 'email', 'type' => 'email', 'label' => 'Email', 'required' => true],
        ['id' => 'message', 'type' => 'textarea', 'label' => 'Message'],
    ],
    'settings' => ['title' => 'Get in touch'],
])->json();

echo 'Form link: https://frms.click/'.$form['tid'];
```

## Ответ

### Успешный ответ

> **Tip: 201 Created**
>
> Форма опубликована. Поделитесь ссылкой `https://frms.click/{tid}` или встройте форму — см. [Формы](https://info.pocketalert.app/features/forms.md#embedding).

Тело ответа имеет ту же структуру, что и один элемент из [Получения всех форм](https://info.pocketalert.app/api/forms/get-forms.md#response).

```json
{
  "tid": "vml19aihrga216gt8apc5e3m9",
  "name": "Contact form",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message" },
    { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
  ],
  "settings": {
    "title": "Get in touch",
    "top_text": "We reply within one business day.",
    "success_message": "Thanks! Your response has been sent.",
    "closed_message": "This form is no longer accepting responses.",
    "background_color": "#f5f5f4",
    "card_color": "#ffffff",
    "text_color": "#1c1917",
    "primary_color": "#3f5cad",
    "font_family": "Inter",
    "font_size": 16,
    "font_weight": 400,
    "border_radius": 10,
    "hide_branding": false,
    "submit": { "text": "Submit", "color": "", "size": "md" }
  },
  "application_tid": "",
  "device_tid": "",
  "default_level": null,
  "push_title": "New lead: {Name}",
  "allowed_origins": [],
  "max_responses": 0,
  "closes_at": null,
  "closed": false,
  "is_active": true,
  "submissions_count": 0,
  "last_submission_at": "",
  "created_at": "23.09.2026 11:40:02"
}
```

### Ответы с ошибками

| Статус | Описание |
|:------:|-------------|
| `400` | Ошибка валидации — поле `error` указывает, какое поле или настройка неверны |
| `401` | Не авторизовано — токен неверный или отсутствует |
| `403` | Вы достигли лимита форм, доступного на вашем тарифе |
| `500` | Не удалось создать форму |
