Модель сотрудника

Сотрудник (Employee) — центральный ресурс API. Это карточка человека в конкретном тенанте: скалярные поля и ссылки на связанные сущности. Получить её можно списком GET /employees или поштучно GET /employees/{employee_id}.

{
  "id": "3f2a9c7e-…",
  "employee_number": "HR-014",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "department_id": "d1c4…",
  "job_title_id": "7b2e…",
  "organization_id": "a90f…",
  "location_id": null,
  "manager_id": "8c5d…",
  "work_email": "kulyash@keruen.kz",
  "start_date": "2024-03-01",
  "end_date": null,
  "create_time": "2024-03-01T04:00:00Z",
  "update_time": "2026-02-10T09:30:00Z",
  "redacted_fields": []
}

Поля

Поле	Тип	Описание
`id`	UUID	Идентификатор сотрудника в тенанте.
`employee_number`	string	Табельный номер. Может быть пустым.
`status`	enum	Статус жизненного цикла (`EmployeeStatus`). См. Статусы и жизненный цикл.
`department_id`	UUID	Отдел. Сам объект отдела — через `expand=department`.
`job_title_id`	UUID	Должность. Объект — через `expand=job_title`.
`organization_id`	UUID	Юридическое лицо, к которому относится сотрудник.
`location_id`	UUID	Локация. Может быть `null`.
`manager_id`	UUID	Руководитель. Ссылку `manager` (id + имя) даёт `expand=manager`.
`work_email`	string	Рабочая почта.
`start_date`	date	Дата начала работы (`YYYY-MM-DD`).
`end_date`	date	Дата окончания. `null`, пока сотрудник не уволен.
`create_time`	RFC 3339	Момент создания карточки (UTC).
`update_time`	RFC 3339	Момент последнего изменения карточки. По нему работает `updated_since`.
`redacted_fields`	string[]	Поля, скрытые правами владельца ключа, в формате `объект.поле`.

Идентификаторы — UUID-строки, моменты времени — RFC 3339 в UTC, календарные даты — YYYY-MM-DD. Отсутствующие значения присутствуют в ответе (пустая строка или null), а не пропадают из объекта. Незнакомые поля и значения enum игнорируйте — состав ответа расширяется аддитивно.

Связанные объекты

Поля person, department, job_title и manager — это отдельные сущности, доступные только по запросу через expand. В базовом ответе их нет, есть только *_id-ссылки. Как обходить эти связи — на странице Employee-graph.

`person` (`expand=person`)

Поле	Тип	Описание
`first_name`, `last_name`, `middle_name`	string	Имя, фамилия, отчество
`full_name`	string	Готовое отображаемое ФИО
`iin`	string	ИИН. Скрывается правами → `redacted_fields: ["persons.iin"]`
`birth_date`	date	Дата рождения (`YYYY-MM-DD`)
`phone`	string	Личный телефон
`personal_email`	string	Личная почта

`department` и `job_title`

Оба объекта — минимальные ссылки: id + title. Других полей (руководитель отдела, иерархия, штатное расписание) в них нет.

`manager` (`expand=manager`)

Ссылка на руководителя: id + full_name. Это намеренно узкий объект — чтобы получить полную карточку руководителя, запросите GET /employees/{manager.id} своим ключом: так к ней применятся права и редакция полей.

Модель доступа

Даже с областью employees:read ключ видит не всё. Эффективный доступ — это пересечение областей ключа и прав владельца ключа. Область — необходимое, но не достаточное условие: сотрудников и поля, недоступные профилю прав владельца, ключ не увидит. Поля, которые владелец не вправе видеть (например ИИН), в ответ не попадают, а их ключи перечисляются в redacted_fields в формате объект.поле. Так, при expand=person без права на ИИН:

{
  "id": "3f2a9c7e-…",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "person": {
    "first_name": "Куляш",
    "last_name": "Байсеитова",
    "full_name": "Куляш Байсеитова"
  },
  "redacted_fields": ["persons.iin"]
}

Отсутствие поля в redacted_fields и пустое значение — разные вещи. Поле в redacted_fields означает «скрыто правами»; пустое значение при отсутствии в redacted_fields означает «данных нет». Не путайте их при синхронизации.

Одиночная карточка неразличима по причине недоступности: «не существует», «нет доступа» и «черновик/удалён» дают одинаковый 404 EMPLOYEE_NOT_FOUND. По коду ответа нельзя выяснить, существует ли скрытый от вас сотрудник.

Дальше

Employee-graph

Связи сотрудника и обход через expand.

Статусы и жизненный цикл

Значения EmployeeStatus и переходы.

Пагинация

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

Начало работы

Сотрудники

Документы

Рецепты

Модель сотрудника

Поля

Связанные объекты

`person` (`expand=person`)

`department` и `job_title`

`manager` (`expand=manager`)

Модель доступа

Дальше

Employee-graph

Статусы и жизненный цикл

Пагинация

​Поля

​Связанные объекты

​person (expand=person)

​department и job_title

​manager (expand=manager)

​Модель доступа

​Дальше

Employee-graph

Статусы и жизненный цикл

Пагинация

Поля

Связанные объекты

`person` (`expand=person`)

`department` и `job_title`

`manager` (`expand=manager`)

Модель доступа

Дальше