pachca-forms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pachca-forms

Base URL:

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

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

Authorization: Bearer <ACCESS_TOKEN>

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

Base URL:

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

授权方式：

Authorization: Bearer <ACCESS_TOKEN>

令牌：仅支持机器人令牌（自动化 → 集成 → API）。用户令牌无效——表单需要使用传出webhook。

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

适用场景

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

展示表单
交互式表单
模态窗口
modal
表单提交
处理表单提交
表单验证
view_submission
调查
通过表单提交申请

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

不适用场景

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

获取个人资料、我的资料、设置状态 → 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. Формируй объект формы заранее, а не после получения события. Формы работают только от бота.

提前准备表单对象：包含
```
title
```
、
```
blocks
```
（类型：
```
input
```
、
```
select
```
、
```
radio
```
、
```
checkbox
```
、
```
date
```
、
```
time
```
、
```
file_input
```
、
```
header
```
、
```
plain_text
```
、
```
markdown
```
、
```
divider
```
）的
```
view
```
，可选
```
callback_id
```
（表单标识符）和
```
private_metadata
```
（上下文信息，例如消息ID）
发送带按钮的消息（POST /messages接口，按钮的
```
data
```
字段传入表单标识符）
用户点击按钮后，会收到包含
```
trigger_id
```
的webhook事件
立即发送POST /views/open请求，携带
```
trigger_id
```
和预先准备好的表单对象
用户填写表单后提交，会收到对应的webhook事件——按照「处理表单提交」场景进行处理

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)

处理表单提交（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 символов).

收到类型为
```
"type": "view"
```
、事件为
```
"event": "submit"
```
的webhook——包含
```
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
. Нельзя открыть форму принудительно.

在频道或私信中发送带「参与调查」按钮的消息：调用POST /messages接口，按钮的
```
"data": "survey_start"
```
用户点击按钮后，会收到包含
```
trigger_id
```
和点击者
```
user_id
```
的webhook事件
立即发送POST /views/open请求，携带调查表单（字段类型：
```
input
```
、
```
select
```
、
```
radio
```
等）
用户提交表单后，会收到
```
"event": "submit"
```
的webhook事件——字段值位于
```
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 — форма закроется

在频道中发布带「创建申请」按钮的消息（按钮的
```
"data": "new_request"
```
）
用户点击按钮后，打开包含主题、描述、优先级（
```
select
```
类型）字段的表单
收到提交的webhook后：创建任务（调用POST /tasks接口）或向负责人发送通知（调用POST /messages接口，指定
```
"entity_type": "user"
```
）
向申请者发送确认消息：调用POST /messages接口，指定
```
"entity_type": "user"
```
和webhook中的
```
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 секунды. Получи новый через нажатие кнопки (вебхук)

状态码	原因	解决方法
422	参数错误	检查必填字段、数据类型、枚举值的有效性
429	请求频率超限	等待后重试。限制：约50次请求/秒，消息类接口约4次请求/秒
403	无权限	权限范围不足（ `insufficient_scope` ）、机器人未加入对话，或该端点仅对管理员/所有者开放
404	资源不存在	ID错误。请确认实体是否存在
401	未授权	检查Authorization头中的令牌是否正确
410	trigger_id已过期或不存在	trigger_id的有效期为3秒。需通过用户点击按钮重新获取（webhook事件）

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

可用操作

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

打开视图

POST /views/open

скоуп:
views:write

json

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

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

```
type
```
：允许的值为
```
modal
```
（模态窗口）
```
private_metadata
```
：最多3000字符
```
callback_id
```
：最多255字符
```
view.title
```
：最多24字符
```
view.close_text
```
：最多24字符
```
view.submit_text
```
：最多24字符
分页方式：基于游标（limit + cursor），不支持基于页码（page-based）

pachca-forms

Original

Translation

pachca-forms

pachca-forms

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

适用场景

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

不适用场景

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

分步场景教程

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

向用户展示交互式表单

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

处理表单提交（view_submission）

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

通过表单进行员工调查

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

申请/请求表单

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

错误处理

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

可用操作

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

打开视图

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

限制与注意事项

Подробнее

更多详情