О чём раздел В данном разделе есть:
Документация для интеграции
HRlink предоставляет открытое API для интеграции. Но как именно осуществить интеграцию, как решить бизнес-кейс или как работает конкретный API-метод - для того чтобы разобраться с этими вопросами нужно изучать документацию.
У нас есть несколько различных документов, каждый из которых помогает с отдельными аспектами.
| Документация | Краткое описание |
|---|---|
| WIKI | Вы как раз тут) и эта документация нацелена на то, чтобы сформировать понимание того, как именно закрываются бизнес-кейсы Клиента. Тут рассматриваются подходы к интеграции, обобщённые бизнес-сценарии, есть дополнительное описание объектов (понимание структуры объектов и их поведения) существенно влияют на скорость интеграции. Также в некоторых случаях тут приводятся примеры API-методов, описание которых ещё не добавлено в документацию. |
GDOC | Описание самих API-методов:
|
REDOC | Более технологичная версия описания API-методов. В данную документацию заносится описание всех новых API-методов, также постепенно сюда переезжает описание из HR-Link_API В данной документации есть ендпоинты, входные и выходные параметры, примеры ответов и ошибки. В конечном итоге данная документация станет основным документом, описывающим работу API-методов. |
Дополнительные материалы ADDON | Есть единичные случаи, когда API-метод существует, но его нет ни в старой версии документации, ни в новой В этом случае, если такие методы должны использоваться в вашем кейсе интеграции, то мы для вас подготовим отдельное описание, которое в последствии будет добавлено в основную документацию, так что если вы не нашли нужное вам описание, просто сообщите вашему менеджеру и мы оперативно решим такой вопрос |
REST API - "Запрос-Ответ"
Важно
Для Интеграции HRlink предоставляет доступ к API в рамках тенанта Клиента.
Для передачи в HRlink и для получения информации из HRlink необходимо использовать REST API.
Система HRlink только отправляет ответы на запросы, поэтому для получения актуальной информации о состоянии объектов (документы, заявления, сотрудники и т.д.) на стороне Клиента необходимо реализовывать периодические опросы HRlink, для получения обновлённой информации.
Важно, чтобы ИС Клиента могла обеспечить обработку информации, поступающей в ответ на запрос.
Способы аутентификации
Тут → Определите способ аутентификации описано в каком случае какой способ аутентификации использовать
В описании API-методов есть указание по способам авторизации (через логин/пароль, через токен)
В разделе [Способы аутентификации и авторизации] более детально раскрыта информация о более сложных механиках аутентификации
- Вход пользователя в HRlink через сторонний сервис аутентификации
- Использование мастер-токена для интеграции с HRlink
- Сквозная аутентификация
Асинхронные процессы
Важно
Большая часть событий имеет синхронный формат процесса, однако некоторые из событий являются ассинхронными.
Нужно учитывать, что выполнение асинхронных событий может занимать какое-то время, поэтому HRlink в ряде случаев возвращает не ответ на запрос, а некую информацию о процессе.
- Конвертация файла в формат PDF/A - все файлы, которые будут участвовать в КЭДО преобразуются (в соответствии с требованиями) в формат PDF/A.
- Процесс конвертации запускается после успешного создания черновика документа
- Процесс применяется при подаче Заявления из файла
- Выпуск УНЭП
- При запуске процесса выпуска УНЭП, если все валидации пройдены возвращается
{"result":true}чтобы понять состояние выпуска, необходимо обратиться к объекту Сотрудник.
- При запуске процесса выпуска УНЭП, если все валидации пройдены возвращается
- Создание документа с совмещённой отправкой - в ответ на запрос возвращается идентификатор события. Чтобы получить информацию о ожидаемом документе необходимо использовать фильтрационные параметры при запросе реестра документов.
- Подписание
- При запросе подписания УНЭП возвращается идентификатор события подписания, а не сам результат подписания
- При запросе подписания ПЭП Госуслуги - происходит перенаправление пользователя на сайт Портал Работа в России, где производится подписание.
- При запросе подписания УНЭП Госключ - происходит отправка документа в Госключ, само подписание происходит в мобильном приложении.
- Обновление печатной формы с оттиском - после каждого подписания 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; Рекомендация по обработке ошибочных ответов
Поиск документации