pachca-forms

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

Authorization: Bearer <ACCESS_TOKEN>

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

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

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

• получить профиль, мой профиль, установить статус → pachca-profile
• найти сотрудника, создать пользователя, список сотрудников → pachca-users
• создать канал, создать беседу, создать чат → pachca-chats
• отправить сообщение, ответить в тред, прикрепить файл → pachca-messages
• настроить бота, вебхук, webhook → pachca-bots
• создать задачу, список задач, напоминание → pachca-tasks
• аудит, журнал событий, безопасность → 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 — форма закроется

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

insufficient_scope

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

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

POST /views/open

скоуп:

views:write

{
  "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

Подробнее