Обзор API

Через REST API HRlink вы интегрируете тенант с кадровыми системами (1С, БОСС-Кадровик, SAP, Битрикс24 и другими). API покрывает все действия, доступные в интерфейсе тенанта: синхронизацию сотрудников и оргструктуры, работу с документами, отправку на подписание, отслеживание статусов.

Базовый URL

https://{tenantHost}/api/{version}/clients/{clientId}/{resource}

Компонент	Описание	Пример
`tenantHost`	Домен тенанта HRlink	`company.hr-link.ru`
`version`	Версия эндпоинта	`v1`, `v2`
`clientId`	UUID пространства внутри тенанта (в API называется `client` — это не заказчик, см. ниже)	`f47ac10b-58cc-4372-a567-0e02b2c3d479`
`resource`	Путь к ресурсу	`employees`, `documents`

Большинство эндпоинтов содержат clientId в пути. Отдельные служебные эндпоинты (например, получение текущего пользователя) работают без него.

Откуда взять tenantHost

tenantHost — адрес тенанта HRlink. Вы получаете его при покупке лицензии.

Что такое client

Это не заказчик

В API HRlink сущность называется client по историческим причинам. Это не заказчик, не контрагент и не пользователь, а изолированное пространство внутри тенанта. Переименовать сущность нельзя — это сломает существующие интеграции, поэтому в URL, телах запросов и ответах вы будете встречать слово client именно в этом техническом значении.

Тенант HRlink — это ваш экземпляр системы на отдельном домене, например company.hr-link.ru. Внутри одного тенанта может быть несколько клиентов (client) — изолированных пространств. Каждый клиент — отдельная структура со своим набором юридических лиц, организационных структур, сотрудников, документов, маршрутов подписания и настроек.

Данные клиентов не пересекаются: сотрудники, документы и настройки одного клиента недоступны в контексте другого. Поэтому почти каждый запрос к API требует clientId — он указывает, с каким именно пространством клиента вы работаете.

Типичная структура:

Тенант (company.hr-link.ru)
├── Клиент A                        ← clientId: aaa-...
│   ├── Юрлицо — ООО «Альфа»
│   ├── Юрлицо — ООО «Альфа-Сервис»
│   ├── оргструктура
│   ├── сотрудники
│   ├── документы
│   └── маршруты подписания
├── Клиент B                        ← clientId: bbb-...
│   ├── Юрлицо — ООО «Бета»
│   ├── оргструктура
│   ├── сотрудники
│   ├── документы
│   └── маршруты подписания
└── ...

Один клиент может объединять несколько юридических лиц — например, группу компаний с общим кадровым учётом.

Как получить clientId

Вызовите Текущий пользователь. В ответе найдите массив currentUser.clientUsers — у каждого элемента есть объект client с полем id. Это и есть clientId для подстановки в URL.

{
  "result": true,
  "currentUser": {
    "clientUsers": [
      {
        "client": {
          "id": "668a634a-c4e9-4416-a481-656c3f17ea06",
          "name": "Название клиента"
        }
      }
    ]
  }
}

Формат запросов и ответов

API работает с JSON по умолчанию. Формат можно указать двумя способами:

Через заголовки HTTP

Content-Type: application/json
Accept: application/json

Через параметр format

GET /api/v2/currentUser?format=JSON

Поддерживаемые значения: JSON, XML.

Структура ответа

Все ответы API содержат поле result. Остальные поля зависят от метода: например, Текущий пользователь возвращает currentUser, а Получить сотрудников — employees.

Успешный ответ

{
  "result": true,
  "currentUser": {
    "clientUsers": []
  }
}

Ответ с ошибкой

{
  "result": false,
  "errorId": "ea244925-8316-4f7c-9047-895020e61720",
  "errorMessage": "Описание ошибки",
  "errorCode": "51.203",
  "operationCode": "51.060"
}

Поле	Описание
`result`	`true` — успех, `false` — ошибка
`errorId`	UUID ошибки (для обращения в поддержку)
`errorMessage`	Текстовое описание ошибки
`errorCode`	Код ошибки
`operationCode`	Код операции

Общие заголовки

Заголовок	Описание	Обязательность
`User-Api-Token`	Токен пользователя	Один из способов аутентификации
`Master-Api-Token`	Мастер-токен	Один из способов аутентификации
`Impersonated-User-Id`	ID пользователя, от имени которого выполняется запрос	При использовании мастер-токена
`Impersonated-User-Id-Type`	Тип ID: `HR_LINK_ID`, `SNILS`, `EXTERNAL_ID`	При использовании мастер-токена
`Content-Type`	Тип контента	Для POST/PUT запросов
`Accept`	Ожидаемый формат ответа	Рекомендуется

Пагинация

Эндпоинты, возвращающие списки, поддерживают пагинацию через параметры:

Параметр	Описание	По умолчанию
`limit`	Количество элементов в ответе	`50`
`offset`	Смещение от начала списка	`0`

Значение limit по умолчанию

Стандартное значение limit — 50. Для отдельных эндпоинтов значение по умолчанию другое — смотрите спецификацию конкретного эндпоинта. В on-premise поставках администратор меняет значение по умолчанию через конфигурацию сервера.

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

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

{"limit":50,"offset":0}

Версионирование эндпоинтов

У эндпоинта может быть несколько версий (v1, v2, ... v5). HRlink выпускает новую версию, когда меняется контракт — структура запроса или ответа. Старые версии продолжают работать без изменений: HRlink гарантирует обратную совместимость. Переходите на новую версию, только если вам нужна функциональность, которую в ней добавили.

Какую версию использовать

Используйте последнюю доступную версию эндпоинта. Она содержит все улучшения и исправления. Например, если доступны updateEmployeeByExternalIdV2 ... V5, используйте V5.

HTTP-статусы

Статус	Описание
`200`	Успешная операция
`400`	Некорректный запрос (невалидные данные)
`401`	Не аутентифицирован (невалидный или отсутствующий токен)
`403`	Нет прав доступа
`404`	Ресурс не найден
`429`	Слишком много запросов (rate limiting)

Rate limiting

Лимит запросов на тенант адаптивный — порог подстраивается под текущую нагрузку и долю тяжёлых операций. При превышении сервер возвращает 429. Заголовков Retry-After / X-RateLimit-* нет — используйте экспоненциальный backoff с jitter. Подробнее про все лимиты API: Ограничения.

Что дальше

Настройте аутентификацию — получите токен для запросов
Выполните первый запрос — проверьте подключение
Изучите модель данных — поймите структуру сущностей

Базовый URL​

Что такое client​

Формат запросов и ответов​

Через заголовки HTTP​

Через параметр format​

Структура ответа​

Успешный ответ​

Ответ с ошибкой​

Общие заголовки​

Пагинация​

Версионирование эндпоинтов​

HTTP-статусы​

Что дальше​