Массовые операции

Что получится в конце

Интеграция сможет запускать массовую синхронизацию справочников, массовое подписание документов, импорт данных из файла и выгрузку больших реестров без поштучных запросов к API.

Что нужно заранее

Что нужно	Где получить
`tenantHost`	Адрес тенанта HRlink
`clientId`	Текущий пользователь
Токен	Аутентификация
Данные для синхронизации или импорта	На стороне интеграции
Документы для массового подписания	Реестр документов

Какие методы используются

Сценарий	Метод
Запустить bulk sync	Создать задачу синхронизации
Проверить bulk sync	Статус задачи синхронизации или Статусы задач синхронизации
Создать пакет массового подписания	Создать процесс массового подписания
Подписать пакет	Массово подписать ПЭП, Массово подписать УНЭП или Массово подписать УКЭП
Создать выгрузку	Создать выгрузку XLS
Получить результат выгрузки	Статус выгрузки и Скачать результат выгрузки
Создать импорт	Создать импорт из файла
Проверить импорт	Статус импорта

Массовая синхронизация (Bulk Sync)

Подробное описание — в разделе Синхронизация сотрудников → Запуск задачи bulk sync.

Типы задач

Тип	Описание
`LEGAL_ENTITIES`	Юрлица
`CLIENT_DEPARTMENTS`	Отделы
`EMPLOYEE_POSITIONS`	Должности
`CLIENT_USERS_V6`	Пользователи и сотрудники
`EMPLOYEE_FUNCTIONAL_MANAGERS`	Управленческие руководители
`CALENDARS`	Календари
`EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS`	Элементы пользовательских структур
`CUSTOM_STRUCTURES`	Справочник пользовательских структур
`EMPLOYEE_VACATIONS_V2`	Отпуска сотрудников
`EMPLOYEE_VACATIONS_PLANNING`	Планирование отпусков
`CLIENT_USER_VACATIONS`	Плановые отпуска пользователей

Ограничения

Лимит элементов задаётся per-type (нет единого):
- EMPLOYEE_FUNCTIONAL_MANAGERS — 1000
- EMPLOYEE_VACATIONS*, EMPLOYEE_VACATIONS_PLANNING, EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS, CLIENT_USER_VACATIONS — 500
- LEGAL_ENTITIES, CLIENT_DEPARTMENTS, EMPLOYEE_POSITIONS, CLIENT_USERS_*, CALENDARS, CUSTOM_STRUCTURES — сервер не проверяет, рекомендуем порции по 500
externalId обязателен у каждого элемента и уникален в пределах задачи
Параллельный запуск задач одного type сервер не блокирует, но безопаснее запускать последовательно — особенно для CLIENT_DEPARTMENTS
Статус задачи проверяйте методом Статус задачи синхронизации

Полный список ограничений — Ограничения.

Массовое подписание документов

Массовое подписание работает через процесс и пакеты. Сначала HRlink создаёт процесс по фильтру реестра документов сотрудника, затем интеграция выбирает пакет и подписывает его ПЭП, УНЭП или УКЭП.

Пакет массового подписания содержит не больше 50 документов. Если документов больше, запускайте процессы последовательно.

Шаг 1. Создать процесс

Вызовите Создать процесс массового подписания. В теле запроса передайте фильтр реестра документов сотрудника: например documentIds, documentExternalIds, статусы подписантов, юрлица или диапазоны дат.

curl
PowerShell
HTTP

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "documentIds": [
      "0f4b4b6e-68c0-4aa9-a195-2f8f8786b111",
      "c14f0726-f8ad-45e6-a3d7-25efcfd36222"
    ],
    "employeeSignerStatuses": ["WAITING_SIGNING"]
  }'

