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

Сотрудник (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[]	Поля, скрытые правами владельца ключа, в формате `объект.поле`.
`custom_fields`	object	Кастомные поля по `api_name`. Только с `expand=custom_fields`.

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

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

Поля person, department, job_title и manager — это отдельные сущности, доступные только по запросу через expand. Кастомные поля карточки тоже приходят только по 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} своим ключом: так к ней применятся права и редакция полей.

Кастомные поля

Поля, которые компания добавила в карточку сотрудника сама (размер одежды, номер пропуска, грейд), приходят в custom_fields при expand=custom_fields. Это объект: ключ — api_name поля, значение — JSON по типу поля. Без expand=custom_fields объект пустой.

curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  "https://app.doodocs.kz/api/developer/v1/employees/3f2a9c7e-…?expand=custom_fields"

{
  "id": "3f2a9c7e-…",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "custom_fields": {
    "badge_number": "A-17",
    "shirt_size": "L",
    "languages": ["kk", "ru", "en"],
    "contract_end": "2027-03-01",
    "children": [
      { "name": "Айгерим", "birth_date": "2019-05-01" }
    ]
  },
  "redacted_fields": ["employees.salary_grade"]
}

Каталог полей

GET /employee_custom_fields возвращает описания полей: api_name, название, тип, варианты для списков и колонки для таблиц. Название приходит на языке из Accept-Language, если для него есть перевод. Область та же — employees:read.

{
  "custom_fields": [
    {
      "api_name": "shirt_size",
      "title": "Размер одежды",
      "description": "",
      "type": "CUSTOM_FIELD_TYPE_SELECT",
      "options": ["S", "M", "L", "XL"],
      "columns": [],
      "create_time": "2026-02-01T06:00:00Z",
      "update_time": "2026-02-01T06:00:00Z"
    }
  ]
}

Каталог и значения следуют одним правилам: в карточке приходят только ключи из каталога, а в каталоге только поля, значения которых владелец ключа вправе видеть у других сотрудников. Поля с видимостью «Только администраторы системы» есть в каталоге, только если владелец ключа — системный администратор.

Типы значений

`type`	JSON значения
`TEXT`, `MULTILINE_TEXT`, `EMAIL`, `URL`, `PHONE`	строка
`NUMBER`, `CURRENCY`, `PERCENTAGE`	число
`DATE`	строка `YYYY-MM-DD`
`DATETIME`	строка RFC 3339 в UTC; `YYYY-MM-DD`, если ввели только дату
`BOOLEAN`	`true` / `false`; у неотмеченного чекбокса значения нет
`SELECT`	строка, одно из `options`
`MULTISELECT`	массив строк из `options`
`LOOKUP`	строка — UUID связанной записи, без раскрытия
`TABLE`	массив объектов, ключи — `api_name` из `columns`

В таблице type сокращён: в ответе он приходит с префиксом CUSTOM_FIELD_TYPE_. Незнакомые типы игнорируйте — список будет расти.

Что важно знать

Нет ключа — нет значения. Если поле есть в каталоге, а ключа в custom_fields нет, значение пустое. Полей вне каталога в карточке не бывает, даже в карточке владельца ключа. Скрытые правами поля могут быть перечислены в redacted_fields как employees.<api_name>, но опирайтесь на каталог, а не на этот список.
Файлы и изображения пока не отдаются. Поля этих типов нет ни в каталоге, ни в значениях; колонки таких типов убираются и из таблиц.
Формульные (вычисляемые) поля не отдаются.
Значения не переводятся. Приходит значение в том виде, в каком его ввели.
Фильтра по кастомным полям нет. Отбирайте сотрудников на своей стороне.
Изменения. Правка значения меняет update_time карточки и отправляет employee.changed, поэтому updated_since её ловит. Изменение самого поля (название, варианты, видимость) карточки не трогает. Каталог и карточки читаются разными запросами, поэтому ключ, которого нет в вашей копии каталога, — повод перечитать каталог.
Только карточка сотрудника. Кастомные поля физлица (person) пока не отдаются.

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

Даже с областью 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`)

Кастомные поля

Каталог полей

Типы значений

Что важно знать

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

Дальше