Зона покрытия публичного API

Public API (публичный API) Case.one разработан специально для управления настройками, которые необходимы для:

Интеграции со сторонними системами.
Мобильных приложений.
Скриптов в сценариях автоматизации.

Методы публичного API позволяют получать информацию, обновлять или удалять данные и создавать различные сущности в Case.one.

На текущий момент вы можете использовать методы публичного API v1, v2, v3 и v4 (подробнее о версиях см. в статье Как правильно выбрать версию API?).

Зона покрытия Public API функционала Case.one

Функционал	Возможности
Авторизация	— Получение или обновление токена — Получение токена доступа с аутентификацией Windows
Основные настройки	— Получение нерабочих дней (конкретные даты и интервалы) (v3) — Обновление нерабочих дней (конкретные даты и интервалы) (v3)
Объекты	— Создание объекта — Обновление объекта — Редактирование объекта — Получение объекта по идентификатору — Получение списка объектов — Архивация объекта — Восстановление объекта из архива — Удаление объекта — Добавление участника в объект — Создание связанного объекта — Получение списка связанных объектов — Удаление связанного объекта — Получение дел любого типа с указанием параметров (v3) — Получение объектов любого типа с указанием параметров (v3) — Получение списка объектов, которые находятся в таблице, с информацией по каждому объекту
Типы объектов	— Получение типа объекта по идентификатору (v1, v2) — для метода v1 в ответе рассчитывается текущая дата и отдается в качестве значения по умолчанию — Получение списка типов объектов
Классы объектов	— Получение класса объекта по идентификатору — Получение списка классов объектов
Роли в деле	— Получение роли в деле по идентификатору — Получение всех ролей в деле
Папки	— Получение папки — Получение списка папок
Проекты	— Получение проекта — Получение списка проектов
События	— Создание события — Создание события (v3) — Обновление события — Обновление события (v3) — Получение события — Получение события (v3) — Получение списка событий — Удаление события — Получение информации по типу события — Получение списка типов событий
Задачи	— Создание задачи — Создание задачи с дополнительными атрибутами (v3) — Обновление задачи — Обновление задачи с дополнительными атрибутами (v3) — Получение задачи — Получение задачи с дополнительными атрибутами (v3) — Получение списка задач — Удаление задачи — Получение информации по типу задачи — Получение списка типов задач — Получение информации по статусу задачи — Получение списка статусов задач — Получение информации по приоритету задачи — Получение списка приоритетов задач
Документы	— Создание документа (v3) — Создание документа по шаблону (v3) — Обновление документа (v3) — Получение документа по идентификатору (v3) — Получение списка документов (v3) — Скачивание документа (v3) — Удаление документа (v3) — Скачивание файла документа в формате PDF для печати (с наложенной подписью) (v3) — Скачивание файла подписи документа (v3)
Участники	— Создание участника с дополнительными атрибутами — Редактирование участника с дополнительными атрибутами — Получение участника — Получение списка участников — Создание участника с дополнительными атрибутами (v3) — Редактирование участника с дополнительными атрибутами (v3) — Получение участника (v3) — Удаление участника (v3) — Исключение участника из дела/объекта (v3) — Создание участника (v4) — Редактирование участника (v4) — Получение участника (v4)
Организационно-правовая форма	— Получение организационно-правовой формы — Получение списка организационно-правовых форм
Пользователи	— Получение пользователя — Получение списка пользователей — Уведомление сообщением одного пользователя
Справочники	— Получение справочника по идентификатору — Получение списка справочников — Получение значения справочника по идентификатору — Получение списка значений справочника
Файлы	— Извлечение файлов из архива и их сохранение в файловом хранилище (v1) — Загрузка файлов в Систему — Скачивание файла
Звонки	— Создание звонка — Отправка уведомления о звонке — Прикрепление записи к звонку — Загрузка записи звонка
Сценарии автоматизации	— Запуск скрипта
Права роли	— Установка прав роли (v4) — Создание роли и установка прав (v4) — Создание роли с назначенными правами (v4) — Обновление прав роли (v4) — Удаление прав роли (v4) — Получение списка прав для роли (v4)
Служебные запросы	— Проверка состояния работоспособности сервиса — Метод проверки состояния системы (v3)
Логи	— Скачивание лога выполнения сценария автоматизации (v3)

Аутентификация пользователя — Auth

Запросы выполняются от имени аутентифицированного пользователя. Методы API учитывают права пользователя. Если пользователь заблокирован, то он не может выполнять запросы по API. Также доступна аутентификация в публичном API с помощью токена, полученного в SSO Keycloak (OpenID).

Методы позволяют авторизоваться пользователю для выполнения запросов:

POST /api/v2/auth/token — метод позволяет получить или обновить токен доступа.
POST /api/v2/auth/wintoken — метод позволяет получить токен доступа с аутентификацией Windows.

Доступные версии: V1, V2.

Основные настройки — GeneralSettings

Группа методов по работе с общими настройками:

GET /api/v3/generalsettings/NonWorkingDays — метод позволяет получить список нерабочих дней (конкретные даты и интервалы).
PUT /api/v3/generalsettings/NonWorkingDays — метод позволяет обновить настройки нерабочих дней (конкретные даты и интервалы).

Доступные версии: V3.

Группы методов для работы с объектами

Методы для работы с объектами, их классами и типами, а также папками и проектами распределены по следующим группам:

Классы объектов — ObjectClasses
Типы объектов — ObjectTypes
Папки дел/объектов — Folders
Проекты — Projects
Объекты — Objects
Проекты — Projects
Роли в деле — RolesInCase

По всем методам работы с объектами в V1 доступны аналогичные методы, которые выполняются только для дел (методы V1 полностью перенесены в методы V2).

Специфика работы с методами API, которые предназначены для работы с объектами и делами, а также с классами и типами объектов, паками, проектами и участниками в деле:

Если у пользователя права на Просмотр или нет прав на блок в объекте/деле, то при создании/редактировании такого объекта/дела через публичный API, заполняя/редактируя блок, в результате будет получен ответ 201, а отправленные значения игнорируются.
Заполнение кастомных полей:
- В методах API по работе с объектом/делом доступно заполнить кастомные поля дела/объекта, передав JSON-объект в формате — тег поля : значение
- Заполнение системных полей таким образом не предусмотрено
- Система позволяет работать с объектами любого класса
- Если у поля нет тега, то в качестве тега используется Id поля (данное значение не отображается на UI)
- В методах публичного API v1 и v2 по работе с объектами выполняется проверка формата кастомных полей, что позволяет корректно заполнять поля карточки дела и избежать ошибок при формировании отчетов по этим полям
Таблицы объектов — в следующих методах API отсутствуют блоки с типом Таблица в ответе:
- ObjectTypes/GET/api/v1/caseTypes/{id}
- ObjectTypes/GET/api/v1/objectTypes/{id}
- ObjectTypes/GET/api/v2/caseTypes/{id}
- ObjectTypes/GET/api/v2/objectTypes/{id}
Проверка на дубли — при создании или редактировании объектов через публичный API в запросе присутствует параметр CheckForDuplicates для проведения валидации данных объекта по правилам определения дубликатов:
- Параметр CheckForDuplicates доступен в следующих методах поддерживаемых версий:
  - Создание объекта
  - Обновление объекта (PUT)
  - Редактирование объекта: (PATCH)
  - Архивация объекта;
  - Восстановление объекта из архива.
- При установке значения False в параметре CheckForDuplicates:
  - Валидация данных объекта не выполняется
  - Объект создается / редактируется через API без валидации атрибутов предаваемого объекта по правилам определения дубликатов
- Если установлено значения True в параметре CheckForDuplicates при передаче запроса вышеуказанными методами, валидация атрибутов предаваемого объекта по правилам определения дубликатов работает по следующему по принципу:
  - Проверяемый объект валидируются по правилу определения дубликата соответствующего типа объектов:
    - Если предаваемый объект не определен как дубликат — объект создается, изменения в объекте сохраняются
    - Если предаваемый объект определен как дубликат — объект не создается, изменения в объекте не сохраняются и будет отправлен ответ об ошибке с полями (см. в таблице ниже)
  - Валидация проверяемого объекта по правилам определения дубликатов не учитывает флаг Запрещать создавать дубликаты — вне зависимости от установки флага при передаче запроса по API, если передаваемый объект определен как дубликат, он не будет создан, все изменения не будут сохранены (процесс создания и редактирования объектов соответствует стандартному механизму):
    - Если правило определения дубликатов не настроено для типа объекта
    - Если правило определения дубликатов не настроено для типа объекта, но в атрибуте запроса CheckForDuplicates передано значение True, параметр игнорируется
    - Если настроенное правило стало невалидным из-за удаления поля, участвующего в правиле, валидация по такому правилу не запускается
В публичном API получения, создания и редактирования объекта доступно использование полей с типом Объект-Пользователь.

Название поля	Описание	Значения Поля
Error	Название ошибки	Невозможно создать дубликат.
ErrorType	Тип ошибки	Conflict.
ConflictMessage	Описание конфликта	В Системе уже есть объекты с похожим набором данных (список уникальных полей из правила определения дубликатов).
ConflictObjects	Массив идентификаторов объектов, по которым проверяемый объект определен как дубликат	Массив идентификаторов.

Классы объектов — ObjectClasses

Доступные версии: V1, V2:

GET /api/v2/objectClasses/{id} — метод позволяет получить класс объекта по идентификатору, в результате будет возвращена подробная информация по указанному классу объекта.
GET /api/v2/objectClasses — метод позволяет получить все классы объектов:
- Доступна фильтрация по классу объекта
- Список классов выводится объектов без паджинации

Типы объектов — ObjectTypes

Доступные версии: V1, V2:

GET /api/v2/objectTypes/{id} (или /api/v2/caseTypes/{id}) — метод позволяет получить тип объекта по идентификатору, в результате будет возвращена подробная информация по указанному типу объекта/дела (тип объекта/дела содержит метаданные объектов/дел), включая информацию о классе объекта.
GET /api/v2/objectTypes (или /api/v2/caseTypes) — метод позволяет получить все типы объектов:
- В выходных данных отображается статус типа объекта/дела: активен/ удален
- Доступна фильтрация по классу объекта

Папки дел/объектов — Folders

Доступные версии: V1, V2:

GET /api/v2/folders/{id} — метод позволяет получить указанную папку, которая содержит объекты, дела и проекты, по идентификатору.
GET /api/v2/folders — метод позволяет получить список папок:
- Доступна фильтрация по классу объекта
- В API V1:
  - В выходных данных нельзя запросить папки с учетом вложенности
  - Выходные данные не содержат информацию о вложенности
- В выходных данных папки отсортированы по алфавиту (паджинация по 100 значений)
- Метод позволяет возвращать:
  - Дочерние папки по указанному Id папки родителя
  - Папки по указанному имени папки — поиск выполняется по вхождению, при этом каждая папка возвращается со всеми вложенными папками
  - Структуру папок и вложенных подпапок с учетом прав (числовое значение)
- Особенности поиска и паджинации:
  - Если PageSize — 20, будут возвращены первые 20 папок и все подпапки в них
  - Если поиск по имени вернет 2 папки, причем одна папка является подпапкой другой, вернутся список из 2-х папок (включая их иерархию)
  - Если указаны и Id папки, и Название, поиск выполняется по названию папки, среди папок, являющихся дочерними для папки, Id которой указано в запросе

Пример:

Папка 1

Папка 1.1
Папка 1.2
- Папка 1.2.1
  - Папка 1.2.1.1
  - Папка 1.2.1.2
- Папка 1.2.2.
  - Папка 1.2.2.1

При поиске по Папка 1 в результате будет вся описанная выше структура.

При поиске по Папка 1.2.1 в результате будет:

Папка 1.2.1
- Папка 1.2.1.1
- Папка 1.2.1.2

Проекты — Projects

Доступные версии: V1, V2:

GET /api/v2/projects/{id} — метод позволяет получить указанный проект, который содержит объекты/дела, по идентификатору.
GET /api/v2/projects — метод позволяет получить список проектов для дел/объектов и их положение в папках:
- Доступна фильтрация по папке и по классу объекта
- В выходных данных проекты отсортированы по алфавиту (паджинация по 100 значений)

Объекты — Objects

Доступные версии: V1, V2, V3.

API V2 (V1):

POST /api/v2/objects — метод позволяет создать объект с блоками:
- Создание объекта должно выполняться одним запросом — т.е. в одном запросе сразу указывается тип объекта, проект и папка для объекта и данные из карточки объекта
- Метод не относится к созданию дела из клиентского запроса
- Возможно заполнение полей объекта по внешнему идентификатору (External ID):
  - Идентификатор позволяет заполнить одно или несколько полей объекта без учета структуры объекта — т.е. доступно передать значение нескольких полей в объекте с их External ID и в объекте заполнятся только эти значения (остальные значения полей не будут удаляться)
  - Если в блоке есть одно или несколько заполненных полей, при редактировании любого поля в этом блоке все обязательные поля в этом блоке также должны быть заполнены
  - Для заполнения мультистрок/мультиблока значения полей передаются в виде массива
PUT /api/v2/objects/{id} — метод позволяет обновить объект с блоками по идентификатору:
- В методе есть необязательные параметры, которые позволяют проверить актуальность сохраненной версии карточки объекта/дела при редактировании в многопользовательском режиме:
  - Version — версия объекта (integer($int64))
  - IsVersionEnabled — проверить версию объекта (boolean)
- Работа метода зависит от этих необязательных параметров:
  - Если параметры не переданы, методы выполняются как раньше
  - Если параметры переданы, сначала выполняется проверка на актуальность версии дела/объекта — если передана не актуальная версия, обновление дела/объекта не выполняется, возвращается ошибка
PATCH /api/v2/objects/{id} — метод позволяет изменить объект с блоками по идентификатору:
- В методе доступно удалить сразу весь блок и/или строку, избегая изменения массива значений каждого поля:
  - Явно указывается порядковый номер мультистроки и/или мультиблока в деле, которые необходимо удалить
  - Доступно удаление пустой строки и/или блока, в котором есть поле формата Чекбокс
- В методе есть необязательные параметры, которые позволяют проверить актуальность сохраненной версии карточки объекта/дела при редактировании в многопользовательском режиме:
  - Version — версия объекта (integer($int64))
  - IsVersionEnabled — проверить версию объекта (boolean)
- Работа метода зависит от этих необязательных параметров:
  - Если параметры не переданы, методы выполняются как раньше
  - Если параметры переданы, сначала выполняется проверка на актуальность версии дела/объекта — если передана не актуальная версия, обновление дела/объекта не выполняется, возвращается ошибка
GET /api/v2/objects/{id} — метод позволяет получить объект по идентификатору, включая информацию обо всех заполненных полях в объекте:
- В выходных параметрах отображается параметр DocumentFolderId, указывающий на корневую папку дела
- Значение null приходит только для полей, которые не определены
GET /api/v2/objects и GET /api/v2/cases — методы позволяют получить список объектов/дел с папками и проектами:
- Доступна фильтрация по последней дате изменения объекта/дела, дате создания, ответственному, статус (архив/в работе), папке, проекту, типу объекта, классу объекта
- В выходных данных объекты отсортированы по алфавиту и далее – по дате создания, паджинация по 100 значений
- В выходных данных содержится информация: тип объекта, ответственный, дата создания, статус, проект и папка
- В выходных параметрах отображается параметр DocumentFolderId, указывающий на корневую папку дела
- Доступно выполнять поиск по пустым или непустым значениям — в блоке Filters доступен необязательный атрибут IsEmpty (аналогично решению в Отчетах) с возможными атрибутами:
  - null — не используется фильтрация
  - true — фильтрация по пустым полям
  - false — фильтрация по заполненным полям

Пример запроса с заполненным блоком Filters:

{

"ObjectClassId": "5a0f18af-d677-ec11-80e6-000d3af7ae73",

 "Filters": [

   {

    "FieldTag": "td_tag1",

    "IsEmpty": false,

   }],

 "IsFormattedTextEnabled": true,

 "Page": 1,

 "PageSize": 1

}

Если используется конструкция "IsEmpty": false, невозможно использовать другие способы фильтрации (будет ошибка в ответе):

"SearchValues": [

 "string"

 ],

 "BeginValue": "string",

 "EndValue": "string"

Например, при использовании конструкции:

"Filters": [

 {

   "FieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

   "FieldTag": "tag1",

   "IsEmpty": true,

   "SearchValues": [

     "4"

    ], }]

POST /api/v2/objects/{id}/archive и POST /api/v2/cases/{id}/archive — методы позволяют заархивировать объект/дело.
POST /api/v2/objects/{id}/restore и POST /api/v2/cases/{id}/restore — методы позволяют восстановить объект/дело из архива.
DELETE /api/v2/objects/{id} и DELETE /api/v2/cases/{id} — методы позволяют удалить объект/дело (удаление доступно только для архивных объектов/дел).
POST /api/v2/objects/{id}/participants и POST /api/v2/cases/{id}/participants — методы позволяют добавить участника в объект/дело и при необходимости установить роль участнику в объекте/деле. Необходимы права Редактирование на объект/дело и Просмотр на участников.

API V3 — в методах API V3 доступно выгрузить объекты любого типа с указанием параметров (например, в качестве параметров могут выступать теги):