Invoke-RestMethod `
  -Method Post `
  -Uri "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings" `
  -ContentType "application/json" `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -Body '{
    "documentIds": [
      "0f4b4b6e-68c0-4aa9-a195-2f8f8786b111",
      "c14f0726-f8ad-45e6-a3d7-25efcfd36222"
    ],
    "employeeSignerStatuses": ["WAITING_SIGNING"]
  }'

POST /api/v1/clients/{clientId}/documents/bulkSignings HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{
    "documentIds": [
      "0f4b4b6e-68c0-4aa9-a195-2f8f8786b111",
      "c14f0726-f8ad-45e6-a3d7-25efcfd36222"
  ],
  "employeeSignerStatuses": ["WAITING_SIGNING"]
}

Ответ содержит process.id и массив process.packages. Каждый пакет содержит:

Поле	Что означает
`id`	ID пакета для методов подписания
`type`	Тип пакета: `NORMATIVE_ACTS`, `HEAD_MANAGER`, `EMPLOYEE_OR_PARTICIPANT`
`suitableSignatures`	Доступные типы подписи: `SES`, `CLOUD_NQES`, `QES`
`entities[].id`	ID связки подписанта с пакетом для включения или исключения документа
`entities[].included`	Попадает ли документ в пакет

Шаг 2. Изменить состав пакета

Если нужно исключить документ из пакета или вернуть его обратно, вызовите Включить/исключить документ из пакета. Передайте processId из процесса и packageDocumentSignerId из process.packages[].entities[].id.

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/{processId}/inclusion/{packageDocumentSignerId}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{"include": false}'

ЛНА-пакет (NORMATIVE_ACTS) нельзя изменять этим методом.

Шаг 3. Подписать пакет

Выберите метод по типу подписи из suitableSignatures.

Тип подписи	Метод	Что передать
`SES`	Массово подписать ПЭП	Только `packageId` в пути
`CLOUD_NQES`	Запросить массовое подписание УНЭП, затем Подтвердить массовое подписание УНЭП	`packageId`, затем `documentBulkSigningRequestId` и код подтверждения
`QES`	Массово подписать УКЭП	`packageId` и массив `signatures`

ПЭП

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/packages/{packageId}/sign/ses" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

УНЭП

Сначала создайте запрос подписания:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/packages/{packageId}/sign/nqes" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Затем подтвердите запрос кодом из канала подтверждения:

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/packages/{packageId}/sign/nqes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "documentBulkSigningRequestId": "bb570817-aabe-4c5c-b2cf-273776f192a8",
    "code": "123456"
  }'

УКЭП

Для УКЭП передайте подписи в Base64 и документы, которые относятся к каждой подписи. Если руководитель подписывает документ по МЧД, укажите attorneyId или attorneyExternalId.

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/packages/{packageId}/sign/qes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "signatures": [
      {
        "value": "{signatureBase64}",
        "documents": [
          {
            "id": "0f4b4b6e-68c0-4aa9-a195-2f8f8786b111",
            "attorneyId": "9f8b44e5-1b02-42f1-b3fb-b0c17f3f1111"
          }
        ]
      }
    ]
  }'

Шаг 4. Проверить результат

После изменения состава или подписания перечитайте процесс методом Получить процесс массового подписания.

curl -X GET "https://{tenantHost}/api/v1/clients/{clientId}/documents/bulkSignings/{processId}" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Для УНЭП-запроса можно отдельно получить его состояние методом Получить запрос массового подписания.

Типы пакетов

Тип	Что подписывает
`HEAD_MANAGER`	Документы, где текущий пользователь подписывает как руководитель
`EMPLOYEE_OR_PARTICIPANT`	Документы, где текущий пользователь подписывает как сотрудник или участник маршрута
`NORMATIVE_ACTS`	ЛНА; если в процессе есть ЛНА-пакет, сначала подпишите его

Массовый импорт и экспорт

Экспорт данных

