> ## 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.

# Конвенции

> Версионирование, форматы, фильтры и совместимость

## Версионирование и совместимость

Версия указывается в пути: `/developer/v1`. Внутри одной версии возможны только
аддитивные изменения — новые поля, новые значения перечислений, новые ручки.

Ваша интеграция обязана выдерживать их без поломок:

* игнорируйте незнакомые поля в ответах;
* переживайте незнакомые значения `enum` (например новый статус сотрудника);
* не полагайтесь на порядок полей.

Ломающие изменения выходят только под новой мажорной версией пути с политикой
устаревания не менее шести месяцев.

## Форматы

* Тела запросов и ответов — JSON в кодировке UTF-8, имена полей в `snake_case`.
* Идентификаторы — строки UUID.
* Моменты времени — RFC 3339 в UTC (`2026-02-10T09:00:00Z`).
* Календарные даты — `YYYY-MM-DD`.
* Отсутствующие значения присутствуют в ответе (пустая строка или `null`), форма
  ответа стабильна.

## Фильтры и expand

Фильтры передаются query-параметрами. Для нескольких значений повторяйте параметр:

```
?status=EMPLOYEE_STATUS_ACTIVE&status=EMPLOYEE_STATUS_LEAVE
```

Запятая **не** разделяет значения — `?status=A,B` будет воспринято как одно
значение. То же правило для `expand` и `department_id`.

`expand` подгружает связанные объекты. Допустимы `person`, `department`,
`job_title`, `manager`; другие имена дают `DEVELOPER.INVALID_EXPAND`. Объект
`manager` намеренно узкий — только идентификаторы и отображаемое имя, без
персональных данных руководителя.

## Лимиты

Запросы ограничиваются по ключу. При превышении приходит `429`; повторяйте с
экспоненциальной задержкой.

## Видимость

Черновики приёма (внутренний статус `CREATED`) и удалённые сотрудники через
Developer API не отдаются никогда.