POST /api/v3/objects/GetObjects — метод позволяет получить список объектов, среди параметров могут быть теги, и должна быть возможность указывать несколько значений для нескольких тегов.
POST /api/v3/objects/GetCases — метод позволяет получить список дел, среди параметров могут быть теги, и должна быть возможность указывать несколько значений для нескольких тегов.
POST /api/v3/objects/GetTableObjects — метод позволяет получить список объектов, которые находятся в таблице, с информацией по каждому объекту:
- Метод позволяет получить по идентификатору блока:
  - Список объектов, которые находятся в таблице
  - Список данных по каждому объекту
- В одном запросе доступно получить данные по одной таблице
- Если идентификатор блока таблицы указан некорректно или не существует, в ответе возвращается ошибка
- Порядок значений для мультиполей может не совпадать с порядком полей, которые выведены в таблице

Во входящих параметрах метода:

Обязательный параметр — ID блока таблица
Необязательные параметры:
- ID объекта, в котором вложена таблица.
- Поле, по которому производится сортировка данных в таблице
- Инлайн фильтры по таблице
- Полнотекстовый поиск

На выходе возвращается массив, содержащий список объектов с паджинацией:

Идентификатор объекта
Значение кастомных полей:
- В формате: “tag”: “string”, если у поля есть тег
- В формате: “id”: “string”, если у поля нет тега
- Для мультиполей (в обычном блоке, в мультиблоке) передается один массив значений
Для системных полей вместо Id передается название поля в следующем соответствии:
- Название — Project_Name
- Номер — Project_FullNumber
- Время создания — Project_CreationDate_Time
- Дата создания — Project_CreationDate
- Клиент — Project_Client_Name
- Описание — Project_Description
- Ответственный — Project_Responsible
- Стадия — Project_Stage_Name
- Статус — Project_IsArchive
- Тип — Project_ProjectType_Name

Связанные объекты — RelatedObjects

В качестве основы методов взяты методы внутреннего API в упрощенном виде:

GET /api/v2/objects/{objectId}/relatedObjects — метод позволяет получить список связанных объектов по идентификатору дела/объекта (права на дело должны быть Просмотр или выше).
POST /api/v2/objects/{objectId}/relatedObjects — метод позволяет создать связанный объект (права на дело должны быть Редактирование или выше).
DELETE /api/v2/objects/{objectId}/relatedObjects — метод позволяет удалить объект из списка связанных объектов в выбранном объекте (права на дело должны быть Редактирование или выше).

Если уровня прав не хватает или отсутствуют права, отобразится ошибка. Не проверяются права на добавленные объекты.

Доступная версия — V2.

Роли в деле — RolesInCase

Доступные версии: V1, V2:

GET /api/v2/rolesInCase/{id} — метод позволяет получить подробную информацию об указанной роли в деле/объекте по идентификатору.
GET /api/v2/rolesInCase — метод позволяет получить список всех ролей в деле/объекте.

Группы методов для работы с событиями

Методы для работы с событиями распределены по следующим группам:

События — Events
Типы событий — EventTypes

События — Events

Доступные версии: V1, V2, V3.

API V2 (V1):

POST /api/v2/events — метод позволяет создать событие:
- Событие создается одним запросом, даже если по типу события указаны дополнительные атрибуты
- Можно не передавать:
  - Календарь (всегда создавать в Firm)
  - Location
  - Reminder
PUT /api/v2/events/{id} — метод позволяет обновить событие.
GET /api/v2/events/{id} — метод позволяет получить событие по идентификатору.
GET /api/v2/events — метод позволяет получить список событий (возможна фильтрации по: делу, дате начала события).
DELETE /api/v2/events/{id} — метод позволяет удалить событие по идентификатору.

API V3:

POST /api/v3/events — метод позволяет создать событие с заполненными доп. атрибутами:
- Работа с созданными полями выполняется через связку Тег — Значение
- Если у поля нет тега, то в качестве тега используется Id поля
PUT /api/v3/events/{id} — метод позволяет обновить событие с заполненными доп. атрибутами:
- Работа с созданными полями выполняется через связку Тег — Значение
- Если у поля нет тега, то в качестве тега используется Id поля
GET /api/v3/events/{id} — метод позволяет получить событие с заполненными доп. атрибутами по идентификатору:
- Работа с созданными полями выполняется через связку Тег — Значение
- Если у поля нет тега, то в качестве тега используется Id поля
- В результате будут получены основные данные по событию и доп. атрибуты в виде Тег — Значение

Типы событий — EventTypes

Доступные версии: V1, V2:

GET /api/v2/eventTypes/{id} — метод позволяет получить подробную информацию по указанному типу события по идентификатору.
GET /api/v2/eventTypes — метод позволяет получить список всех типов событий.

Группы методов для работы с задачами

Методы для работы с задачами распределены по следующим группам:

Задачи — Tasks
Типы задач — TaskTypes
Статусы задач — TaskStatuses
Приоритеты задач — TaskPriorities

В публичном API проверяются права пользователя на Создание и Удаление задач.

Задачи — Tasks

Доступные версии: V1, V2, V3.

При работе с методами группы Tasks вам доступны следующие операции с документами:

Получение информации о документах, прикрепленных к задаче.
Прикрепление/открепление существующих в Case.one документов в задачу.
Создание задачи с загруженным в Case.one документом или несколькими документами.

API V2 (V1):

POST /api/v2/tasks — метод позволяет создать задачу:
- Задача создается одним запросом, даже если по названию задачи указаны дополнительные атрибуты
- Название задачи доступно выбрать только из соответствующего справочника, из уже существующих значений
- При создании задачи через API это попадает в историю задачи
- Можно создать задачу с прикреплением одного или нескольких документов:
  - В исходящих параметрах запроса доступно передать идентификаторы всех документов, которые должны быть прикреплены к задаче
  - Если в задаче есть хотя бы один документ, в ответе отображаются данные по каждому из указанных в запросе документах: идентификатор документа и название документа
- Можно не передавать:
  - Файлы
  - Ремайндеры
