Внутренний справочник сотрудников редко существует полностью изолированно.

В организации уже могут работать кадровые системы, Active Directory, телефонная станция, системы управления помещениями и другие информационные решения. Каждая из них содержит часть данных, которые могут быть нужны корпоративному каталогу.

Ручной перенос информации между такими системами быстро становится неудобным.

Для автоматического обмена может использоваться программный интерфейс — API.

Что такое API справочника сотрудников

API позволяет одной информационной системе обращаться к данным другой системы программным способом.

Например:

Кадровая система

→ API

→ Оргнавигатор

Кадровая система может передать информацию о сотруднике, а справочник — создать или обновить соответствующую карточку.

Пользователю при этом не требуется вручную переносить данные.

Зачем справочнику нужен API

Основная задача API — автоматизировать обмен данными.

Например, организация может передавать:

сотрудников;
подразделения;
должности;
телефоны;
электронную почту;
помещения;
другие связанные объекты.

Это позволяет использовать справочник как единое пользовательское представление информации, не заставляя каждую систему хранить все данные самостоятельно.

API и импорт файлов

API не обязательно заменяет файловый импорт.

Это два разных подхода.

При файловом обмене система формирует CSV или другой файл:

Кадровая система

→ employees.csv

→ Справочник

При API обмен происходит непосредственно между системами:

Кадровая система

→ HTTP-запрос

→ API справочника

→ обновление данных

Выбор зависит от требований организации.

Когда достаточно CSV

Файловый обмен может быть вполне подходящим вариантом.

Например, если кадровые данные меняются нечасто, можно один раз в сутки формировать файл.

Для многих организаций этого достаточно.

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

Когда API особенно полезен

Программный интерфейс может быть востребован, если:

в организации много сотрудников;
данные часто меняются;
работает несколько информационных систем;
требуется автоматическое обновление;
необходимо передавать изменения без ручного участия;
справочник должен стать частью корпоративной инфраструктуры.

Какие операции может предоставлять API

Набор операций зависит от конкретной системы.

Например, API может позволять:

получить список сотрудников;
получить карточку сотрудника;
создать сотрудника;
изменить данные сотрудника;
архивировать сотрудника;
получить подразделения;
получить помещения;
обновить отдельные поля.

При проектировании API важно предоставлять только те операции, которые действительно необходимы.

Получение списка сотрудников

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

Например:

GET /api/employees

Система может вернуть список доступных записей.

Для большой организации лучше не передавать тысячи сотрудников одним запросом.

Пагинация

Если сотрудников несколько тысяч, API может использовать постраничную выдачу.

Например:

GET /api/employees?page=1&limit=100

Первый запрос возвращает первые 100 записей.

GET /api/employees?page=2&limit=100

Так клиент постепенно получает весь набор данных.

Получение конкретного сотрудника

Для работы с одной карточкой может использоваться идентификатор.

Например:

GET /api/employees/10452

В ответ система возвращает данные конкретного сотрудника.

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

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

API может поддерживать создание новой записи.

Например:

POST /api/employees

Передаваемые данные могут включать:

{
  "externalId": "10452",
  "name": "Иванов Иван Иванович",
  "position": "Начальник отдела",
  "departmentId": "D002"
}

После обработки система создаёт соответствующую карточку.

Обновление сотрудника

Для существующей записи может использоваться отдельный запрос.

Например:

PATCH /api/employees/10452

Можно изменить только необходимые поля.

Например, при переводе сотрудника достаточно передать новое подразделение.

Почему PATCH может быть удобнее полной замены

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

Изменился только телефон.

Нет необходимости передавать всю карточку.

Можно изменить только одно значение:

{
  "phone": "1234"
}

Это уменьшает объём передаваемых данных и снижает риск случайного изменения других полей.

Идентификаторы в API

Как и при файловом импорте, API должен использовать стабильные идентификаторы.

Например:

externalId = 10452

Так интегрирующая система может однозначно определить нужного сотрудника.

