pachca-forms

Base URL:

https://api.pachca.com/api/shared/v1

Авторизация:

Authorization: Bearer <ACCESS_TOKEN>

Токен: только бот (Автоматизации → Интеграции → API). Пользовательский токен не подойдёт — формы требуют исходящий вебхук.

Когда использовать

показать форму
интерактивная форма
модальное окно
modal
submit формы
обработать отправку формы
валидация формы
view_submission
опрос
заявка через форму

Когда НЕ использовать

получить профиль, мой профиль, установить статус → pachca-profile
найти сотрудника, создать пользователя, список сотрудников → pachca-users
создать канал, создать беседу, создать чат → pachca-chats
отправить сообщение, ответить в тред, прикрепить файл → pachca-messages
настроить бота, вебхук, webhook → pachca-bots
создать задачу, список задач, напоминание → pachca-tasks
аудит, журнал событий, безопасность → pachca-security

Пошаговые сценарии

Показать интерактивную форму пользователю

Заранее подготовь объект формы:
```
view
```
с
```
title
```
,
```
blocks
```
(типы:
```
input
```
,
```
select
```
,
```
radio
```
,
```
checkbox
```
,
```
date
```
,
```
time
```
,
```
file_input
```
,
```
header
```
,
```
plain_text
```
,
```
markdown
```
,
```
divider
```
), опционально
```
callback_id
```
(идентификатор формы) и
```
private_metadata
```
(контекст, например id сообщения)
Отправь сообщение с кнопкой (POST /messages с
```
buttons
```
, в
```
data
```
кнопки передай идентификатор формы)
При нажатии кнопки — получи вебхук-событие с
```
trigger_id
```
Немедленно отправь POST /views/open с
```
trigger_id
```
и готовым объектом формы
Пользователь заполняет форму → при отправке получи вебхук — обработай по сценарию «Обработать отправку формы»

bash

curl "https://api.pachca.com/api/shared/v1/views/open" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"modal","trigger_id":"abc123","view":{"title":"Заявка на отпуск","callback_id":"vacation_form","private_metadata":"{\"msg_id\":154332686}","blocks":[{"type":"input","name":"date_start","label":"Дата начала"},{"type":"input","name":"date_end","label":"Дата окончания"},{"type":"select","name":"reason","label":"Причина","options":[{"text":"Отпуск","value":"vacation"},{"text":"Больничный","value":"sick"}]}]}}'

trigger_id
живёт 3 секунды — за это время нужно успеть отправить POST /views/open. Формируй объект формы заранее, а не после получения события. Формы работают только от бота.

Обработать отправку формы (view_submission)

Получи вебхук с
```
"type": "view"
```
,
```
"event": "submit"
```
— содержит
```
callback_id
```
,
```
user_id
```
,
```
private_metadata
```
и
```
data
```
(значения полей, ключи совпадают с полем
```
name
```
каждого блока)
Извлеки значения из
```
data
```
: например, для блока с
```
"name": "comment"
```
значение в
```
data.comment
```
Если форма содержит
```
file_input
```
— скачай файлы по
```
data.field_name[].url
```
немедленно: ссылки истекают через 1 час
Если данные валидны → ответь HTTP 200 (пустое тело) — форма закроется у пользователя
Если есть ошибки → ответь HTTP 400 с
```
{"errors": {"field_name": "текст ошибки"}}
```
— пользователь увидит ошибки в форме и сможет исправить и отправить повторно

Ответ должен быть дан в течение 3 секунд — иначе пользователь увидит ошибку отправки, но все значения сохранятся и он повторит попытку.
callback_id
— идентифицирует какая форма отправлена (если ботов несколько).
private_metadata
— контекст, переданный при открытии (до 3000 символов).

Опрос сотрудников через форму

Отправь сообщение с кнопкой «Пройти опрос» в канал или ЛС: POST /messages с
```
"data": "survey_start"
```
в кнопке
При нажатии кнопки получи вебхук с
```
trigger_id
```
и
```
user_id
```
нажавшего
Немедленно отправь POST /views/open с формой (поля:
```
input
```
,
```
select
```
,
```
radio
```
и т.д.)
При отправке формы получи вебхук с
```
"event": "submit"
```
— значения полей в
```
data
```
Обработай ответы: сохрани в базу или отправь итоговым сообщением в канал
Ответь HTTP 200 — форма закроется

Каждый пользователь должен нажать кнопку сам — у каждого свой
trigger_id
. Нельзя открыть форму принудительно.

Форма заявки/запроса

Размести в канале сообщение с кнопкой «Создать заявку» (
```
"data": "new_request"
```
)
При нажатии открой форму с полями: тема, описание, приоритет (
```
select
```
)
При submit-вебхуке: создай задачу (POST /tasks) или отправь уведомление ответственному (POST /messages с
```
"entity_type": "user"
```
)
Отправь подтверждение автору: POST /messages с
```
"entity_type": "user"
```
,
```
"entity_id": user_id
```
из вебхука
Ответь HTTP 200 — форма закроется

Обработка ошибок

Код	Причина	Что делать
422	Неверные параметры	Проверь обязательные поля, типы данных, допустимые значения enum
429	Rate limit	Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec
403	Нет доступа	Недостаточно скоупов ( `insufficient_scope` ), бот не в чате, или endpoint только для админов/владельцев
404	Не найдено	Неверный id. Проверь что сущность существует
401	Не авторизован	Проверь токен в заголовке Authorization
410	trigger_id истёк или не найден	trigger_id действует 3 секунды. Получи новый через нажатие кнопки (вебхук)

Доступные операции

Открытие представления

POST /views/open

скоуп:
views:write

json

{
  "type": "modal",
  "trigger_id": "",
  "view": {
    "title": "",
    "blocks": []
  }
}

Ограничения и gotchas

```
type
```
: допустимые значения —
```
modal
```
(Модальное окно)
```
private_metadata
```
: максимум 3000 символов
```
callback_id
```
: максимум 255 символов
```
view.title
```
: максимум 24 символов
```
view.close_text
```
: максимум 24 символов
```
view.submit_text
```
: максимум 24 символов
Пагинация: cursor-based (limit + cursor), НЕ page-based

Подробнее

см. references/endpoints.md

pachca-forms

NPX Install

Tags

SKILL.md Content

pachca-forms

Когда использовать

Когда НЕ использовать

Пошаговые сценарии

Показать интерактивную форму пользователю

Обработать отправку формы (view_submission)

Опрос сотрудников через форму

Форма заявки/запроса

Обработка ошибок

Доступные операции

Открытие представления

Ограничения и gotchas

Подробнее