PUT /api/v2/tasks/{id} — метод позволяет обновить задачу:
- Изменение задачи через API попадает в историю задачи
- Возможно прикрепить (или открепить) к задаче один или сразу несколько документов:
  - В исходящих параметрах запроса доступно передать идентификаторы всех документов, которые должны быть прикреплены к задаче:
    - Если в параметрах запроса передается пустой массив Documents, документы будут удалены из задачи
    - Если в параметрах запроса для документа передается значение null, документы останутся без изменений
    - Если включить в запрос параметры документов, которые нужно прикрепить к задаче:
      - Новые документы будут прикреплены
      - Существующие в задаче документы останутся без изменений
      - Остальные документы, которых нет в запросе, будут откреплены
  - В ответе отображаются данные по каждому из указанных в запросе документах: идентификатор документа и название документа.
GET /api/v2/tasks/{id} — метод позволяет получить задачу по идентификатору:
- Просмотр задачи через API не попадает в историю задачи
- Если в задаче есть хотя бы один документ, в ответе отображаются данные по каждому документу:
  - Идентификатор документа
  - Название документа
GET /api/v2/tasks — метод позволяет получить список задач:
- Возможна фильтрации по: делу, дате выполнения, ответственному
- Фильтрация по ответственному позволяет посмотреть задачи, назначенные на определенного пользователя или группу пользователей:
  - Фильтрация выполняется по GUID (статистически уникальному 128-битный идентификатору)
  - В результат фильтрации попадают только те задачи, у которых хотя бы один ответственный пользователь совпал по GUID
- При фильтрации по пользователю в результат не попадут задачи, назначенные на группу, в которую входит указанный пользователь, т.к. вхождение пользователя в группу не проверяется
- Если в задаче есть хотя бы один документ, в ответе отображаются данные по каждому документу:
  - Идентификатор документа
  - Название документа
DELETE /api/v2/tasks/{id} — метод позволяет удалить задачу по идентификатору.

API V3:

POST /api/v3/tasks — метод позволяет создать задачу с заполненными дополнительными атрибутами — работа с созданными полями выполняется через связку Тег — Значение (как и в методах работы с объектами).
PUT /api/v3/tasks/{id} — метод позволяет обновить задачу с дополнительными атрибутами — работа с созданными полями выполняется через связку Тег — Значение (как и в методах работы с объектами).
GET /api/v3/tasks/{id} — метод позволяет получить задачу с дополнительными атрибутами по идентификатору — работа с созданными полями выполняется через связку Тег — Значение (как и в методах работы с объектами).

Типы задач — TaskTypes

Доступные версии: V1, V2:

GET /api/v2/taskTypes/{id} — метод позволяет получить подробную информацию по указанному типу задачи по идентификатору.
GET /api/v2/taskTypes — метод позволяет получить список всех типов задач.

Статусы задач — TaskStatuses

Доступные версии: V1, V2:

GET /api/v2/taskStatuses/{id} — метод позволяет получить подробную информацию по указанному статусу задачи по идентификатору.
GET /api/v2/taskStatuses — метод позволяет получить список всех статусов задач.

Приоритеты задач — TaskPriorities

Доступные версии: V1, V2:

GET /api/v2/taskPriorities/{id} — метод позволяет получить подробную информацию по указанному приоритету задачи по идентификатору.
GET /api/v2/taskPriorities — метод позволяет получить список всех приоритетов задач.

Документы — Documents

В методах для работы с документами присутствует секция Signatures для получения информации об электронной подписи (ЭП). Секция Signatures содержит массив объектов подписей (вне зависимости от их статуса).

Доступная версия: V3:

PUT /api/v3/documents — метод позволяет создать документ по идентификатору с возможностью загрузки файла:
- Совмещена работа методов Upload и BulkCreate — при передаче на вход файла (также как сейчас происходит для Upload) файл сразу отображается как документ в системе
- Место размещения выбирается в зависимости от передаваемого параметра (если возможно):
  - Если пусто — в корень раздела Документы
  - Если есть Id папки — в конкретную папку
- На выходе будут получены атрибуты вновь созданного документа с docID
- Можно загружать документы в дела и папки, к которым есть доступ у пользователя с правами на Редактирование и выше
POST /api/v3/documents/CreateFromTemplate — метод позволяет создать документ по шаблону в указанную или корневую папку объекта:
- Передается Id шаблона
- Готовый документ добавляется в папку дела (Id папки или подпапки) — если не передан Id папки, то в корневую папку дела
- Если в шаблоне есть ссылки на отсутствующие теги в деле, то они игнорируются и документ создается (поведение аналогично методу FillTemplate из внутреннего API)
- Параметры на вход:
  - Id шаблона документа
  - Id дела, куда нужно положить документ
  - Id папки или подпапки (если не задано, то в корень дела)
- Можно создавать документы по шаблону в делах, к которым есть доступ у пользователя с правами на Редактирование и выше.
PUT /api/v3/documents/Update — метод позволяет обновить документ при наличии прав на Редактирование и выше — редактируемые системные атрибуты:
- Название (Name или Id) (обязательное):
  - Если передали name и Id, name игнорируется
  - Если передали неверный Id, отобразится ошибка
  - Если передали только name, то используется name
- Тип (опциональное)
- Дата (обязательное)
- Папка (опциональное)
- Доп. атрибуты по тегам (без возможности изменения самого файла документа)
GET /api/v3/documents/{id} — метод позволяет получить атрибуты документа по идентификатору:
- Возвращает основные атрибуты документа (тип, дата и т.д.) и доп. атрибуты документа по тегам
- Можно получить документы, к которым есть доступ у пользователя на Просмотр и выше
POST /api/v3/documents — метод позволяет получить список документов с фильтрацией по атрибутам:
- Фильтрация доступна по следующим атрибутам:
  - Id родительской папки — если ни один параметр не указан, то отображается список от самой верхней директории раздела Документы
  - Тип сущности (папка или файл) — по умолчанию отображаются обоих типов
  - Типа документа (значение из справочника Тип документа)
  - Id автора документа
  - Дата создания документа
  - Произвольная поисковая строка
