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

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

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

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

1. Если у пользователя права на Просмотр или нет прав на блок в объекте/деле, то при создании/редактировании такого объекта/дела через публичный API, заполняя/редактируя блок, в результате будет получен ответ 201, а отправленные значения игнорируются.
2. Заполнение кастомных полей:
   • В методах API по работе с объектом/делом доступно заполнить кастомные поля дела/объекта, передав JSON-объект в формате — тег поля : значение
   • Заполнение системных полей таким образом не предусмотрено
   • Система позволяет работать с объектами любого класса
   • Если у поля нет тега, то в качестве тега используется Id поля (данное значение не отображается на UI)
   • В методах публичного API v1 и v2 по работе с объектами выполняется проверка формата кастомных полей, что позволяет корректно заполнять поля карточки дела и избежать ошибок при формировании отчетов по этим полям
3. Таблицы объектов — в следующих методах 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}
4. Проверка на дубли — при создании или редактировании объектов через публичный API в запросе присутствует параметр CheckForDuplicates для проведения валидации данных объекта по правилам определения дубликатов:
   • Параметр CheckForDuplicates доступен в следующих методах поддерживаемых версий:
     • Создание объекта
     • Обновление объекта (PUT)
     • Редактирование объекта: (PATCH)
     • Архивация объекта;
     • Восстановление объекта из архива.
   • При установке значения False в параметре CheckForDuplicates:
     • Валидация данных объекта не выполняется
     • Объект создается / редактируется через API без валидации атрибутов предаваемого объекта по правилам определения дубликатов
   • Если установлено значения True в параметре CheckForDuplicates при передаче запроса вышеуказанными методами, валидация атрибутов предаваемого объекта по правилам определения дубликатов работает по следующему по принципу:
     • Проверяемый объект валидируются по правилу определения дубликата соответствующего типа объектов:
       • Если предаваемый объект не определен как дубликат — объект создается, изменения в объекте сохраняются
       • Если предаваемый объект определен как дубликат — объект не создается, изменения в объекте не сохраняются и будет отправлен ответ об ошибке с полями (см. в таблице ниже)
     • Валидация проверяемого объекта по правилам определения дубликатов не учитывает флаг Запрещать создавать дубликаты — вне зависимости от установки флага при передаче запроса по API, если передаваемый объект определен как дубликат, он не будет создан, все изменения не будут сохранены (процесс создания и редактирования объектов соответствует стандартному механизму):
       • Если правило определения дубликатов не настроено для типа объекта
       • Если правило определения дубликатов не настроено для типа объекта, но в атрибуте запроса CheckForDuplicates передано значение True, параметр игнорируется
       • Если настроенное правило стало невалидным из-за удаления поля, участвующего в правиле, валидация по такому правилу не запускается
5. В публичном API получения, создания и редактирования объекта доступно использование полей с типом Объект-Пользователь.

Классы объектов — 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 — метод позволяет получить список всех ролей в деле/объекте.