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-search
• аудит, журнал событий, безопасность → pachca-security

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

POST /views/open

скоуп: views:write

{
  "type": "modal",
  "trigger_id": "791a056b-006c-49dd-834b-c633fde52fe8",
  "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