- Папки исключаются из выборки при фильтрации по типу документа и/или дате создания
- Пользователь получает доступ к делам, к которым у него есть права на Просмотр или выше
GET /api/v3/documents/{id}/sign/{userId} — метод позволяет скачать отдельный файла подписи у подписанного документа:
- На вход передается Id файла, в который вложена подпись ЭП и Id пользователя, на выходе возвращается файл с подписью ЭП и именем
- Функционал на скачивание архива документа с ЭП сохраняется
GET /api/v3/documents/Download — метод позволяет скачать файл документа с сервера по идентификатору:
- Аналог Download но вместо fileID передается docID
- Можно скачивать документы в делах, к которым у пользователя есть доступ на Чтение и выше
GET /api/v3/documents/DownloadAsPdf — метод позволяет скачать файл документа в формате PDF для печати (с наложенной подписью), файл можно сохранить на инстанс методом Upload или отправить по почте методом в скриптах.
DELETE /api/v3/documents — метод позволяет удалить документ по идентификатору (при наличии прав на Изменение).

Группы методов для работы с участниками

Методы для работы с участниками распределены по следующим группам:

Участники — Participants
Организационно-правовая форма (у участников) — LegalForms

Участники — Participants

Доступные версии: V1, V2, V3, V4.

В методах по работе с участниками доступны:

Параметр CheckForDuplicates, который позволяет проверять данные участника по правилам определения дубликатов при создании или редактировании участника:
- Параметр CheckForDuplicates не учитывает наличие флага Запрещать создавать дубликаты
- Значения параметра:
  - True — при выборе значения участник будет проверяться на дубликаты
  - False — проверка участника на дубликаты выполняться не будет
- Параметр доступен в методах публичного API, которые позволяют:
  - Создать участника
  - Обновить участника
  - Редактировать участника
Новые системные поля карточки участника Телефон (PhoneMain, string, необязательный параметр) и Электронная почта (EmailMain, string, необязательный параметр) включены:
- В ответ и запрос поддерживаемых версий методов:
  - Получение участников (GET /api/v2/participants)
  - Обновление участника
  - Создание участника
- В ответ поддерживаемых версий методов:
  - Получение участника по идентификатору
  - Обновление участника
- В V4 (на базе V3) для обработки новых системных полей в запросе (поля включаются в ответ):
  - Создание участника
  - Обновление участника
  - Редактирование участника

API V2 (V1):

POST /api/v2/participants — метод позволяет создать участника с дополнительными атрибутами:
- Доступно создать компанию (юридическое лицо) и физическое лицо
- Создается участник, и сразу можно указать доп. атрибуты по нему
PATCH /api/v2/participants/{id} — метод позволяет изменить участника с дополнительными атрибутами — доступно изменить поля участника:
- Включая его обычные атрибуты
- Через PATCH (по аналогии с делом)
GET /api/v2/participants/{id} — метод позволяет получить подробной информации об указанном участнике по идентификатору (и по доп. атрибутам)
GET /api/v2/participants — метод позволяет получить список участников:
- Данные по контакту и дела, в которых есть контакты
- Дополнительные атрибуты:
  - Name
  - Type (Individual или Company)
  - Email
  - Phone
  - LastName
  - FirstName
  - INN
  - KPP
- Если не выбраны условия, то выдается весь список с паджинацией

API V3 — работа с созданными полями выполняется через связку Тег — Значение:

POST /api/v3/participants — метод позволяет создать участника с дополнительными атрибутами.
PUT /api/v3/participants/{id} — метод позволяет изменить участника с дополнительными атрибутами.
GET /api/v3/participants/{id} — метод позволяет получить подробную информацию об указанном участнике с заполненными доп. атрибутами по идентификатору.
DELETE /api/v3/participants/{id} — метод позволяет удалить участника по идентификатору:
- Удаление доступно при наличии доступа на изменение секции Участники
- При удалении проверяются права на изменение дел, в которых этот участник фигурирует — если нет прав на хотя бы одно из дел, то участник не будет удален
PUT /api/v3/participants/ExcludeParticipantFromProject — метод позволяет исключить участника из дела/объекта:
- Если Id role in object не указан, участник исключается со всеми ролями
- Список всех зарегистрированных ролей в системе можно получить с помощью метода GET /api/v2/rolesInCase
- Исключение доступно при наличии прав на редактирование дела

API V4:

POST /api/v4/participants{id} — метод позволяет создать участника с дополнительными атрибутами.
PUT /api/v4/participants/{id} — метод позволяет изменить участника с дополнительными атрибутами.
GET /api/v4/participants/{id} — метод позволяет получить подробную информацию об указанном участнике с заполненными доп. атрибутами по идентификатору.

Организационно-правовая форма — LegalForms

Доступные версии: V1, V2:

GET /api/v2/legalForms/{id} — метод позволяет получить подробную информацию об организационно-правовой форме по идентификатору.
GET /api/v2/legalForms — метод позволяет получить все организационно-правовые формы.

Пользователи — Users

При получении карточки пользователя система не отдает информацию из блока Рабочая информация, если отсутствуют права на просмотр блока.

В методах для работы с пользователями:

Доступно получить все атрибуты пользователя, в том числе дополнительные.
Все атрибуты доступны по тегу.

Вы можете получить сведения о дате и времени последнего входа пользователя или клиента в систему Case.one через следующие методы публичного API:

GET /api/v1/users/{id}
GET /api/v1/users
GET /api/v2/users/{id}
GET /api/v2/users

В качестве источника данных параметра LastLoginDate методов берутся дата и время из статуса Последний вход колонки Статус в разделе Администрирование — Пользователи:

Формат данных: дата в ISO, время в UTC+0.
Поле может быть пустым, если пользователь никогда не входил в Case.one.

В результате будут получены сведения о последнем входе пользователя или клиента, если вход в Case.one был выполнен:

На странице входа Case.one.
С помощью Windows-аутентификации.
Через SSO.

Доступные версии: V1, V2:

GET /api/v2/users/{id} — метод позволяет получить указанного пользователя по идентификатору — в исходящих параметрах доступно указать:
- Группы пользователя
- Роли пользователя
- Телефон
- Часовой пояс
- Должность
- Подразделение
- Организация
- Сайт
GET /api/v2/users — метод позволяет получить список пользователей:
- Доступна фильтрация:
  - Все, пользователи, клиенты
  - Все, только активные
- Системные пользователи не отображаются
- По пользователям передаются данные: ФИО (с учетом настроек локализации), почта, тип (клиент, пользователь), статус (активный, заблокированный)
- Пользователи отсортированы по ФИО (с учетом настроек локализации), паджинация по 100 значений
POST /api/v2/users/{id}/notify — метод позволяет отправить уведомление стандартным всплывающим сообщением одному пользователю:
- Полный аналог приватного запроса /api/NotifySingleUser
- Метод принимает как просто текст, так и текст с html-разметкой
- Сообщение у пользователя выводится в соответствии с разметкой
- Стилизованная под Case.one разметка (остальные теги могут использоваться, но будут выводиться браузером)
  - Перенос строки: <br/>, \n, \r
  - Ссылки: <a href></a>
  - Стилизация текста: <b>, <i>, <u>
  - Списки: <ol>, <ul>
- Можно добавить необязательный массив кнопок в формате: текст + ссылка:
  - По каждой ссылке можно указать параметр – открывается в том же окне или новом
  - Если параметр не указан, считается, что открывается в соответствии с настройками аккаунта
- Для каждой кнопки предусмотрен параметр закрытия нотификации:
  - Параметр не обязательный
  - Если параметр не передан, нажатие на кнопку не закроет уведомление
- Текущий механизм размещения кнопок не меняется (не гарантировано корректное отображения, если название слишком большое или много кнопок)
- Кнопка Закрыть всегда отображается

Права роли — RolePermissions

Основная версия: V4 (методы также отображаются в V1, V2, V3):

Методы создания роли:
- POST /api/UserManagment/RolePermissions — метод позволяет установить права на системные разделы для роли
- POST /api/UserManagment/RolePermissions/CreateRolePermission — метод позволяет создать роль и установить права на системные разделы
- POST /api/RolePermissions/CreateRolePermission — метод позволяет создать роль с назначенными правами
Методы обновления прав — позволяют обновить права на системные разделы у роли:
- PUT /api/UserManagment/RolePermissions/UpdateRolePermission
- PUT /api/RolePermissions/UpdateRolePermission
Методы получения списка прав для роли — позволяют получить список прав на разделы для роли по идентификатору роли:
- GET /api/UserManagment/RolePermissions/GetRolePermissions
- GET /api/RolePermissions/GetRolePermissions
Метод удаления прав роли:
- DELETE /api/RolePermissions/DeleteRolePermission/{id} — метод позволяет удалить права на системные разделы для роли по идентификатору

Методы для управления правами роли являются алиасами.

Справочники — Dictionaries

Доступные версии: V1, V2:

GET /api/v2/dictionaries/{id} — метод позволяет получить справочник по идентификатору.
GET /api/v2/dictionaries — метод позволяет получить список справочников, учитывая системные значения (например, приоритет задачи) — возвращается сразу весь список справочников.
GET /api/v2/dictionaries/{id}/values/{valueId} — метод позволяет получить значения справочника по идентификатору.
GET /api/v2/dictionaries/{id}/values — метод позволяет получить все значения указанного справочника.

Группы методов для работы с файлами

В API V1 доступна группа методов Файлы — Files с методом POST /api/v1/files/{id}/extract, который позволяет извлечь файлы из архива и временно их сохранить в файловом хранилище:

По Id файла, в который вложен файл-архив, выполняется запрос разархивации.
На выходе возвращается массив, содержащий:
- Ссылку на скачивание файла архива
- Имя файла в архиве
- Путь внутри архива (включая имя файла)
Параметр encoding определяет кодировку, которая используется для отображения имен файлов и папок в архиве — если параметр не задан, по умолчанию используется кодировка соответствующая языку аккаунта, указанному в разделе Администрирование — Аккаунт (для русского языка — cp866).

Например, если на инстансе установлен английский язык, а целевой архив содержит в именах кириллицу, необходимо явно передавать кодировку — encoding=cp866. Список поддерживаемых кодировок можно посмотреть по этой ссылке.

Скачать файлы по ссылкам можно в течение двух часов (по умолчанию).
В файле настроек конфигурации appsettings.json в секции Custom можно задать дополнительные настройки, влияющие на работу этого API (время доступности скачивания файла и директория для хранения файла):
- Если в архиве содержится хотя бы один файл с запрещенным расширением, отображается ошибка, файлы не извлекаются
- Поддерживаемое расширение архивов: *.zip (однотомные архивы без пароля)
- Предусмотрены следующие ограничения по умолчанию: размер архива — 100 Мб, размер файла — 100 Мб, Количество файлов в архиве — 100

Настройки секции Custom:

"Custom": {

...

"ExtractedFileLifetime": "02:00:00", // время жизни извлеченных файлов, по умолчанию 2 часа

"ExtractedFilesTempDirectory": "/temp_path" // директория для временного хранения извлеченных файлов, по умолчанию не задано, в этом случае используется временная папка пользователя, от имени которого работает приложение

}

"Custom": {

...

"MaxArchiveFileSize": 104857600, // максимальный размер архива в байтах, по умолчанию 100 Мб

"MaxExtractingFileSize": 104857600, // максимальный размер файла в архиве (без сжатия), по умолчанию 100 Мб

"MaxExtractingFileCount": 100 // максимальное кол-во файлов в архиве, по умолчанию 100

}

В API V2 доступны группы методов:

Загрузка — Upload → POST /api/v2/upload — метод позволяет загрузить файл:
- Принимает те же параметры что и fetch + тип содержимого (текст, base64)
- Метод скачивает файл по указанному адресу и декодирует его в base64 при необходимости (если в файле двоичные данные)
- Метод решает кейс по скачиванию бинарных файлов из внешних систем, если нужна их обработка в скриптах, или при необходимости переложить файл из одной внешней системы в другую
- Накладывает ограничение на размер и расширение файла (ограничения настраиваются в файле конфигурации)
Скачивание — Download → GET /api/v2/download/{id} — метод позволяет скачать файл:
- Принимает те же параметры что и fetch + тип содержимого (текст, base64)
- Метод загружает файл по указанному адресу, конвертируя его из base64 при необходимости
- Метод решает кейсы по загрузке измененных текстовых файлов и загрузке файлов из внешних base64 источников
- Накладывает ограничение на размер и расширение файла (ограничения настраиваются в файле конфигурации)
- Доступно скачать документ вместе с подписью

Звонки — Calls

Доступные версии: V1, V2:

POST /api/v2/calls — метод позволяет создать звонок.
POST /api/v2/calls/sendNotification — метод позволяет отправить уведомление по звонку.
PUT /api/v2/calls/{id}/attachRecordin — метод позволяет прикрепить запись к звонку.
POST /api/v2/calls/uploadRecording — метод позволяет загрузить запись звонка.

Скрипты — Scripts

Доступные версии: V1, V2.

POST /api/v2/scripts/run — метод позволяет запустить скрипт:

Чтобы избежать проблем с производительностью, рекомендуем запускать сценарии асинхронно (значение true в IsAsync).
При запуске слишком большого количества скриптов отображается нотификация 429: Слишком много скриптов запущено.
Максимальное количество параллельно работающих скриптов задается настройкой в web.config:

<add key="ScriptsWorkersCount" value="10" />

Служебные запросы

В API V2 (V1) и V3 доступна группа методов для проверки состояния системы Health:

GET /api/v2/health — метод позволяет проверить состояние работоспособности сервиса — в результате будет получено текущее состояние работоспособности системы и БД:
- Status — состояние работоспособности:
  - Unknown — неизвестно
  - OK — ок
  - Error — ошибка
- DbStatus — состояние работоспособности БД:
  - Unknown — неизвестно
  - OK — ок
  - Error — ошибка
GET api/v3/health — метод позволяет проверить количество ошибок и предупреждений в global.log, а также собрать статистику по времени обработки запросов и учитывать ее при анализе состояния Системы:
- Метод недоступен для просмотра в Swagger из-за технических ограничений, поскольку отличается способ реализации метода
- В файле приложения appsettings.json в секции HealthChecks доступно задать настройки API проверки состояния Системы:

 {
  "HealthChecks": {
    ...                                     //Прочие настройки HealthCheck
    "RequestProcessingTimeSettings": {      //секция настроек HealthCheck по статистике ошибок и предупреждений
      "Tracking": false,                    //отслеживание времени выполнения запроса
      "Range": "01:00:00",                  //время хранения статистики проверки времени обработки запросов. По умолчанию "01:00:00" (1 час)
      "Step": "00:01:00",                   //временной отрезок, за который будет подсчитываться статистика. По умолчанию "00:01:00" (минута)
      "MaxExecutionTime": "00:01:00",       //максимальное время выполнения запроса. По умолчанию "00:01:00" (минута)
      "CountForDegraded": 100,              //кол-во запросов, необходимое для получения статуса Degraded. По умолчанию 100
    }
  }

Ответ метода GET api/v3/health имеет следующий формат:

{
  "status": "Healthy",                      //общий статус всех проверок
  "totalDuration": "00:00:03.9302856",      //общая продолжительность всех проверок
  "entries": {                              //список всех проверок
    ...                                     //Прочие HealthCheck'и
    "requestProcessingTime": {              //HealthCheck'а проверки времени обработки запросов
      "data": {
        "longRequestCount": 0,              //кол-во запросов, выполнение которых превысило время, заданное в параметре MaxExecutionTime
      },
      "duration": "00:00:03.9293789",       //продолжительность выполнения HealthCheck'а статистики
      "status": "Healthy"//статус HealthCheck'а, в зависимости от настроек в appsettings
    },
  }
}

В API V3 доступна группа методов для получение логов — Logs с помощью метода GET /api/v3/logs/Get, который позволяет получить файл логов выполнения сценария автоматизации по параметрам:

Логи остаются разделенными по дням.
В выгружаемых логах содержатся логи, формируемые методом console.log().
Метод позволяет также скачать:
- WorkflowTrace.log — лог работы сценариев, куда записывается информация обо всех сработавших сценариях и их выполненных шагах (необходимый уровень Trace)
- CaseDotStar.ServicePackages.Common.Scripts.ScriptInterpreterLogger.log — лог интерпретатора JS-скриптов, в который записываются все ошибки, возникающие при выполнении JS-скриптов, а также записи в консоль выполненные командой console.log (необходимый уровень Info)

Справочный центр Case.one

Группы и методы публичного API

Зона покрытия публичного API

Аутентификация пользователя — Auth

Основные настройки — GeneralSettings

Группы методов для работы с объектами

Классы объектов — ObjectClasses

Типы объектов — ObjectTypes

Папки дел/объектов — Folders

Проекты — Projects

Объекты — Objects

Связанные объекты — RelatedObjects

Роли в деле — RolesInCase

Группы методов для работы с событиями

События — Events

Типы событий — EventTypes

Группы методов для работы с задачами

Задачи — Tasks

Типы задач — TaskTypes

Статусы задач — TaskStatuses

Приоритеты задач — TaskPriorities

Документы — Documents

Группы методов для работы с участниками

Участники — Participants

Организационно-правовая форма — LegalForms

Пользователи — Users

Права роли — RolePermissions

Справочники — Dictionaries

Группы методов для работы с файлами

Звонки — Calls

Скрипты — Scripts

Служебные запросы