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

Первый запрос

Проверим подключение к API двумя запросами: получим текущего пользователя и список сотрудников.

Подготовка​

Вам потребуется:

  • tenantHost — адрес тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink (например, company.hr-link.ru). HRlink выдаёт адрес при покупке лицензии
  • Токен аутентификации — пользовательский или мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. (см. Аутентификация)

clientId получим из первого же запроса.

Шаг 1. Получить текущего пользователя​

curl -X GET "https://{tenantHost}/api/v2/currentUser" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {ваш_токен}"

Ответ:

{
  "result": true,
  "currentUser": {
    "personalData": {
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "lastName": "Иванов",
      "firstName": "Иван",
      "patronymic": "Иванович",
      "email": "ivanov@company.ru",
      "lifeTimeGroup": "GT1YLET3Y"
    },
    "clientUsers": [
      {
        "id": "d4e5f6a7-1111-2222-3333-444455556666",
        "externalId": "CU-001",
        "client": {
          "id": "668a634a-c4e9-4416-a481-656c3f17ea06",
          "name": "ООО Компания"
        },
        "roles": [],
        "registrySettings": []
      }
    ],
    "digitalSignatureData": {
      "certificates": [],
      "govKeySigningEnabled": false,
      "qesSigningEnabled": false
    },
    "permissions": {
      "userPermissions": [],
      "clientPermissions": []
    }
  }
}
Где взять clientId

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

Шаг 2. Получить список сотрудников​

Подставьте clientId из предыдущего шага в URL:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/employees/getRegistry" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {ваш_токен}" \
  -d '{"limit":10,"offset":0}'
Тело запроса

Получение сотрудников — POST, хотя по смыслу это чтение данных. Тело запроса обязательно. Если фильтры и пагинация не нужны, передайте пустой объект {}. В примерах limit и offset передаются в JSON-теле.

Ответ:

{
  "result": true,
  "employees": [
    {
      "id": "b2c3d4e5-1111-2222-3333-444455556666",
      "externalId": "EMP-001",
      "clientUser": {
        "id": "d4e5f6a7-1111-2222-3333-444455556666",
        "externalId": "CU-001",
        "userId": "a1b2c3d4-1111-2222-3333-444455556666"
      },
      "legalEntity": {
        "id": "c3d4e5f6-1111-2222-3333-444455556666",
        "externalId": "LE-001"
      },
      "department": {
        "id": "e5f6a7b8-1111-2222-3333-444455556666",
        "name": "IT-отдел"
      },
      "position": {
        "id": "f6a7b8c9-1111-2222-3333-444455556666",
        "name": "Разработчик"
      },
      "lastName": "Иванов",
      "firstName": "Иван",
      "patronymic": "Иванович",
      "version": 3
    }
  ]
}

Поля limit и offset управляют пагинацией.

Типичные ошибки​

401 Unauthorized​

Невалидный или просроченный токен.

СитуацияЧто проверить
Пользовательский токенСрок действия — 1 год. Возможно, токен истёк, владелец уволен или сбросил пароль
Master-Api-TokenMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора.Указаны ли оба заголовка Impersonated-User-Id и Impersonated-User-Id-Type. Не истёк ли мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. (код 22.015)

Полный список кодов ошибок аутентификации — в разделах Ошибки аутентификации и Перевыпуск токенов.

403 Forbidden​

У пользователя нет прав на эту операцию. Проверьте:

  • пользователь относится к указанному clientId
  • у пользователя есть роль кадровика (HR) для доступа к реестру сотрудников
Права при работе с мастер-токеном

Доступные данные зависят от прав пользователя, указанного в Impersonated-User-Id. Если у пользователя нет роли кадровика — он увидит только ограниченный набор данных.

400 Bad Request​

Невалидный формат данных. Проверьте:

  • clientId передан в формате UUID
  • в теле POST-запроса есть хотя бы {}
  • JSON корректен (нет лишних запятых, кавычки двойные)

Что дальше​

  1. Идентификаторы — разница между id и externalId
  2. Модель данных — сущности userUser Физическое лицо в системе HRlink. Один User соответствует одному реальному человеку. С пользователем связаны персональные данные, документы (СНИЛС, паспорт, ИНН) и логины (email, телефон)., clientUserClientUser Связь пользователя с пространством клиента — пара (userId, clientId). Один пользователь может относиться к нескольким клиентам, но в одном клиенте встречается только один раз., employeeEmployee Связь пользователя пространства клиента с юрлицом — пара (clientUserId, legalEntityId). Один пользователь может иметь несколько записей Employee в разных юрлицах или даже в одном.
  3. Синхронизация сотрудников — загрузите организационную структуру
  4. Отправка документов — отправьте первый документ на подписание