Связывать записи только по ФИО нежелательно.

Идемпотентность операций

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

Например, система отправила запрос на создание сотрудника, но не получила ответ из-за временного сбоя сети.

Интеграция повторяет запрос.

Если API правильно спроектирован, повторная операция не должна создавать второго такого же сотрудника.

Что делать при повторной передаче данных

Предположим, один и тот же сотрудник передан дважды:

externalId = 10452

API должно понимать, что речь идёт об одной записи.

Поэтому внешний идентификатор должен быть уникальным в пределах источника данных.

Синхронизация изменений

API может использоваться не только для полной загрузки.

Например, система может запрашивать изменения за определённый период:

GET /api/employees?updatedAfter=2026-08-20T00:00:00

В ответ возвращаются только изменившиеся записи.

Такой подход уменьшает объём обмена.

Событийная интеграция

В более сложной архитектуре изменения могут передаваться практически сразу после их возникновения.

Например:

Создан сотрудник

↓

Кадровая система

↓

Событие

↓

API справочника

↓

Новая карточка

Такой вариант позволяет поддерживать данные почти в реальном времени.

API подразделений

Интеграция может распространяться не только на сотрудников.

Например:

GET /api/divisions

может возвращать организационную структуру.

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

Иерархия подразделений

Для описания структуры может использоваться:

{
  "id": "D002",
  "name": "Отдел закупок",
  "parentId": "D001"
}

Поле parentId позволяет восстановить положение подразделения в дереве.

API помещений

Если справочник содержит здания и кабинеты, эти объекты также могут участвовать в интеграции.

Например:

GET /api/locations

может возвращать здания, этажи и помещения.

Сотрудник при этом может быть связан с конкретным кабинетом.

Связи между объектами

В сложном справочнике важно передавать не только сами объекты, но и связи между ними.

Например:

Сотрудник

→ подразделение

→ кабинет

→ здание

API должно позволять корректно устанавливать такие связи.

Что делать, если связанный объект отсутствует

Предположим, интеграция передала сотрудника:

departmentId = D002

но подразделения D002 ещё нет.

Система должна иметь определённое поведение.

Возможны варианты:

отклонить запись;
временно сохранить её без подразделения;
создать подразделение автоматически;
поместить ошибку в очередь повторной обработки.

Автоматическое создание подходит не для каждого сценария.

Авторизация API

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

Для API могут использоваться:

API-ключи;
токены;
OAuth;
сервисные учётные записи;
другие механизмы авторизации.

Выбор зависит от инфраструктуры организации.

Права доступа API

Не каждой интеграции нужны одинаковые возможности.

Например:

Кадровая система

→ создание и изменение сотрудников

АТС

→ изменение телефонов

Система помещений

→ изменение кабинетов

Такое разделение уменьшает риск случайного изменения чужих данных.

Принцип минимальных прав

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

Например:

GET /api/employees

может быть доступен системе отчётности.

А операции:

POST
PATCH
DELETE

для неё должны быть запрещены.

Защита API

Даже если справочник работает во внутренней сети, API требует защиты.

Необходимо учитывать:

кто может подключаться;
какие операции доступны;
какие данные передаются;
где хранятся токены;
ведётся ли журнал запросов.

Внутренняя сеть сама по себе не означает отсутствие рисков.

HTTPS во внутренней сети

Если API передаёт сведения о сотрудниках, желательно использовать защищённое соединение.

Например:

https://directory.company.local/api/employees

Шифрование защищает данные при передаче между системами.

Ограничение доступа по сети

Дополнительным уровнем защиты может быть ограничение источников запросов.

Например, API доступен только серверам определённых подсетей.

Так можно не выставлять программный интерфейс во внешнюю сеть.

Логирование запросов

Для интеграции полезно сохранять информацию о работе API.

Например:

21.08.2026 02:15
POST /api/employees
Источник: hr-system
Результат: 201

