Перейти к основному содержимому

Создать задачу синхронизации

POST 
/api/v1/clients/:clientId/bulkDataSyncTasks

Описание метода​

Ставит асинхронную задачу массовой синхронизации данных. Метод сразу возвращает bulkDataSyncTask.id — идентификатор задачи. Прогресс и итог обработки запрашиваются методом bulkDataSyncTaskGetBulkDataSyncTaskStatus (GET /api/v1/clients/{clientId}/bulkDataSyncTasks/{taskId}) — он отдаёт статус задачи и результаты по каждой модели из массива data (создана, обновлена, пропущена, ошибка).

Что делает задача — определяется полем type: юрлица, отделы, должности, пользователи клиента вместе с их сотрудниками, календари и т. д. Структура data и parameters зависит от type — подсхемы CreateBulkDataSyncTaskDTO_<TYPE> описывают каждый случай отдельно. Поле externalId обязательно у каждого элемента data для всех типов; внутри одной задачи externalId должны быть уникальны.

Bulk sync — основной способ загрузки и поддержки оргструктуры. Пошаговый сценарий: гайд Синхронизация сотрудников.

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

Базовое право — BULK_DATA_SYNC_TASKS_CREATE на уровне ClientUser или Employee. Для отдельных типов задач требуются дополнительные права:

typeДоп. право (ClientUserPermission)
CALENDARSCALENDAR_CREATE + CALENDAR_YEARS_EDIT
CUSTOM_STRUCTURESCUSTOM_STRUCTURES_CREATE + CUSTOM_STRUCTURES_UPDATE

Лимиты на размер data​

Лимит элементов задаётся per-type, единого ограничения нет:

typeЛимит
EMPLOYEE_FUNCTIONAL_MANAGERS1000
EMPLOYEE_VACATIONS, EMPLOYEE_VACATIONS_V2, EMPLOYEE_VACATIONS_PLANNING, EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS500
CLIENT_USER_VACATIONS500
LEGAL_ENTITIES, CLIENT_DEPARTMENTS, EMPLOYEE_POSITIONS, CLIENT_USERS_*, CALENDARS, CUSTOM_STRUCTURESне проверяется на стороне сервера

Для типов без серверного лимита рекомендуется бить выборку на порции 500 элементов — так нагрузка на API остаётся ровной, а отдельные ошибки не «вытягивают» вместе с собой большой пакет.

Параллельные задачи одного типа​

bulkDataSyncTaskCreateBulkDataSyncTask не блокирует запуск второй задачи того же type, пока предыдущая не завершилась. Однако последствия зависят от типа: для CLIENT_DEPARTMENTS параллельные задачи могут конкурировать за один справочник, для LEGAL_ENTITIES это менее опасно. Безопаснее запускать задачи одного типа последовательно — после SUCCEEDED/FAILED/PARTIALLY_SUCCEEDED предыдущей.

Валидации запроса​

  • Тело запроса задано.
  • Поле type задано.
  • Поле data задано и не пусто.
  • Все элементы data не равны null.
  • Клиент существует, не удалён, и пользователь относится к клиенту.
  • У пользователя есть право BULK_DATA_SYNC_TASKS_CREATE (на уровне ClientUserClientUser Связь пользователя с пространством клиента — пара (userId, clientId). Один пользователь может относиться к нескольким клиентам, но в одном клиенте встречается только один раз. или EmployeeEmployee Связь пользователя пространства клиента с юрлицом — пара (clientUserId, legalEntityId). Один пользователь может иметь несколько записей Employee в разных юрлицах или даже в одном.).
  • parameters корректны для заданного type (см. подсхему CreateBulkDataSyncTaskDTO_<TYPE>).
  • data корректны для заданного type — детальные правила в подсхеме CreateBulkDataSyncTaskDTO_<TYPE>. Общие правила для всех типов: externalId задан у каждого элемента и уникален в пределах задачи.
  • Лимит data (если применим к типу) не превышен.
  • Дополнительные type-specific права (см. таблицу выше) предоставлены.

Request​

Responses​

Успешная операция.