Back to Details

pachca-users

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

pachca-users

pachca-users

Base URL: 
https://api.pachca.com/api/shared/v1
Авторизация: 
Authorization: Bearer <ACCESS_TOKEN>
Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API).
基础URL：
https://api.pachca.com/api/shared/v1
授权方式：
Authorization: Bearer <ACCESS_TOKEN>
令牌：可使用机器人令牌（自动化 → 集成 → API）或用户令牌（自动化 → API）。

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

适用场景

  • найти сотрудника
  • создать пользователя
  • список сотрудников
  • создать тег
  • управлять тегами
  • назначить тег
  • приостановить сотрудника
  • онбординг
  • offboarding
  • уволить сотрудника
  • участники тега
  • 查找员工
  • 创建用户
  • 获取员工列表
  • 创建标签
  • 管理标签
  • 分配标签
  • 暂停员工账号
  • 入职（onboarding）
  • 离职（offboarding）
  • 解雇员工
  • 获取标签成员

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

不适用场景

  • получить профиль, мой профиль, установить статус → pachca-profile
  • создать канал, создать беседу, создать чат → pachca-chats
  • отправить сообщение, ответить в тред, прикрепить файл → pachca-messages
  • настроить бота, вебхук, webhook → pachca-bots
  • показать форму, интерактивная форма, модальное окно → pachca-forms
  • создать задачу, список задач, напоминание → pachca-tasks
  • аудит, журнал событий, безопасность → pachca-security
  • 获取个人资料、我的资料、设置状态 → pachca-profile
  • 创建频道、创建群聊、创建对话 → pachca-chats
  • 发送消息、回复线程、上传文件 → pachca-messages
  • 配置机器人、Webhook → pachca-bots
  • 展示表单、交互式表单、模态窗口 → pachca-forms
  • 创建任务、任务列表、提醒 → pachca-tasks
  • 审计、事件日志、安全 → pachca-security

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

分步场景

Массовое создание сотрудников с тегами

批量创建带标签的员工

  1. Создай тег (если нужен): POST /group_tags с 
    {"group_tag": {"name": ...}}
  2. Для каждого сотрудника: POST /users — теги назначаются через поле 
    list_tags
    в теле запроса
  3. Или обнови существующего: PUT /users/{id} с 
    list_tags
Создание сотрудников доступно только администраторам и владельцам (не ботам). Нет отдельного эндпоинта "добавить юзера в тег" — теги назначаются через 
list_tags
при создании (POST /users) или обновлении (PUT /users/{id}).
  1. 创建标签（如需）：调用POST /group_tags，请求体为
    {"group_tag": {"name": ...}}
  2. 为每位员工调用：POST /users — 通过请求体中的
    list_tags
    字段分配标签
  3. 或更新现有员工：调用PUT /users/{id}，携带
    list_tags
    字段
仅管理员和所有者可创建员工（机器人无此权限）。目前没有单独的“为用户添加标签”接口，需在创建员工（POST /users）或更新员工（PUT /users/{id}）时通过
list_tags
字段分配标签。

Найти сотрудника по имени или email

根据姓名或邮箱查找员工

  1. GET /users?query=Иван — поиск по имени/email (частичное совпадение)
  2. Если нужен точный поиск по email — перебери страницы и отфильтруй на клиенте
bash
curl "https://api.pachca.com/api/shared/v1/users?query=Иван&limit=50" \
  -H "Authorization: Bearer $TOKEN"
  1. 调用GET /users?query=伊万 — 按姓名/邮箱模糊搜索
  2. 如需精确匹配邮箱，需遍历分页结果并在客户端过滤
bash
curl "https://api.pachca.com/api/shared/v1/users?query=Иван&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Ответ: {"data":[{"id":186,"first_name":"Иван","last_name":"Петров","email":"ivan@example.com",...}]}

响应：{"data":[{"id":186,"first_name":"Иван","last_name":"Петров","email":"ivan@example.com",...}]}


> GET /users поддерживает параметр `query` для поиска. Пагинация cursor-based: используй `limit` и `cursor` из `meta`.

> GET /users接口支持`query`参数用于搜索。分页采用基于cursor的方式：使用`limit`参数和响应`meta`中的`cursor`参数。

Онбординг нового сотрудника

新员工入职流程

  1. POST /users с 
    email
    , именем, тегами (
    list_tags
    ) — создать аккаунт
  2. POST /chats/{id}/members с 
    member_ids
    — добавить в нужные каналы (онбординг, общий, тематические)
  3. POST /messages с 
    "entity_type": "user"
    , 
    "entity_id": user.id
    — отправить welcome-сообщение в личные сообщения
Шаг 1 требует токена администратора/владельца. Шаги 2-3 можно делать ботом.
  1. 调用POST /users，携带
    email
    、姓名、标签（
    list_tags
    ）—— 创建账号
  2. 调用POST /chats/{id}/members，携带
    member_ids
    —— 将员工加入指定频道（入职频道、公共频道、主题频道等）
  3. 调用POST /messages，携带
    "entity_type": "user"
    、
    "entity_id": user.id
    —— 向员工发送欢迎私信
