api-restДата актуальности: 2026-06-17. Read-only документация.
Справочник REST-эндпоинтов, экспонируемых роутамиsmarty-backend-stable/api-rest/routes/.
Все маршруты подключены под префиксом /api/v2 (значение config.rest.api). Полный путь эндпоинта:
/api/v2 + basePath роутера + path createRoute
Для workspace-объектов добавляется сегмент /ws/:_wsId между префиксом и basePath роутера.
| Класс запроса | Описание |
|---|---|
AuthRequest |
Требует авторизованную сессию (cookie/token) + валидный аккаунт. В большинстве workspace-маршрутов дополнительно проверяется членство в workspace (req.profile = Employee). |
EmployeeRequest |
Авторизация через Employee (сессия + workspace scope). Доступен и для бот-токенов (sck_). |
ObjectsListRequest / ObjectInstanceRequest |
Наследники EmployeeRequest с предустановленными валидаторами для списков/единичных объектов. |
BasicRequest |
Без обязательной авторизации (но может быть добавлена через middleware). |
NoAuthRequest |
Явно без авторизации. |
WsApiRequest |
Авторизация через API-ключ workspace (для внешних интеграций). |
Каждый WorkspaceObject / RegularObject автоматически получает набор стандартных маршрутов через плагин PublicObject. Далее в таблицах они обозначены как "CRUD (collection)" и "CRUD (instance)".
Коллекция (/):
| Метод | Путь | Назначение |
|---|---|---|
GET |
/ |
Список объектов (фильтрация, пагинация, сортировка) |
GET |
/count |
Количество доступных объектов |
GET |
/random |
Случайный список объектов |
POST |
/ |
Создание объекта / массовое создание |
PATCH |
/ |
Массовое обновление (по ids[]) |
Единичный объект (/:_id):
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:_id |
Информация об одном объекте |
PATCH |
/:_id |
Обновление объекта |
Стандартные параметры запроса (query) для GET-списков:
| Параметр | Тип | Описание |
|---|---|---|
ids |
ObjectId[] |
Фильтр по ID |
skip |
Number |
Смещение (пагинация) |
limit |
Number |
Лимит (пагинация) |
sort |
String |
Сортировка |
fields |
String[] |
Выбор полей |
filter |
Object |
Дополнительные фильтры |
Все ответы оборачиваются в стандартный envelope Restify:
{
"result": { /* данные от handler */ },
"status": 200
}
Ошибки:
{
"error": {
"message": "Описание ошибки",
"code": "ERROR_CODE"
},
"status": 4xx/5xx
}
Многие модели подключают дополнительные плагины, добавляющие эндпоинты. Обозначения в таблицах:
| Плагин | Маршрут | Метод | Назначение |
|---|---|---|---|
Deletable |
/:_id |
DELETE |
Удаление объекта |
Archivable |
/:_id/archive |
POST |
Архивация |
Archivable |
/:_id/restore |
POST |
Восстановление из архива |
Markable |
/:_id/marks |
GET/POST/PATCH/DELETE |
Управление метками |
LinkableObject |
/:_id/links/:collectionName |
GET/POST/DELETE |
Связанные объекты |
HaveAttachedObjects |
/:_id/attaches |
GET/POST/DELETE |
Прикреплённые объекты |
WithAccessRights |
/:_id/access_rights |
GET/POST/PATCH/DELETE |
Права доступа |
WithAdminRights |
/:_id/admin_rights |
GET/POST/PATCH/DELETE |
Админ-права |
Searchable |
/search (collection) |
GET |
Полнотекстовый поиск |
StarableObject |
/stars (collection) |
GET/POST/DELETE |
Избранные объекты |
GeoLocated |
/:_id/geo |
GET/POST |
Геолокация |
SortObjects |
/sort (collection) |
POST |
Сортировка |
ImportExportObjects |
/import, /export |
POST |
Импорт/экспорт |
WsApiDirectAccess |
/:_id/wsapi-access |
GET/POST |
Прямой доступ через API |
crm.js)Базовый путь: /api/v2/ws/:_wsId/
Описание: "Объекты CRM"
contacts)Модель: Contact
Базовый путь: /api/v2/ws/:_wsId/contacts
Авторизация: AuthRequest (Employee)
Доп. роутеры: casesHistory, timeTracker, Comments, autoComplete
| Метод | Путь | Назначение |
|---|---|---|
GET |
/ |
Список контактов |
GET |
/count |
Количество контактов |
GET |
/random |
Случайные контакты |
POST |
/ |
Создание контакта |
PATCH |
/ |
Массовое обновление |
GET |
/:_id |
Информация о контакте |
PATCH |
/:_id |
Обновление контакта |
DELETE |
/:_id |
Удаление контакта |
GET |
/autoComplete |
Автодополнение |
Стандартные плагины: Deletable, Archivable, Markable, LinkableObject, HaveAttachedObjects, WithAccessRights, StarableObject, Searchable, GeoLocated, ObjectActivity, ObjectWithCustomFields, ImportExportObjects.
Вложенные роутеры:
/:_id/casesHistory/ -- история кейсов (GET, read-only)/:_id/timeTracker/ -- учёт времени (GET/POST/PATCH)/:_id/comments/ -- комментарии (GET/POST/PATCH/DELETE)projects)Модель: Project
Базовый путь: /api/v2/ws/:_wsId/projects
Авторизация: AuthRequest (Employee)
Доп. роутеры: timeTracker, Comments
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Вложенные роутеры:
/:_id/timeTracker/ -- учёт времени/:_id/comments/ -- комментарииtasks)Модель: Task
Базовый путь: /api/v2/ws/:_wsId/tasks
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
notes)Модель: Note
Базовый путь: /api/v2/ws/:_wsId/notes
Авторизация: AuthRequest (Employee)
Доп. роутеры: timeTracker, Comments
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Вложенные роутеры:
/:_id/timeTracker/ -- учёт времени/:_id/comments/ -- комментарииgoals)Модель: Goal
Базовый путь: /api/v2/ws/:_wsId/goals
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
requisitions)Модель: Requisition
Базовый путь: /api/v2/ws/:_wsId/requisitions
Авторизация: AuthRequest (Employee)
Доп. роутеры: casesHistory, timeTracker, Comments, logos
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Вложенные роутеры:
/:_id/casesHistory/ -- история кейсов/:_id/timeTracker/ -- учёт времени/:_id/comments/ -- комментарииСпециальные эндпоинты PracticeCard:
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
POST |
/:_id/practiceCard/display |
Auth + wsapi | Генерация и прикрепление карточки заявки |
POST |
/:_id/practiceCard/generate |
Auth + wsapi | Генерация карточки заявки (возвращает файл) |
POST |
/:_id/practiceCard/content |
Auth + wsapi | Данные карточки заявки |
Эндпоинты Helpdesk:
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
POST |
/:_id/helpdesk/accept |
Auth + wsapi | Взять заявку в работу (idempotent) |
POST |
/:_id/helpdesk/complete |
Auth + wsapi | Отметить заявку выполненной |
POST |
/:_id/helpdesk/reopen |
Auth + wsapi | Переоткрыть заявку |
POST |
/:_id/helpdesk/csat |
Auth + wsapi | Сохранить CSAT-оценку (body: rating 1-5, comment) |
assignments)Модель: Assignment
Базовый путь: /api/v2/ws/:_wsId/assignments
Авторизация: AuthRequest (Employee)
Доп. роутеры: timeTracker, Comments
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Вложенные роутеры:
/:_id/timeTracker/ -- учёт времени/:_id/comments/ -- комментарииcustomFields)Модели: CustomField, CustomFieldTemplate
Базовый путь: /api/v2/ws/:_wsId/custom_fields, /api/v2/ws/:_wsId/custom_field_templates
Авторизация: AuthRequest (Employee)
Оба -- стандартные WorkspaceObject с CRUD.
Шаблоны по умолчанию (default_templates):
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
GET |
/default_templates/ |
Employee | Список шаблонов по умолчанию для workspace |
POST |
/default_templates/collection_custom_fields/:collectionName |
Employee | Кастомные поля для списка объектов (body: ids[]) |
service_notes)Модель: ServiceNote
Базовый путь: /api/v2/ws/:_wsId/service_notes
Авторизация: AuthRequest (Employee)
Доп. роутеры: groups, linkGroups, categories
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
GET |
/:_id/deciders |
Auth | Список получателей |
POST |
/:_id/deciders |
Auth | Добавление получателей (body: ids[]) |
PATCH |
/:_id/deciders |
Auth | Перезапись получателей |
DELETE |
/:_id/deciders |
Auth | Удаление получателей (query: ids[]) |
POST |
/:_id/send |
Auth | Отправка записки получателям |
POST |
/:_id/recall |
Auth | Отзыв записки |
POST |
/:_id/make-decision |
Auth | Принятие решения (body: decision, comment) |
POST |
/:_id/archive |
Auth | Архивация единичной записки |
POST |
/:_id/restore |
Auth | Восстановление из архива |
POST |
/:_id/hide |
Auth | Индивидуальное удаление |
POST |
/archive (collection) |
Auth | Массовая архивация (body: ids[]) |
POST |
/restore (collection) |
Auth | Массовое восстановление |
POST |
/hide (collection) |
Auth | Массовое скрытие |
GET |
/get-new (collection) |
Auth | Новые служебные записки для текущего сотрудника |
Поля decision: new, in_process, viewed, confirmed, declined.
exportTemplate)Модель: ExportTemplate
Базовый путь: /api/v2/ws/:_wsId/export_templates
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
analytics_helpdesk)Базовый путь: /api/v2/ws/:_wsId/analytics/helpdesk
Авторизация: AuthRequest (Employee, через ObjectsListRequest)
Все эндпоинты -- POST с body-фильтрами. Общие параметры body:
| Поле | Тип | Описание |
|---|---|---|
start |
Number |
Начало периода (unix ms) |
end |
Number |
Конец периода (unix ms) |
_groupIds |
ObjectId[] |
Фильтр по группам |
priorities |
String[] |
Фильтр по приоритетам (low/normal/high/critical) |
responsibles |
ObjectId[] |
Фильтр по ответственным |
acceptedBy |
ObjectId[] |
Фильтр по принявшим |
completedBy |
ObjectId[] |
Фильтр по завершившим |
customFieldFilters |
[{_fieldId, value}] |
Фильтр по кастомным полям |
timeAxis |
String |
Поле для бакетинга: createdOn/acceptedAt/completedAt/enterTime |
bucketStepMs |
Number |
Шаг бакета (по умолчанию 24ч) |
| Метод | Путь | Назначение |
| --- | --- | --- |
POST |
/acceptanceTime |
Время от поступления до принятия (avgMs, medianMs, p90, p95) |
POST |
/resolutionTime |
Время от принятия до выполнения |
POST |
/firstResponseTime |
Время до первого ответа |
POST |
/sla |
Доля заявок в рамках SLA |
POST |
/backlogByAge |
Бэклог непринятых по возрасту |
POST |
/heatmapByHour |
Распределение по часам суток |
POST |
/reopenedTotals |
Статистика переоткрытий |
POST |
/reassignmentTotals |
Статистика переназначений |
POST |
/csat |
CSAT-распределение (1-5) |
POST |
/bottleneckByStage |
Узкие места по этапам (среднее время на этапе) |
botCardFields)Базовый путь: /api/v2/ws/:_wsId/card-fields
Авторизация: EmployeeRequest (сессия или sck_-токен)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/:groupId |
Поля карточки группы | query: collectionName |
POST |
/:groupId |
Создать/прикрепить поле | body: name (required), fieldType, typeValues, collectionName |
DELETE |
/:groupId |
Открепить поле от группы | body/query: fieldId или name |
stars)Базовый путь: /api/v2/ws/:_wsId/stars/:collectionName
Авторизация: AuthRequest (Employee, без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:collectionName |
Список избранных объектов типа |
POST |
/:collectionName |
Добавить в избранное (body: ids[]) |
DELETE |
/:collectionName |
Удалить из избранного (query: ids[]) |
collectionName -- любая StarableObject-модель (contacts, projects, tasks, notes, goals, requisitions, assignments, ...).
workspace.js)Базовый путь: /api/v2/ws/:_wsId/
Описание: "Служебные объекты"
workspace)Модель: Workspace (RegularObject)
Базовый путь: /api/v2/workspace
Авторизация: WorkspaceInstance (AuthRequest, без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
GET |
/workspace |
Список рабочих пространств пользователя |
GET |
/workspace/:_id |
Информация о workspace |
Специальные эндпоинты (instance):
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:_id/leave |
Покинуть рабочее пространство |
GET |
/:_id/locales |
Локали workspace |
GET |
/:_id/me |
Профиль сотрудника текущего пользователя |
GET |
/:_id/me/invites |
Исходящие приглашения в диалоги |
GET |
/:_id/me/related-dialog-participants |
Внешние участники диалогов |
GET |
/:_id/balance-history |
История баланса (полная) |
GET |
/:_id/balance-history/income |
История баланса (приход) |
GET |
/:_id/balance-history/outcome |
История баланса (расход) |
GET |
/:_id/exportToken |
Токен для импорта РП |
GET |
/:_id/order-info/:merchant_order_id |
Информация о заказе на пополнение |
POST |
/:_id/changeRate |
Изменение тарифа (body: rateId) |
GET |
/:_id/rates |
Список доступных тарифов |
POST |
/:_id/rates |
Проверка стоимости тарифа (body: rate) |
POST |
/:_id/pressFillBalance |
Кнопка "Пополнить баланс" |
POST |
/:_id/pbxIntegration |
Запрос на подключение Телефонии |
GET |
/:_id/billing_options |
Биллинг-опции |
GET |
/:_id/order |
Пакеты оплаты |
POST |
/:_id/order |
Создание заказа (body: _packId, money, autoPay) |
POST |
/:_id/stop_autopay |
Отмена автоплатежей |
POST |
/:_id/change-rate-window/close |
Закрытие окна смены тарифа |
GET |
/:_id/market |
Настройки маркета |
POST |
/:_id/market/enable |
Вкл/выкл интеграции (body: module, type, enable) |
POST |
/:_id/market/integrate |
Настройка интеграции (body: module, type, data) |
POST |
/:_id/market/integrate/sendRequisition |
Заявка на подключение интеграции |
POST |
/:_id/offer/accept |
Активация акций/промокодов (body: offer_id) |
Параметры market/enable и market/integrate:
module: sip, messengers, botstype: telkom, rostelecom, ertelecom, zadarma, mango_office, sipuni, uis, megafon, beeline, telegram, viber, vk, smarty_chat, zoom, whatsapp, whatsapp_waba, smarty_mail, smarty_doc, albato, smarty_bot, smarty_bot_constructorwsapi)Модель: WorkspaceApi
Базовый путь: /api/v2/ws/:_wsId/wsapi
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:_id/token |
Получение текущего токена |
GET |
/:_id/token/refresh |
Обновление токена |
marks)Модель: Mark
Базовый путь: /api/v2/ws/:_wsId/marks
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Динамические эндпоинты (для каждой Markable-модели):
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:_id/:collectionName |
Объекты типа с данной меткой |
GET |
/without-marks/:collectionName |
Объекты типа без меток |
GET |
/without-marks |
Количество объектов без меток |
employees)Модель: Employee
Базовый путь: /api/v2/ws/:_wsId/employees
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
GET |
/:_id/rights/access/full |
Auth | Полный список прав сотрудника |
PATCH |
/:_id/block |
Auth | Блокировка сотрудника |
PATCH |
/:_id/activate |
Auth | Активация сотрудника |
DELETE |
/:_id/activate |
Auth | Деактивация сотрудника |
GET |
/:_id/workgroups |
Auth | Группы сотрудника |
POST |
/:_id/workgroups |
Auth | Добавление в группы (body: ids[]) |
PATCH |
/:_id/workgroups |
Auth | Перезапись групп |
DELETE |
/:_id/workgroups |
Auth | Удаление из групп (query: ids[]) |
POST |
/invite (collection) |
Auth | Отправка приглашений (body: objects[]) |
DELETE |
/invite (collection) |
Auth | Отмена приглашений (query: ids[]) |
POST |
/:_id/hide |
Auth | Скрытие сотрудника |
POST |
/ai-models/:provider (collection) |
Auth | Список моделей AI-провайдера |
GET |
/ai-tools (collection) |
Auth | Список AI-инструментов |
POST |
/:_id/trigger/:triggerId/fire |
Auth | Ручной запуск триггера бота (body: message) |
POST |
/:_id/regenerate-connection-token |
Auth | Перегенерация service-токена (smarty_custom) |
employee_groups)Модель: EmployeeGroup
Базовый путь: /api/v2/ws/:_wsId/employee_groups
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Auth | Назначение |
|---|---|---|---|
GET |
/:_id/employees |
Auth | Сотрудники группы |
POST |
/:_id/employees |
Auth | Добавление сотрудников |
PATCH |
/:_id/employees |
Auth | Перезапись сотрудников |
DELETE |
/:_id/employees |
Auth | Удаление сотрудников |
access_rights)Модель: AccessRight
Базовый путь: /api/v2/ws/:_wsId/access_rights
Авторизация: AuthRequest (Employee, без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Дополнительно: objectsRightsHandler для Employee и EmployeeGroup (управление правами доступа сотрудников/групп к объектам).
admin_rights)Модель: AdminRight
Базовый путь: /api/v2/ws/:_wsId/admin_rights
Авторизация: AuthRequest (Employee, без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Дополнительно: objectsRightsHandler для Employee.
ai-models)Модель: Workspace
Базовый путь: /api/v2/ws/:_wsId/ai-models
Авторизация: AuthRequest (Employee, без wsapi/short)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/:provider |
Список моделей AI-провайдера | body: apiToken, customProviderEndpoint, customProviderHeaders, openaiCompatMode |
Rate limit: 10 запросов в минуту на workspace.
Провайдеры с опциональным токеном: smarty_custom, smarty.
bot-helpers)Базовый путь: /api/v2/ws/:_wsId/bot-helpers
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение |
|---|---|---|
GET |
/groups-tree |
Дерево групп workspace по коллекциям и категориям |
Возвращает { tree: { collectionName: { categoryLabel: [{_id, title, inArchive, isHide}] } } }. Для dialogs -- отдельная ветка с псевдо-категориями "Внешние" / "Внутренние публичные" / "Внутренние приватные".
bot-actions)Базовый путь: /api/v2/ws/:_wsId/bot-actions
Авторизация: AuthRequest (Employee)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/trigger |
Нажатие кнопки под сообщением бота | body: messageId (required), actionId (required) |
Idempotent: повторное нажатие возвращает status: 'already-used'.
bot-knowledge-bases)Базовый путь: /api/v2/ws/:_wsId/bot-knowledge-bases
Авторизация: AuthRequest (Employee, требуется manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Получить или создать KB для бота | query: botId (required) |
POST |
/ |
Создать KB | body: botId, title, description |
PATCH |
/:id |
Обновить KB | body: title, description, retrievalConfig, enableAutoRAG |
DELETE |
/:id |
Удалить KB (soft-delete, каскад) | -- |
GET |
/:id/documents |
Список документов | -- |
POST |
/:id/documents/text |
Индексировать текст | body: title, text |
POST |
/:id/documents/file |
Загрузить файл (multipart) | multipart: file (max 25MB) |
DELETE |
/:id/documents/:docId |
Удалить документ + чанки | -- |
POST |
/:id/reindex |
Переиндексировать KB | -- |
GET |
/:id/documents/:docId/chunks |
Чанки документа (текст + вектор) | -- |
PATCH |
/:id/documents/:docId/chunks/:chunkId |
Редактировать чанк + ре-embed | body: text (max 10000 chars) |
POST |
/:id/documents/:docId/chunks/:chunkId/reembed |
Ре-embed без изменения текста | -- |
DELETE |
/:id/documents/:docId/chunks/:chunkId |
Удалить чанк | -- |
POST |
/:id/search |
Семантический поиск | body: query, topK (1-20), minScore |
bot-token-usage)Базовый путь: /api/v2/ws/:_wsId/bot-token-usage
Авторизация: AuthRequest (Employee, требуется manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Сводка использования токенов ботом | query: botId (required) |
Возвращает агрегаты за сегодня / 7 дней / 30 дней / всё время: prompt_tokens, completion_tokens, cache_read_input_tokens, cache_creation_input_tokens, calls.
bot-traces)Базовый путь: /api/v2/ws/:_wsId/bot-traces
Авторизация: AuthRequest (Employee, требуется manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Список трассировок или одна трассировка | query: botId (required), traceId, limit, beforeId, q, status, model, triggerType, dialogId |
При указании traceId возвращает полную трассировку с шагами (LLM round-trips + tool calls).
bot-skills)Базовый путь: /api/v2/ws/:_wsId/bot-skills
Авторизация: AuthRequest (Employee; чтение -- membership, мутации -- manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Список навыков | query: scope (mine/library/all), category, q, visibility |
GET |
/:skillId |
Детали навыка (включая body) | -- |
POST |
/ |
Создать навык (private) | body: name (slug), title, description, body, category, ... |
PATCH |
/:skillId |
Обновить навык (own only) | body: поля из EDITABLE_FIELDS |
DELETE |
/:skillId |
Архивировать навык (own only) | -- |
POST |
/:skillId/publish |
Опубликовать (visibility=public) | -- |
POST |
/:skillId/unpublish |
Снять с публикации | -- |
POST |
/:skillId/link |
Привязать публичный навык | -- |
DELETE |
/:skillId/link |
Отвязать навык | -- |
POST |
/:skillId/fork |
Клонировать публичный/системный навык | -- |
Валидация name: slug, [a-z][a-z0-9-]{1,63}.
bot-plugins)Базовый путь: /api/v2/ws/:_wsId/bot-plugins
Авторизация: AuthRequest (Employee; чтение -- membership, мутации -- manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Список плагинов | query: scope (mine/library/all), category, q, visibility |
GET |
/:pluginId |
Детали плагина (connection только для owned) | -- |
POST |
/ |
Создать плагин (private) | body: name (slug), title, type, baseUrl, auth, actions, ... |
PATCH |
/:pluginId |
Обновить плагин (own only) | body: поля из EDITABLE_FIELDS |
DELETE |
/:pluginId |
Архивировать плагин (own only) | -- |
POST |
/:pluginId/publish |
Опубликовать | -- |
POST |
/:pluginId/unpublish |
Снять с публикации | -- |
POST |
/:pluginId/link |
Привязать публичный плагин | -- |
DELETE |
/:pluginId/link |
Отвязать плагин | -- |
POST |
/:pluginId/fork |
Клонировать (connection не копируется) | -- |
GET |
/:pluginId/oauth/start |
Получить URL для OAuth2 авторизации | -- |
Поля auth.type: none, api_key, bearer, oauth2, custom.
Поля type: api, mcp.
Fork idempotent: повторный fork возвращает существующую копию.
consultant)Базовый путь: /api/v2/ws/:_wsId/consultant
Авторизация: AuthRequest (Employee, любой member)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Получить/создать консультанта для workspace | -- |
GET |
/history |
История сообщений (до 200) | -- |
POST |
/message |
Отправить сообщение | body: content, attaches[], voice |
Голосовые сообщения: body.voice: { dataBase64, mime, transcript }. Если transcript пуст, автоматически транскрибируется через Whisper.
voiceTranscribe)Базовый путь: /api/v2/ws/:_wsId/voice
Авторизация: EmployeeRequest
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/transcribe |
Транскрибация аудио (Whisper) | body: dataBase64 (required, max 10MB), mime (default: audio/webm) |
widget-tokens)Базовый путь: /api/v2/ws/:_wsId/widget-tokens
Авторизация: AuthRequest (Employee, требуется manage_bots)
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/ |
Список токенов workspace | -- |
POST |
/ |
Создать токен | body: _botId (required), title, allowedDomains[], originAllowList[], rateLimitPerHour, budgetUsdCents, customization |
GET |
/:id |
Получить токен | -- |
PUT |
/:id |
Обновить токен | body: поля из sanitizeUpdatePayload |
DELETE |
/:id |
Отозвать токен (soft-revoke) | body: reason |
Slug формат: wt_ + 24 url-safe символа. Неизменяемый после создания.
Лимит: 50 токенов на workspace (soft-cap).
widget)Базовый путь: /api/widget (НЕ под /api/v2/)
Авторизация: Нет (анонимный доступ). Безопасность через токен + origin allow-list + rate limit.
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/:token/message |
Отправить сообщение боту | body: chatId, text (max 4000 chars) |
GET |
/:token/messages |
Получить сообщения диалога | query: chatId, since (msgId) |
GET |
/:token/config |
Конфигурация виджета (greeting, colors) | -- |
POST |
/:token/voice |
Отправить голосовое сообщение | multipart: audio (max 5MB), chatId |
GET |
/:token/demo |
Демо-страница виджета (HTML) | -- |
GET |
/_health |
Health check | -- |
Формат токена: wt_[A-Za-z0-9_-]{16,40}.
Rate limit: per-token + per-IP,滑动窗口 1 час.
CORS: Разрешён с любого origin (проверяется после резолва токена).
botPluginOAuth)Базовый путь: /api/v2/bot-plugins/oauth/callback
Авторизация: Нет (анонимный). Доверие через HMAC-signed state.
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
GET |
/bot-plugins/oauth/callback |
Callback от OAuth2-провайдера | query: code, state, error |
version)Базовый путь: /api/v2
Авторизация: BasicRequest (без авторизации)
| Метод | Путь | Назначение |
|---|---|---|
GET |
/version |
Текущая версия приложения |
GET |
/checkVersion |
Проверка поддерживаемой версии (headers) |
GET |
/about |
Информация о приложении (version, name, description, author, license) |
report)Базовый путь: /api/v2
Авторизация: Mixed
| Метод | Путь | Auth | Назначение | Параметры |
|---|---|---|---|---|
POST |
/feedback |
Auth (без wsapi) | Запрос в поддержку | body: message (required, max 5000), browser, name, os |
GET |
/hockey |
NoAuth | Хук для iOS crash-репортов | body: public_identifier, type, crash_reason, sent_at, title, url |
POST |
/deletionReport |
Auth (без wsapi) | Заявка на удаление аккаунта (1 раз/сутки) | body: reason (required) |
georoutes)Базовый путь: /api/v2
Авторизация: AuthRequest
| Метод | Путь | Auth | Назначение | Параметры |
|---|---|---|---|---|
GET |
/geocoding/geocode |
Auth + wsapi | Геокодирование (адрес -> координаты) | query: q, region, latLng, language, accuracy |
GET |
/countries |
Auth (без wsapi) | Список стран | -- |
checkPromoCode)Базовый путь: /api/v2
Авторизация: NoAuthRequest
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/check |
Проверка промокода | body: code (required) |
pdfBuilder)Базовый путь: /api/v2/pdfBuilder
Авторизация: AuthRequest + wsapi
| Метод | Путь | Назначение | Ответ |
|---|---|---|---|
POST |
/samFit |
PDF для samFit (фитнес-план) | stream: application/pdf |
POST |
/tshirt |
PDF для футболок | stream: application/pdf |
Параметры POST /samFit (body):
| Поле | Тип | Описание |
|---|---|---|
fileName |
String (max 100) | Название файла |
fullName |
String (max 100) | ФИО |
date |
Number | Дата (unix ms) |
age |
Number | Возраст |
height |
Number | Рост |
targetWeight |
Number | Желаемый вес |
foodType |
String (max 100) | Тип питания |
kcalFrom |
Number | Калораж от |
kcalTo |
Number | Калораж до |
targetDescription |
String (max 5000) | Цель |
weekOfPregnancy |
Number | Неделя беременности |
startDate |
Number | Дата начала (unix ms) |
weightHistory |
Number[] (max 5) | История веса |
renderGirthHistory |
Boolean | Рендер истории обхватов (default: true) |
waistHistory |
Number[] (max 5) | История обхвата талии |
hipsHistory |
Number[] (max 5) | История обхвата бёдер |
leftLegHistory |
Number[] (max 5) | История обхвата левой ноги |
rightLegHistory |
Number[] (max 5) | История обхвата правой ноги |
feelDescriptions |
String[] (max 5) | История ощущений |
dietDescriptions |
String[] (max 5) | История режима питания |
progressDescriptions |
String[] (max 5) | История прогресса |
facePhotoUrls |
String[] (max 5) | URL фото лицом |
sidewayPhotoUrls |
String[] (max 5) | URL фото боком |
backPhotoUrls |
String[] (max 5) | URL фото спиной |
Параметры POST /tshirt (body):
| Поле | Тип | Описание |
|---|---|---|
fileName |
String (max 100) | Название файла |
fullName |
String (max 100) | ФИО |
imageSrc |
String | Ссылка на изображение |
imageBuilder)Базовый путь: /api/v2/imageBuilder
Авторизация: AuthRequest + wsapi
| Метод | Путь | Назначение | Ответ |
|---|---|---|---|
POST |
/samFit |
Изображение для samFit | binary: image/jpeg |
POST |
/tshirt |
Изображение для футболок | binary: image/jpeg |
POST |
/wallpaper |
Изображение для ХК Торпедо | binary: image/jpeg |
POST |
/torpedo_contract |
Контракт для ХК Торпедо | binary: image/jpeg |
POST |
/wallpaper-baltica |
Изображение для ФК Балтика | binary: image/jpeg |
Параметры POST /samFit (body): аналогичны PDF-билдеру /samFit.
Параметры POST /tshirt (body): аналогичны PDF-билдеру /tshirt.
Параметры POST /wallpaper (body):
| Поле | Тип | Описание |
|---|---|---|
fileName |
String (max 100) | Название файла |
number |
String (max 99) | Номер |
fullName |
String (max 100) | ФИО |
Параметры POST /torpedo_contract (body):
| Поле | Тип | Описание |
|---|---|---|
fileName |
String (max 100) | Название файла (при значении torpedo -- контракт Торпедо) |
fullName |
String (max 100) | ФИО |
Параметры POST /wallpaper-baltica (body):
| Поле | Тип | Описание |
|---|---|---|
fileName |
String (max 100) | Название файла |
number |
String (max 99) | Номер |
fullName |
String (max 100) | ФИО |
news)Модель: News (RegularObject)
Базовый путь: /api/v2/news
Авторизация: AuthRequest (без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/read (collection) |
Массовое прочтение | body: ids[], action (read/close) |
POST |
/:_id/read |
Прочтение новости | body: action (read/close) |
unattended)Модель: UnattendedOperation (RegularObject)
Базовый путь: /api/v2/unattended_operations
Авторизация: AuthRequest (без wsapi)
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
comments)Модель: Comment
Подключается к: contacts, projects, notes, requisitions, assignments
Базовый путь: /:_parentId/comments/
Авторизация: AuthRequest (Employee), baseObject: 'object'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
cases_history)Модель: ObjectCasesHistory
Подключается к: contacts, requisitions
Базовый путь: /:_parentId/casesHistory/
Авторизация: AuthRequest (Employee), baseObject: 'object', read-only
| Метод | Путь | Назначение |
|---|---|---|
GET |
/ |
Список записей истории |
GET |
/:_id |
Одна запись |
time_tracker)Модель: TimeTracker
Подключается к: contacts, projects, notes, requisitions, assignments
Базовый путь: /:_parentId/timeTracker/
Авторизация: AuthRequest (Employee), baseObject: 'object'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD (без DELETE) |
groups)Модель: Group
Подключается к: contacts, projects, tasks, notes, goals, requisitions, assignments, service_notes, access_rights
Базовый путь: /groups/ (collection)
Авторизация: AuthRequest (Employee), baseObject: 'model'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Назначение |
|---|---|---|
GET |
/objects/count |
Количество объектов в группах (по этапам) |
stages)Модель: Stage
Подключается к: тем же моделям, что и groups
Базовый путь: /stages/ (collection)
Авторизация: AuthRequest (Employee), baseObject: 'model'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD (без create, delete) |
Специальные эндпоинты:
| Метод | Путь | Назначение | Параметры |
|---|---|---|---|
POST |
/copy |
Копирование настроек этапов | body: from (GroupId), to (GroupId), includeFiles |
categories)Модель: Category
Подключается к: service_notes, access_rights
Базовый путь: /categories/ (collection)
Авторизация: AuthRequest (Employee), baseObject: 'model'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
link_groups)Модель: LinkGroup
Подключается к: service_notes, contacts, projects, notes, goals, requisitions, assignments
Базовый путь: /:_parentId/link_groups/
Авторизация: AuthRequest (Employee), baseObject: 'object'
| Метод | Путь | Назначение |
|---|---|---|
| CRUD (collection/instance) | Стандартные | Стандартные CRUD |
Специальные эндпоинты:
| Метод | Путь | Назначение |
|---|---|---|
GET |
/:_id/objects |
Сгруппированные связанные объекты |
POST |
/:_id/objects |
Добавление объектов в группу связей |
PATCH |
/:_id/objects |
Перезапись объектов в группе |
DELETE |
/:_id/objects |
Удаление объектов из группы |
| Область | Причина |
|---|---|
| Подробные схемы body для каждого CRUD-эндпоинта | Определяются динамически из модели (buildSchema); список полей зависит от конкретной модели CRM |
Реализация Object.createObjectLowLevel() |
Глубокая логика в smarty-db |
Плагины Restify: SynchronizableObject, IndividualSortObjects, Groupable, CheckParamExisting, OcrSupport, TimeTrackAnalytics, WithReaction, EmployeeObjectConfiguration, GroupingElementRights |
Внутренние маршруты, формируемые плагинами; документируются при необходимости |
Внутренние маршруты smarty-ui, smarty-tracker, smarty-helpdesk, smarty-rights |
Подключены как внешние роутеры; свои документы |
Маршруты smarty-dialog (под /ws/:_wsId/dialogs/) |
Документированы в smarty-dialog/docs/API.md |