В данном разделе есть:

информация о способах коммуникации между ИС Клиента и HRlink (ответ на запрос).
пояснение что ряд событий происходит асинхронно
раскрыта поддержка двойных идентификаторов
описан подход по работе с пагинированными данными реестров

Документация для интеграции

HRlink предоставляет открытое API для интеграции. Но как именно осуществить интеграцию, как решить бизнес-кейс или как работает конкретный API-метод - для того чтобы разобраться с этими вопросами нужно изучать документацию.

У нас есть несколько различных документов, каждый из которых помогает с отдельными аспектами.

Документация	Краткое описание
WIKI	Вы как раз тут) и эта документация нацелена на то, чтобы сформировать понимание того, как именно закрываются бизнес-кейсы Клиента. Тут рассматриваются подходы к интеграции, обобщённые бизнес-сценарии, есть дополнительное описание объектов (понимание структуры объектов и их поведения) существенно влияют на скорость интеграции. Также в некоторых случаях тут приводятся примеры API-методов, описание которых ещё не добавлено в документацию.
HR-Link_API	Описание самих API-методов: эндпоинты входные параметры возвращаемые ответы примеры данная документация находится в процессе переезда на более технологичный движок (см. следующую строчку). Постепенно мы полностью перенесём описание отсюда и откажемся от ведения данной документации.
HR-Link REST API	Более технологичная версия описания API-методов. В данную документацию заносится описание всех новых API-методов, также постепенно сюда переезжает описание из HR-Link_API В данной документации есть ендпоинты, входные и выходные параметры, примеры ответов и ошибки. В конечном итоге данная документация станет основным документом, описывающим работу API-методов.
Дополнительные материалы	Есть единичные случаи, когда API-метод существует, но его нет ни в старой версии документации, ни в новой В этом случае, если такие методы должны использоваться в вашем кейсе интеграции, то мы для вас подготовим отдельное описание, которое в последствии будет добавлено в основную документацию, так что если вы не нашли нужное вам описание, просто сообщите вашему менеджеру и мы оперативно решим такой вопрос

REST API - "Запрос-Ответ"

Для Интеграции HRlink предоставляет доступ к API в рамках тенанта Клиента.

Для передачи в HRlink и для получения информации из HRlink необходимо использовать REST API.

Система HRlink только отправляет ответы на запросы, поэтому для получения актуальной информации о состоянии объектов (документы, заявления, сотрудники и т.д.) на стороне Клиента необходимо реализовывать периодические опросы HRlink, для получения обновлённой информации.

Важно, чтобы ИС Клиента могла обеспечить обработку информации, поступающей в ответ на запрос.

Способы аутентификации

Тут → Определите способ аутентификации описано в каком случае какой способ аутентификации использовать

В описании API-методов есть указание по способам авторизации (через логин/пароль, через токен)

В разделе [Способы аутентификации и авторизации] более детально раскрыта информация о более сложных механиках аутентификации

Вход пользователя в HRlink через сторонний сервис аутентификации
Использование мастер-токена для интеграции с HRlink
Сквозная аутентификация

Асинхронные процессы

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

Нужно учитывать, что выполнение асинхронных событий может занимать какое-то время, поэтому HRlink в ряде случаев возвращает не ответ на запрос, а некую информацию о процессе.

Конвертация файла в формат PDF/A - все файлы, которые будут участвовать в КЭДО преобразуются (в соответствии с требованиями) в формат PDF/A.
1. Процесс конвертации запускается после успешного создания черновика документа
2. Процесс применяется при подаче Заявления из файла
Выпуск УНЭП
1. При запуске процесса выпуска УНЭП, если все валидации пройдены возвращается {"result":true} чтобы понять состояние выпуска, необходимо обратиться к объекту Сотрудник.
Создание документа с совмещённой отправкой - в ответ на запрос возвращается идентификатор события. Чтобы получить информацию о ожидаемом документе необходимо использовать фильтрационные параметры при запросе реестра документов.
Подписание
1. При запросе подписания УНЭП возвращается идентификатор события подписания, а не сам результат подписания
2. При запросе подписания ПЭП Госуслуги - происходит перенаправление пользователя на сайт Портал Работа в России, где производится подписание.
3. При запросе подписания УНЭП Госключ - происходит отправка документа в Госключ, само подписание происходит в мобильном приложении.
Обновление печатной формы с оттиском - после каждого подписания HRlink обновляет ПФ, добавляя в оттиск данные о новом подписании.

ExternalId

Большая часть объектов имеет двойной идентификатор

ID - идентификатор, формируемый HRlink в формате UUID
ExternalId - для HRlink это идентификатор внешней системы, для Клиента это идентификатор в своей системе

Поддержка двойных идентификаторов позволяет Клиенту обращаться к объектам наиболее удобным образом.

Перечень объектов, поддерживающих использование ExternalId:

Документ
Физлицо
Сотрудник
Юрлицо
Отдел
Должность
Тип документа

Пагинация

Получение реестров (Документы, Заявления, Сотрудники) происходит с учётом пагинации.

При запросе списков (реестр документов, заявлений, сотрудников и т.д.) HRlink используется постраничный вывод.

Параметры в теле запроса

```
{
    "sort": [{ "by": "DOCUMENT_DATE", "direction": "ASC" }],
    "limit": 50,
    "offset": 1324
}
```

пояснение

50 - максимальное значение, по умолчанию = 10

Получая список документов, нужно посмотреть количество документов в списке,

Переопределение сдвига offset = offset + limit

Таким образом каждый раз вычисляется новый сдвиг, например:

Итерация 1: limit = 50, offset = 0 (или не указан)
- Получили первые 50 заявлений
Итерация 2: limit = 50, offset = 50
- Получили заявления с 51 по 100
Итерация 3: limit = 50, offset = 100
- Получили заявления со 101 по 150
Итерация N - полученное количество заявлений меньше 50, следовательно дошли до конца списка заявлений, дальнейший инкремент сдвига не требуется

Ошибочные ответы от API

В API документации раздел [Ошибочные ответы от API] описывается Структура ошибочного ответа; Виды и примеры ошибочных ответов от API; Рекомендация по обработке ошибочных ответов

Поиск документации