При ошибке журнал помогает определить причину проблемы.

Обработка ошибок

API должно возвращать понятный результат операции.

Например:

{
  "error": "department_not_found",
  "message": "Подразделение D002 не найдено"
}

Интегрирующая система может понять причину и выполнить необходимые действия.

HTTP-коды

Для стандартных API могут использоваться HTTP-коды.

Например:

Код	Значение
`200`	операция выполнена
`201`	объект создан
`400`	некорректный запрос
`401`	требуется авторизация
`403`	недостаточно прав
`404`	объект не найден
`409`	конфликт
`500`	внутренняя ошибка

Такая схема позволяет интеграциям обрабатывать результаты предсказуемо.

Ограничение частоты запросов

Если API доступен нескольким системам, одна из них может случайно создать чрезмерную нагрузку.

Поэтому иногда полезно ограничивать количество запросов.

Например:

1000 запросов в минуту

Конкретное значение зависит от нагрузки и инфраструктуры.

Версионирование API

Интеграция может существовать несколько лет.

За это время структура данных может измениться.

Поэтому API желательно версионировать.

Например:

/api/v1/employees

После значительных изменений может появиться:

/api/v2/employees

Старую версию при этом можно некоторое время сохранять для совместимости.

Документация API

Без документации интеграцию сложно сопровождать.

Необходимо описывать:

доступные методы;
параметры;
форматы данных;
авторизацию;
ошибки;
ограничения;
версии API.

Хорошая документация позволяет подключить новую систему без изучения исходного кода справочника.

API и персональные данные

Программный интерфейс может передавать персональные данные сотрудников.

Поэтому необходимо учитывать те же ограничения, что и при обычном просмотре информации.

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

Ограничение состава данных

Например, одна интеграция получает:

{
  "name": "Иванов Иван Иванович",
  "position": "Начальник отдела",
  "phone": "1234"
}

А другая может получать только:

{
  "name": "Иванов Иван Иванович",
  "department": "Отдел закупок"
}

Такой подход позволяет ограничивать объём передаваемой информации.

API и экспорт данных

API не означает, что экспорт файлов больше не нужен.

Оба механизма могут использоваться одновременно.

Например:

API

→ регулярная автоматическая синхронизация

CSV

→ разовая выгрузка для анализа

Excel

→ работа ответственного сотрудника

Каждый механизм решает свою задачу.

API в закрытом контуре

Для организаций с внутренней сетью API может работать полностью внутри локальной инфраструктуры.

Например:

[Кадровая система]
        |
        v
[Оргнавигатор API]
        |
        v
[Внутренние пользователи]

Внешний интернет для обмена данными при этом не требуется.

Когда API не нужен

Не каждой организации необходимо создавать сложную интеграцию.

Если справочник содержит несколько сотен сотрудников и обновляется один раз в месяц, регулярного импорта CSV может быть достаточно.

API стоит внедрять тогда, когда его преимущества оправдывают дополнительные работы по настройке и сопровождению.

Что определить перед разработкой интеграции

Перед подключением API желательно определить:

какие системы будут источниками данных;
какие объекты необходимо передавать;
кто является владельцем каждого поля;
какие идентификаторы используются;
какие операции нужны;
какие права должны быть у каждой интеграции;
как обрабатываются ошибки;
как выполняется журналирование;
как будет обновляться версия API.

Оргнавигатор и API

Оргнавигатор может использовать программный API для интеграции с корпоративными информационными системами.

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

При этом API может работать внутри инфраструктуры организации и использовать существующие механизмы защиты и контроля доступа.

Итог

API превращает внутренний справочник из изолированного приложения в часть общей информационной инфраструктуры организации.

С его помощью можно автоматически получать и обновлять данные о сотрудниках, подразделениях, контактах и помещениях.

Однако сам по себе API не решает вопросы интеграции. Необходимо заранее определить источники данных, идентификаторы, права доступа, правила обработки ошибок и состав передаваемой информации.

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