HR Directory API

API интеграции сотрудников

API позволяет синхронизировать справочник сотрудников из 1С и других учётных или HR-систем (ERP, HRM, собственная учётная система) с организацией в Оснарис. Контракт универсальный и не привязан к конкретному источнику данных.

Введение

Создайте интеграцию в личном кабинете Оснарис
Получите API-ключ
Выполните preview данных
Запустите синхронизацию
При необходимости читайте синхронизированный справочник

Интеграция создаётся в личном кабинете Оснарис, в разделе модуля «Обучение» — там же выдаётся API-ключ.

Авторизация

Текущий API использует Bearer-токен:

Authorization: Bearer odk_xxxxx

API-ключ относится к конкретной организации и конкретному source system. Секрет создаётся в Оснарис и не должен публиковаться в клиентском frontend-коде.

Scopes

training.directory.read: чтение сотрудников, синхронизированных данным source system.
training.directory.write: preview и синхронизация сотрудников.

Сотрудники

GET /employees

Возвращает всех сотрудников организации для данного source system, синхронизированных ранее через этот API.

Требуемый scope: training.directory.read

POST /employees:preview

Проверяет пакет сотрудников и показывает, какие записи будут созданы или обновлены, без применения изменений.

Требуемый scope: training.directory.write

POST /employees:sync

Создаёт и обновляет сотрудников из пакета. Поддерживает безопасный повтор запроса через заголовок Idempotency-Key — при совпадении ключа для уже завершённого запуска возвращает тот же результат, не выполняя синхронизацию повторно.

Требуемый scope: training.directory.write

`deactivateMissing`

false / отсутствует — сотрудники, которых нет в текущем пакете, остаются как есть.
true — активные сотрудники данного source system, отсутствующие в полном пакете, переводятся в inactive.

Используйте deactivateMissing=true только при передаче полного актуального справочника source system. Разрешено только для непустого пакета без ошибок валидации — иначе запрос отклоняется с 400.

Схема сотрудника

Поле	Тип	Обязательное	Назначение
`externalId`	`string`	да	Уникальный ID сотрудника в вашей системе. До 200 символов.
`personnelNumber`	`string`	нет	Табельный номер. До 100 символов.
`lastName`	`string`	нет	Фамилия. До 300 символов.
`firstName`	`string`	нет	Имя. До 300 символов.
`middleName`	`string`	нет	Отчество. До 300 символов.
`displayName`	`string`	нет	Готовое отображаемое имя. До 300 символов. Если не передано, собирается из lastName/firstName/middleName, а при их отсутствии — из externalId.
`email`	`string`	нет	До 300 символов.
`phone`	`string`	нет	До 100 символов.
`position`	`string`	нет	Должность. До 300 символов.
`department`	`string`	нет	Подразделение. До 300 символов.
`managerExternalId`	`string`	нет	externalId руководителя из того же source system. До 200 символов.
`status`	`"active" \| "inactive"`	нет	По умолчанию active.
`roles`	`string[]`	нет	Роли source system. Максимум 50 элементов.
`customFields`	`object`	нет	Дополнительные поля произвольной структуры.
`updatedAt`	`string (date-time)`	нет	Только в ответах GET /employees — не передавайте это поле при sync.

Ограничения

externalId обязателен
externalId — до 200 символов после обрезки
personnelNumber — до 100 символов
phone — до 100 символов
managerExternalId — до 200 символов
большинство текстовых полей — до 300 символов
roles — максимум 50 элементов
один запрос обрабатывает максимум 5000 сотрудников (лишние попадают в errors, запрос не отклоняется целиком)
тело запроса читается с лимитом 8 МиБ

Идентификация и upsert

Сотрудник идентифицируется внутри организации по сочетанию source system + externalId. Повторная синхронизация существующего externalId обновляет запись, новыйexternalId создаёт сотрудника. Email не является первичным ключом.

Руководитель

managerExternalId связывает сотрудника с руководителем из того же source system:

[
  { "externalId": "EMP-001", "displayName": "Руководитель" },
  { "externalId": "EMP-002", "displayName": "Сотрудник", "managerExternalId": "EMP-001" }
]

Ошибки и коды ответа

HTTP	Когда
`200`	успешный GET / preview / sync
`400`	некорректный запрос — невалидный JSON, ошибка валидации, запрещённый сценарий `deactivateMissing`. Внутренние ошибки preview/sync тоже возвращаются как 400, не как 500.
`401`	отсутствующий/невалидный API-ключ или ключ без требуемого scope
`429`	превышен лимит запросов — 120 в минуту для данного API-ключа
`500`	внутренняя ошибка чтения справочника — только на `GET /employees`

Построчные ошибки в пакете

preview/sync возвращают построчные ошибки прямо внутри 200-ответа:

{
  "index": 3,
  "externalId": "EMP-004",
  "errors": ["status должен быть active или inactive"]
}

пустой externalId → ошибка
повторяющийся externalId в одном пакете → ошибка
невалидный status → ошибка
customFields должен быть объектом
пакет больше 5000 записей → отдельная строка ошибки, а не отказ всего запроса

GET /employees

curl \
  -H "Authorization: Bearer $OSNARIS_API_KEY" \
  "${OSNARIS_API_URL}/employees"

200 OK

{
  "employees": [
    {
      "externalId": "EMP-001",
      "displayName": "Иванов Иван Иванович",
      "email": "ivanov@example.ru",
      "position": "Менеджер",
      "department": "Продажи",
      "status": "active",
      "roles": [],
      "customFields": {},
      "updatedAt": "2026-08-17T18:40:14.000Z"
    }
  ]
}

POST /employees:preview

curl -X POST \
  -H "Authorization: Bearer $OSNARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"employees":[{"externalId":"EMP-001","displayName":"Иванов Иван Иванович"}]}' \
  "${OSNARIS_API_URL}/employees:preview"

200 OK

{
  "employees": [
    { "externalId": "EMP-001", "displayName": "Иванов Иван Иванович" }
  ],
  "errors": [],
  "summary": { "received": 1, "valid": 1, "create": 1, "update": 0, "errors": 0 }
}

POST /employees:sync

curl -X POST \
  -H "Authorization: Bearer $OSNARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-001" \
  -d '{"employees":[{"externalId":"EMP-001","displayName":"Иванов Иван Иванович","status":"active"}],"deactivateMissing":false}' \
  "${OSNARIS_API_URL}/employees:sync"

200 OK

{
  "runId": "b7e2...",
  "replayed": false,
  "summary": { "received": 1, "created": 1, "updated": 0, "deactivated": 0, "errors": 0 },
  "errors": []
}

401

{
  "error": "invalid_directory_credential",
  "requiredScope": "training.directory.write"
}

429

{
  "error": "rate_limit_exceeded"
}

400

{
  "error": "Некорректный запрос",
  "errors": ["deactivateMissing разрешён только для непустого пакета без ошибок"]
}