REST API модуля «Управление целями»

Справочник REST-методов модуля ithive.goalsmanagement для интеграций, входящих вебхуков и AI-агентов.

Базовый URL

https://{портал}/rest/{user_id}/{webhook_code}/{method}.json

Пример:

https://portal.company.ru/rest/1/xxxxxxxx/goalsmanagement.process.list.json

Scope и аутентификация

  • Scope: goalsmanagement
  • Аутентификация: входящий вебхук Bitrix24 или OAuth/сессия авторизованного пользователя
  • Все методы goalsmanagement.* требуют авторизованного пользователя REST. Без авторизации — ошибка UNAUTHORIZED. Дополнительно методы проверяют права модуля (ModuleUser::*) и/или права на конкретную сущность (иначе ACCESS_DENIED / PERMISSION_DENIED / CARD_NOT_FOUND и т.п.).

Авторизация ≠ право на операцию: наличие вебхука само по себе не даёт, например, право создавать процессы или менять статусы чужих карточек.

Права доступа

Права задаются логикой Goals\ModuleUser (роли модуля: администратор модуля, руководитель, сотрудник, внутренний контроль и флаги canView* / canAdd* / canEditStructure и т.д.). Конкретные опции групп — в настройках модуля на портале.

Сводка по группам методов

Группа методов Кто может (как в коде)
Служебные (schema) Любой авторизованный
process.list/get/... Чтение: canViewProcess; запись add/update/delete/saveBinding: обычно admin/module admin (canAddProcess / admin)
goalcard.* Чтение: assertCanView / canViewControl; create/activate/…: admin/head; changeStatus/approve: head/admin по правилам карточки; sendNotify: только админ модуля/портала
goalitem.* Доступ к карточке + владелец/admin/head; delete с confirm=true при каскаде
ratingcard.* / ratingitem.* Аналогично карточкам оценки / правам ModuleUser
goal.* (каталог) canViewGoal / canAddGoal для записи
task.* Авторизованный; add — права на задачу отдела

В шапках отдельных методов формулировка «Кто может вызывать» даёт краткий итог по коду; детали — в этом разделе.

Формат ответа

Внутренний конверт модуля (в result обёртки Bitrix REST):

Поле Описание
result Данные или null при ошибке
total Количество записей (для list-методов; в webhook часто на верхнем уровне Bitrix)
next Смещение следующей страницы или null
error null или { code, message, details }

Пагинация

Для list-методов:

Параметр По умолчанию Описание
limit 50 Размер страницы, максимум 500
offset 0 Смещение
fetchAll false Вернуть все записи одним ответом. Защитный лимит (по умолчанию 5000); при превышении — FETCH_ALL_LIMIT_EXCEEDED
filter - Mongo-style фильтр ($eq, $in, $gte, ...)

Пакетные вызовы

Отдельного метода goalsmanagement.batch нет. Несколько goalsmanagement.* за один HTTP-запрос — штатный batch Битрикс24 (/rest/{user_id}/{webhook_code}/batch.json).

Именование upsert

Методы сохранения целей/оценок карточки публикуются как goalitem.upsert и ratingitem.upsert (не *.save): часть WAF блокирует REST-пути, оканчивающиеся на .save.

Что отсутствует в текущем коде

  • goalsmanagement.process.status.list — не реализован

Разделы справочника

Раздел Описание
Служебные schema
Процессы process.*
Карточки целей goalcard.*
Цели карточки goalitem.*
Карточки оценки ratingcard.*
Оценки ratingitem.*
Каталог целей goal.*
Задачи task.*
Коды ошибок Полный перечень

Всего методов в текущем коде: 47.

Предыдущая
Установка, обновление и удаление модуля
Следующая
Коды ошибок