> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Каноническая карточка сотрудника: поля, redacted_fields и модель доступа

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

```json theme={null}
{
  "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`). См. [Статусы и жизненный цикл](/ru/guides/employees/lifecycle). |
| `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\[] | Поля, скрытые правами владельца ключа, в формате `объект.поле`.                                             |

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

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

Поля `person`, `department`, `job_title` и `manager` — это отдельные сущности,
доступные только по запросу через `expand`. В базовом ответе их нет, есть только
`*_id`-ссылки. Как обходить эти связи — на странице
[Employee-graph](/ru/guides/employees/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` без права на ИИН:

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

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

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

## Дальше

<Columns cols={2}>
  <Card title="Employee-graph" icon="diagram-project" href="/ru/guides/employees/graph">
    Связи сотрудника и обход через `expand`.
  </Card>

  <Card title="Статусы и жизненный цикл" icon="chart-line" href="/ru/guides/employees/lifecycle">
    Значения `EmployeeStatus` и переходы.
  </Card>

  <Card title="Пагинация" icon="layer-group" href="/ru/api-reference/pagination">
    Обход списков и инкрементальная синхронизация.
  </Card>
</Columns>