步骤1需要管理员/所有者令牌。步骤2-3可使用机器人令牌执行。

Offboarding сотрудника

员工离职流程

  1. PUT /users/{id} с 
    "suspended": true
    — заблокировать доступ
  2. Опционально: DELETE /users/{id} — удалить аккаунт полностью
Приостановка (
suspended
) сохраняет данные, удаление — необратимо. Уточняй политику перед удалением.
  1. 调用PUT /users/{id}，携带
    "suspended": true
    — 锁定账号权限
  2. 可选操作：调用DELETE /users/{id} — 彻底删除账号
暂停账号（
suspended
）会保留数据，删除操作不可恢复。执行删除前请确认相关政策。

Получить всех сотрудников тега/департамента

获取标签/部门下的所有员工

  1. GET /group_tags?names[]=Backend — найти тег по названию
  2. Из ответа взять 
    id
    тега
  3. GET /group_tags/{id}/users с пагинацией (
    limit
    + 
    cursor
    ) — получить всех участников
  1. 调用GET /group_tags?names[]=Backend — 按名称查找标签
  2. 从响应中获取标签的
    id
  3. 调用GET /group_tags/{id}/users，结合分页参数（
    limit
    + 
    cursor
    ）—— 获取所有成员

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

错误处理

КодПричинаЧто делать
422Неверные параметрыПроверь обязательные поля, типы данных, допустимые значения enum
429Rate limitПодожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec
403Нет доступаНедостаточно скоупов (
insufficient_scope
), бот не в чате, или endpoint только для админов/владельцев
404Не найденоНеверный id. Проверь что сущность существует
401Не авторизованПроверь токен в заголовке Authorization
代码原因处理方式
422参数错误检查必填字段、数据类型、枚举值是否合法
429请求频率超限等待后重试。限制：约50次请求/秒，消息类接口约4次请求/秒
403无权限权限范围不足（
insufficient_scope
）、机器人未加入对应聊天，或该接口仅对管理员/所有者开放
404资源不存在ID错误。请确认资源是否存在
401未授权检查Authorization头中的令牌是否正确

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

可用操作

Новый тег

创建新标签

POST /group_tags
скоуп: 
group_tags:write
json
{
  "group_tag": {
    "name": "Новое название тега"
  }
}
POST /group_tags
权限范围：
group_tags:write
json
{
  "group_tag": {
    "name": "新标签名称"
  }
}

Список тегов сотрудников

获取员工标签列表

GET /group_tags
скоуп: 
group_tags:read
GET /group_tags
权限范围：
group_tags:read

Информация о теге

获取标签信息

GET /group_tags/{id}
скоуп: 
group_tags:read
GET /group_tags/{id}
权限范围：
group_tags:read

Редактирование тега

编辑标签

PUT /group_tags/{id}
скоуп: 
group_tags:write
json
{
  "group_tag": {
    "name": "Новое название тега"
  }
}
PUT /group_tags/{id}
权限范围：
group_tags:write
json
{
  "group_tag": {
    "name": "新标签名称"
  }
}

Удаление тега

删除标签

DELETE /group_tags/{id}
скоуп: 
group_tags:write
DELETE /group_tags/{id}
权限范围：
group_tags:write

Список сотрудников тега

获取标签下的员工列表

GET /group_tags/{id}/users
скоуп: 
group_tags:read
GET /group_tags/{id}/users
权限范围：
group_tags:read

Создать сотрудника

创建员工

POST /users
скоуп: 
users:create
json
{
  "user": {
    "email": "olegp@example.com"
  }
}
POST /users
权限范围：
users:create
json
{
  "user": {
    "email": "olegp@example.com"
  }
}

Список сотрудников

获取员工列表

GET /users
скоуп: 
users:read
GET /users
权限范围：
users:read

Информация о сотруднике

获取员工信息

GET /users/{id}
скоуп: 
users:read
GET /users/{id}
权限范围：
users:read

Редактирование сотрудника

编辑员工

PUT /users/{id}
скоуп: 
users:update
json
{
  "user": {}
}
PUT /users/{id}
权限范围：
users:update
json
{
  "user": {}
}

Удаление сотрудника

删除员工

DELETE /users/{id}
скоуп: 
users:delete
DELETE /users/{id}
权限范围：
users:delete

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

限制与注意事项

  • limit
    : максимум 50
  • user.role
    : допустимые значения — 
    admin
    (Администратор), 
    user
    (Сотрудник), 
    multi_guest
    (Мульти-гость)
  • Пагинация: cursor-based (limit + cursor), НЕ page-based
  • limit
    参数最大值为50
  • user.role
    的可选值：
    admin
    （管理员）、
    user
    （员工）、
    multi_guest
    （多平台访客）
  • 分页方式：基于cursor（limit + cursor），不支持基于页码的分页

Подробнее

更多详情

см. references/endpoints.md
请查看references/endpoints.md