Экспорт работает асинхронно. Интеграция создаёт задачу методом Создать выгрузку XLS, проверяет статус и скачивает результат после перехода задачи в FINISHED.

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/exportTasks" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "type": "EMPLOYEE_REGISTRY",
    "params": {
      "legalEntityIds": ["{legalEntityId}"]
    }
  }'

Ответ содержит exportTask.id:

{
  "result": true,
  "exportTask": {
    "id": "91a2a5fb-2f74-4cf1-9f3c-e3327f4bc3e0"
  }
}

Проверяйте статус методом Статус выгрузки:

curl -X GET "https://{tenantHost}/api/v1/clients/{clientId}/exportTasks/{taskId}" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Если exportTask.state равен FINISHED, скачайте результат методом Скачать результат выгрузки. Метод вернёт 303, а заголовок Location будет содержать одноразовую ссылку на файл.

curl -i -X GET "https://{tenantHost}/api/v1/clients/{clientId}/exportTasks/{taskId}/result" \
  -H "User-Api-Token: {token}"

Если выгрузка разбита на части, в exportTask.resultParts[] будут ID частей. Скачивайте каждую часть методом Скачать часть выгрузки.

curl -i -X GET "https://{tenantHost}/api/v1/clients/{clientId}/exportTasks/{taskId}/results/{resultPartId}" \
  -H "User-Api-Token: {token}"

Доступные типы выгрузки:

Тип	Что выгружается
`EMPLOYEE_REGISTRY`	Реестр сотрудников для кадровика
`NORMATIVE_ACT_DOCUMENTS`	Лист ознакомления с ЛНА
`EMPLOYEES_WITH_FUNCTIONAL_MANAGER`	Управленческая структура
`APPLICATION_REGISTRY`	Реестр заявлений для кадровика
`DOCUMENTS_DOCFLOW_ARCHIVES`	Архивы КЭДО по документам
`APPLICATIONS_DOCFLOW_ARCHIVES`	Архивы КЭДО по заявлениям

Импорт данных

Импорт тоже работает асинхронно. Сначала загрузите файл методом Загрузить файл, затем передайте fileId в метод Создать импорт из файла.

curl -X POST "https://{tenantHost}/api/v1/files" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}" \
  -F "file=@/path/to/import.xlsx"

Создайте задачу импорта:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/importTasks" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "fileId": "{fileId}",
    "type": "FUNCTIONAL_MANAGER"
  }'

Ответ содержит task.id и начальный статус:

{
  "result": true,
  "task": {
    "id": "e84ac01e-c631-48a4-81d7-5fce23c12b2f",
    "state": "QUEUED"
  }
}

Проверяйте статус методом Статус импорта:

curl -X GET "https://{tenantHost}/api/v1/clients/{clientId}/importTasks/{taskId}" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Финальные статусы импорта: SUCCEEDED и FAILED. При ошибке смотрите task.failReason и task.result.

Оптимизация для больших объёмов

Когда выгрузка замедляется

Если в реестре больше 45 000 документов или сотрудников, запрос всего реестра одним вызовом может не уложиться в таймаут.

Пример: разбиение по порциям

Общий объём: 5000 сотрудников
Размер порции bulk sync: 500

Итого: 10 последовательных вызовов метода «Создать задачу синхронизации»
Между вызовами: проверить статус предыдущей задачи

Метод для запуска каждой порции — Создать задачу синхронизации.

Что получится в конце​

Что нужно заранее​

Какие методы используются​

Массовая синхронизация (Bulk Sync)​

Типы задач​

Ограничения​

Массовое подписание документов​

Шаг 1. Создать процесс​

Шаг 2. Изменить состав пакета​

Шаг 3. Подписать пакет​

ПЭП​

УНЭП​

УКЭП​

Шаг 4. Проверить результат​

Типы пакетов​

Массовый импорт и экспорт​

Экспорт данных​

Импорт данных​

Оптимизация для больших объёмов​

Когда выгрузка замедляется​

Рекомендации​

Пример: разбиение по порциям​