Тема
Люди и оргструктура
Семейство people.
norm_org_units
Дерево подразделений компании целиком. Состав подразделения — сигнал, по которому подразделение встречи определяется без модели: если большинство участников числится в одном подразделении, выбор сделан. Членство прямое, принадлежность верхним уровням выводится по полю parent_id. Доменное состояние not_ready — оргструктура не подключена: это ждёт человека, повторный вызов ничего не изменит.
Доступ: чтение · Списковый: нет · Версии контракта: 1
Аргументы
Аргументов нет.
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
units | да | список OrgUnit | Все подразделения компании; дерево строится по parent_id. |
error | нет | DomainError | Почему данных нет: оргструктура не подключена. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:units",
"label": "Подразделения"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"data": {
"units": [
{
"id": "u-root",
"name": "Компания",
"parent_id": null,
"kind": "company",
"sort_order": 0
},
{
"id": "u-sales",
"name": "Продажи",
"parent_id": "u-root",
"kind": "division",
"code": "012",
"sort_order": 10
},
{
"id": "u-retail",
"name": "Розница",
"parent_id": "u-sales",
"kind": "department",
"sort_order": 20
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:units"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Оргструктура не подключена: нет источника подразделений и людей. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}norm_people_list
Сотрудники компании страницами. Поле id — то значение, которое передаётся в поля протокола с людьми (participant_ids, organizer_id). Почты приходят в нижнем регистре, и у одного человека их бывает несколько: сопоставляйте по любой из них. Для следующей страницы передайте page.next_cursor как cursor; нет курсора — люди дочитаны. total — сколько людей всего с учётом фильтров. role_id отбирает тех, у кого есть назначение с этой ролью: так отвечают на вопрос «кто занимает роль». unit_id отбирает по прямому членству, без спуска в дочерние подразделения: спускайтесь сами по дереву norm_org_units. active_only не передан — отдаются все, кого хранит сервер; true — скрыты те, у кого дата увольнения уже наступила. Доменное состояние not_ready — оргструктура не подключена.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
active_only | нет | boolean | Скрыть уволенных; по умолчанию приходят все. |
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
role_id | нет | string | Найти тех, кто занимает эту роль: id из norm_roles_list. |
unit_id | нет | string | Найти тех, кто числится в подразделении напрямую, без дочерних. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
people | да | список Person | Сотрудники этой страницы. |
total | да | integer | Сколько сотрудников подошло под фильтр всего, на всех страницах. |
error | нет | DomainError | Почему данных нет: оргструктура не подключена. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people",
"label": "Сотрудники"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"total": 2,
"people": [
{
"id": "p-1042",
"name": "Анна Новикова",
"aliases": [
"Новикова А.",
"a.novikova"
],
"emails": [
"a.novikova@example.com",
"79001234567@example.com"
],
"unit_ids": [
"u-sales",
"u-retail"
],
"phone": "+7 900 123-45-67",
"handles": [
"@a_novikova",
"anna.novikova"
],
"manager_id": "p-1077",
"hired_at": "2024-02-01",
"assignments": [
{
"id": "a-1042-sales",
"unit_id": "u-sales",
"role_id": "r-cco",
"role_name": "Коммерческий директор",
"is_primary": true,
"is_head": false,
"started_at": "2024-02-01"
},
{
"id": "a-1042-retail",
"unit_id": "u-retail",
"role_id": "r-head-retail",
"role_name": "Руководитель розницы",
"is_primary": false,
"is_head": true
}
],
"extra": {
"grade": "M2",
"location": "Москва"
}
},
{
"id": "p-1077",
"name": "Михаил Петров",
"aliases": [
"Петров М."
],
"emails": [
"m.petrov@example.com"
],
"unit_ids": [
"u-retail"
]
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Оргструктура не подключена: нет источника подразделений и людей. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}norm_hour_costs_list
Стоимость часа сотрудников страницами: ставки «с — по — сумма в час». Это полная стоимость часа работы человека для компании, как её считает компания; окладов, премий и выплат в ответе нет, а часы встреч на ставку умножает платформа. В ответе — сотрудники, у которых хоть одна ставка пересекается с периодом from–to (дни включительно), с такими ставками целиком, без обрезки по границам периода. person_ids — только эти сотрудники, до 200; сотрудника без ставки в ответе нет, и это не сбой. basis: group — компания отдала среднюю ставку группы вместо личной, чтобы не раскрыть зарплату. Отдаётся только владельцу и администратору компании: остальным реализация отвечает unauthorized_scope. total — сколько сотрудников подошло под фильтр; для следующей страницы передайте page.next_cursor как cursor. Доменное состояние not_ready — стоимость часа у компании не настроена.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
from | да | string (date) | С какого дня нужны ставки, включительно. |
to | да | string (date) | По какой день нужны ставки, включительно. |
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
person_ids | нет | список string | Только эти сотрудники: id из norm_people_list. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
costs | да | список PersonHourCost | Сотрудники этой страницы с их ставками. |
total | да | integer | Сколько сотрудников со ставкой подошло под фильтр всего, на всех страницах. |
error | нет | DomainError | Почему данных нет: стоимость часа у компании не настроена. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "hour-costs:2026-07-08..2026-10-06",
"label": "Стоимость часа сотрудников"
}
],
"freshness": {
"as_of": "2026-10-06T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"total": 2,
"costs": [
{
"person_id": "p-1042",
"rates": [
{
"from": "2026-01-01",
"to": "2026-08-31",
"hour_cost": 1210.5,
"currency": "RUB",
"basis": "person"
},
{
"from": "2026-09-01",
"hour_cost": 1379.6,
"currency": "RUB",
"basis": "person"
}
]
},
{
"person_id": "p-1077",
"rates": [
{
"from": "2026-06-01",
"hour_cost": 1850,
"currency": "RUB",
"basis": "group"
}
]
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "hour-costs"
}
],
"freshness": {
"as_of": "2026-10-06T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Стоимость часа сотрудников у компании не настроена.",
"retryable": false
}
}
}norm_roles_list
Роли компании страницами: то, чем занимаются её люди. У компании с обычным кадровым учётом это справочник должностей, и у роли есть только идентификатор и название; компания, которая описывает роли смыслом, добавляет продукт роли, заказчика и подчинение. Идентификатор роли возвращается в назначениях сотрудника и принимается фильтром norm_people_list. unit_id отбирает роли, привязанные к подразделению; query — по части названия или другого названия без учёта регистра, total считается с учётом фильтров. Версий и текста описания в списке нет: карточку должности отдаёт norm_role_get. Пустой список — законный ответ компании, которая ролей не ведёт; not_ready означает, что оргструктура не подключена вовсе.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
query | нет | string | Найти должности по части названия: без учёта регистра, по name и aliases. |
unit_id | нет | string | Показать только роли этого подразделения. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
roles | да | список Role | Роли этой страницы; пустой список — компания ролей не ведёт. |
total | да | integer | Сколько ролей подошло под фильтр всего, на всех страницах. |
error | нет | DomainError | Почему данных нет: оргструктура не подключена. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles",
"label": "Роли"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"total": 3,
"roles": [
{
"id": "r-head-retail",
"name": "Руководитель розницы",
"aliases": [
"Директор розничной сети"
],
"product": "Выполненный план продаж розничной сети при сохранённой марже",
"customer": "Коммерческий директор",
"reports_to_role_id": "r-cco",
"unit_id": "u-retail",
"description": "Отвечает за выручку и маржу всех торговых точек."
},
{
"id": "r-cco",
"name": "Коммерческий директор"
},
{
"id": "r-recruiter",
"name": "Рекрутер",
"aliases": [
"Специалист по подбору"
],
"reports_to_role_id": "r-head-hiring",
"unit_id": "u-hiring",
"description": "Ищет кандидатов и доводит их до выхода на работу.",
"headcount_total": 4,
"headcount_filled": 3,
"grade": "7",
"grade_note": "оклад по штатному расписанию",
"substitute": "На время отсутствия замещает другой рекрутер отдела",
"kpis": [
{
"name": "Срок закрытия своих вакансий",
"target": "не больше 30 дней",
"category": "Effectiveness"
},
{
"name": "Доля кандидатов, прошедших испытательный срок",
"target": "от 80 %",
"category": "Quality"
},
{
"name": "Закрытые вакансии за квартал",
"target": "по плану отдела; от показателя зависит премия",
"category": "Effectiveness",
"id": "kpi-hires-q"
}
],
"updated_at": "2026-09-09T10:15:00+03:00"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Оргструктура не подключена: справочник ролей брать неоткуда. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}norm_role_get
Карточка одной должности по id из norm_roles_list: должность целиком, руководящая должность и прямо подчинённые — ссылками с названиями, перечень версий описания со статусами и датами. subordinates: [] — подчинённых нет; поля нет — компания подчинение не отдаёт. Текста описания в карточке нет: его отдаёт norm_role_description. Людей в должности ищите в norm_people_list с role_id — дата вступления в должность лежит в их назначении; название подразделения — в norm_org_units. Доменные состояния: unknown_id — должности с таким id нет; not_ready — оргструктура не подключена.
Доступ: чтение · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Какую должность открыть: id из norm_roles_list. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
role | да | Role | Должность целиком, со всеми полями, какие ведёт компания. |
descriptions | нет | список RoleDescriptionVersion | Версии описания должности, новые первыми. |
error | нет | DomainError | Почему карточки нет: должность не найдена или оргструктура не подключена. |
reports_to | нет | RoleRef | Кому подчиняется должность; нет — не подчиняется или компания не ведёт. |
subordinates | нет | список RoleRef | Прямо подчинённые должности; пустой список — подчинённых нет. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles/r-recruiter",
"label": "Должности"
}
],
"freshness": {
"as_of": "2026-10-05T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"data": {
"role": {
"id": "r-recruiter",
"name": "Рекрутер",
"aliases": [
"Специалист по подбору"
],
"reports_to_role_id": "r-head-hiring",
"unit_id": "u-hiring",
"description": "Ищет кандидатов и доводит их до выхода на работу.",
"headcount_total": 4,
"headcount_filled": 3,
"grade": "7",
"grade_note": "оклад по штатному расписанию",
"substitute": "На время отсутствия замещает другой рекрутер отдела",
"kpis": [
{
"name": "Срок закрытия своих вакансий",
"target": "не больше 30 дней",
"category": "Effectiveness"
},
{
"name": "Доля кандидатов, прошедших испытательный срок",
"target": "от 80 %",
"category": "Quality"
},
{
"name": "Закрытые вакансии за квартал",
"target": "по плану отдела; от показателя зависит премия",
"category": "Effectiveness",
"id": "kpi-hires-q"
}
],
"updated_at": "2026-09-09T10:15:00+03:00"
},
"reports_to": {
"id": "r-head-hiring",
"name": "Начальник отдела подбора и адаптации персонала"
},
"subordinates": [],
"descriptions": [
{
"version": 3,
"status": "active",
"approved_at": "2026-03-12",
"effective_from": "2026-03-16",
"file_name": "ДИ_Рекрутер_v3.docx",
"file_url": "https://docs.example.com/hr/positions/recruiter-v3.docx"
},
{
"version": 2,
"status": "superseded",
"effective_from": "2025-02-01",
"effective_to": "2026-03-15",
"file_name": "ДИ_Рекрутер_v2.docx"
},
{
"version": 1,
"status": "superseded",
"effective_from": "2024-01-10",
"effective_to": "2025-01-31"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles"
}
],
"freshness": {
"as_of": "2026-10-05T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"error": {
"code": "unknown_id",
"message": "Должности r-unknown нет в справочнике: возьмите id из norm_roles_list.",
"retryable": false
}
}
}norm_role_description
Текст описания должности в Markdown окнами. Без version — действующая версия, а если действующей нет — самая новая по номеру; version — номер из descriptions карточки norm_role_get. max_chars — размер окна в символах (умолчание 12000, максимум 24000; те же значения, что у окна расшифровки, раздел limits слепка). Для следующего окна передайте page.next_cursor как cursor; нет курсора — текст дочитан. Повторный вызов с тем же курсором вернёт тот же текст, склейка окон равна полному тексту. Доменные состояния: unknown_id — нет должности или версии с таким номером; no_data — у должности нет ни одной версии описания; not_ready — оргструктура не подключена.
Доступ: чтение · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
role_id | да | string | Чьё описание читать: id должности из norm_roles_list. |
cursor | нет | string | Откуда продолжить чтение: next_cursor из прошлого ответа. Без него — с начала. |
max_chars | нет | integer | Сколько символов прислать за раз. |
version | нет | integer | Какую версию читать; без номера — действующую. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
role_id | да | string | Чьё это описание: тот же id, что передан во входе. |
text | да | string | Markdown этого окна. |
total_chars | да | integer | Длина всего текста: по ней видно, сколько окон впереди. |
version | да | integer | Какой версии этот текст: важно, когда номер не передавали. |
error | нет | DomainError | Почему текста нет: должность или версия не найдены, описания нет, оргструктура не подключена. |
file_name | нет | string | Имя файла оригинала, если версия ведётся файлом. |
file_url | нет | string (uri) | Ссылка на оригинал в системе компании; может требовать там входа. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles/r-recruiter/descriptions/3",
"label": "Должности"
}
],
"freshness": {
"as_of": "2026-10-05T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"page": {
"has_more": true,
"next_cursor": "v3:240"
},
"data": {
"role_id": "r-recruiter",
"version": 3,
"total_chars": 5180,
"text": "# Рекрутер\n\n## Зачем эта должность\n\nРекрутер ищет кандидатов на открытые вакансии отдела и доводит их до выхода на работу.\n\n## Обязанности\n\n- Открывает вакансию по заявке руководителя и согласует профиль кандидата.\n- Ведёт воронку кандидатов: поиск, скрининг, первичное интервью.\n",
"file_name": "ДИ_Рекрутер_v3.docx",
"file_url": "https://docs.example.com/hr/positions/recruiter-v3.docx"
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:roles/r-cco"
}
],
"freshness": {
"as_of": "2026-10-05T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "no_data",
"message": "У должности «Коммерческий директор» описания нет: компания его не завела.",
"retryable": false
}
}
}norm_person_get
Карточка одного сотрудника целиком. Передайте id или email — хотя бы один обязателен, без обоих вызов отклоняется как invalid_input. Передали оба — карточку определяет id, почта игнорируется. Почта сравнивается без учёта регистра. Уволенный отдаётся всегда: вы спросили конкретного человека. Доменные состояния: unknown_user — ни идентификатор, ни почта не подошли; record_rejected — на эту почту в компании заведено больше одной карточки, и выбрать за человека нельзя; not_ready — оргструктура не подключена.
Доступ: чтение · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
email | нет | string | Кого открыть: почта сотрудника, в любом регистре. |
id | нет | string | Кого открыть: id сотрудника. Если передан, почта не нужна. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
person | да | Person | Карточка сотрудника целиком, в том числе уволенного. |
error | нет | DomainError | Почему карточки нет: человек не найден или по почте их несколько. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people/p-1042",
"label": "Карточка сотрудника"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 86400,
"stale": false
},
"data": {
"person": {
"id": "p-1042",
"name": "Анна Новикова",
"aliases": [
"Новикова А.",
"a.novikova"
],
"emails": [
"a.novikova@example.com",
"79001234567@example.com"
],
"unit_ids": [
"u-sales",
"u-retail"
],
"phone": "+7 900 123-45-67",
"handles": [
"@a_novikova",
"anna.novikova"
],
"manager_id": "p-1077",
"hired_at": "2024-02-01",
"assignments": [
{
"id": "a-1042-sales",
"unit_id": "u-sales",
"role_id": "r-cco",
"role_name": "Коммерческий директор",
"is_primary": true,
"is_head": false,
"started_at": "2024-02-01"
},
{
"id": "a-1042-retail",
"unit_id": "u-retail",
"role_id": "r-head-retail",
"role_name": "Руководитель розницы",
"is_primary": false,
"is_head": true
}
],
"extra": {
"grade": "M2",
"location": "Москва"
}
}
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people"
}
],
"freshness": {
"as_of": "2026-09-21T03:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"error": {
"code": "unknown_user",
"message": "Ни идентификатор, ни почта не подошли ни к одному сотруднику. Проверьте значение: идентификаторы приходят из norm_people_list.",
"retryable": false
}
}
}norm_person_upsert
Создать или обновить карточку сотрудника. Ключ — id или email, правило то же, что у norm_person_get. По ключу id карточка только обновляется: нет такой — unknown_user. По ключу email карточка обновляется или создаётся; для создания обязательно имя, иначе ответ несёт record_rejected и поле name среди непринятых. Что делают переданные поля: поля нет во входе — оно не трогается; переданный массив заменяет прежний набор целиком; значение null у одиночного поля очищает его; внутри extra то же правило по каждому ключу. Непринятое поле — не отказ: остальное записано, а поле названо в rejected_fields с причиной. Доменные состояния: not_ready — запись профилей у компании не настроена; unknown_user — карточки по ключу id нет; record_rejected — ничего не записано (на почту заведено больше одной карточки, при создании нет имени, хранилище отвергло карточку целиком); unknown_field — компания не ведёт поле ядра, которое вы пытаетесь записать. Реализация вправе разрешить запись только привилегированным ролям и отвечать unauthorized_scope.
Доступ: запись · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
aliases | нет | список string | Другие написания имени; заменяют прежние целиком. |
assignments | нет | список Assignment | Где и в какой роли человек работает; заменяют прежние целиком. |
email | нет | string | Чью карточку обновить или создать: почта сотрудника. |
emails | нет | список string | Все почты человека; заменяют прежние целиком. |
extra | нет | object | Поля, которые компания ведёт сверх контракта. |
handles | нет | список string | Логины в мессенджерах и других системах; заменяют прежние целиком. |
hired_at | нет | string | null (date) | Дата прихода в компанию; null — убрать. |
id | нет | string | Чью карточку обновить: id сотрудника. По id карточка только обновляется. |
manager_id | нет | string | null | Руководитель: id сотрудника; null — убрать. |
name | нет | string | Имя; без него новую карточку не создать. |
phone | нет | string | null | Телефон; null — убрать. |
terminated_at | нет | string | null (date) | Дата ухода из компании; null — убрать. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
created | да | boolean | Создана ли карточка сейчас; false — обновлена существующая. |
id | да | string | id записанной карточки: пригодится, если её только что создали. |
rejected_fields | да | список RejectedField | Какие поля не записались и почему; остальное записано. |
error | нет | DomainError | Почему ничего не записано. |
url | нет | string (uri) | Ссылка на карточку в системе компании. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people/p-1042",
"label": "Карточка сотрудника"
}
],
"freshness": {
"as_of": "2026-09-21T09:31:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"id": "p-1042",
"created": false,
"url": "https://people.example.com/p-1042",
"rejected_fields": [
{
"key": "extra.birthday",
"reason": "поле не ведётся в карточке сотрудника"
}
]
}
}Пример: случай «created»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people/p-1103",
"label": "Карточка сотрудника"
}
],
"freshness": {
"as_of": "2026-09-21T09:31:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"id": "p-1103",
"created": true,
"url": "https://people.example.com/p-1103",
"rejected_fields": []
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "org:people"
}
],
"freshness": {
"as_of": "2026-09-21T09:31:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"error": {
"code": "unknown_user",
"message": "Карточки с таким идентификатором нет. По ключу id карточка только обновляется; чтобы завести новую, передайте email и имя.",
"retryable": false
}
}
}Объекты семейства
Объекты, из которых состоят аргументы и ответы инструментов этого семейства.
OrgUnit
Подразделение. Идентификатор, название и родитель. У корневого подразделения родитель — null. Принадлежность верхним уровням выводится по цепочке родителей. Необязательные kind, code и sort_order — вид узла, код в учётной системе компании и порядок среди соседей.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Чтобы сослаться на подразделение: в фильтрах, назначениях, протоколе. |
name | да | string | Название подразделения. |
parent_id | да | string | null | В какое подразделение входит это; null — верхний уровень. |
code | нет | string | Код подразделения в учётной системе компании. |
kind | нет | OrgUnitKind | Уровень подразделения: компания, дивизион, отдел, команда, группа. |
sort_order | нет | integer | В каком порядке показывать подразделение среди соседей. |
OrgUnitKind
Вид подразделения. Уровень узла в дереве: юридическое лицо, дивизион, отдел, команда, группа. Вид описателен: вложенность задаётся только полем parent_id.
Значения: company, division, department, team, group.
Person
Сотрудник. Идентификатор для полей протокола с людьми (participant_ids, organizer_id), имя, другие написания имени, все написания почты в нижнем регистре и прямое членство в подразделениях. handles — опознавательные строки вне почты (логины в мессенджерах): сопоставляйте их так же, как почту. Когда отданы назначения, unit_ids равно множеству их подразделений. Руководителя ищите так: явный manager_id; если его нет — человек с признаком is_head в основном подразделении; если и его нет — по цепочке reports_to_role_id роли основного назначения. extra — поля, которые ведёт сама компания: их состав контракт не описывает.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
aliases | да | список string | Другие написания имени: помогают узнать человека в расшифровке и в конференции. |
emails | да | список string | Все почты человека в нижнем регистре: участника встречи находят по любой из них. |
id | да | string | Чтобы указать человека в протоколе (participant_ids, organizer_id) и в уведомлении. |
name | да | string | Имя человека. |
unit_ids | да | список string | В каких подразделениях человек числится напрямую. |
assignments | нет | список Assignment | Где и в какой роли человек работает. |
extra | нет | object | Поля, которые компания ведёт сверх контракта. |
handles | нет | список string | Логины в мессенджерах и других системах: по ним человека узнают так же, как по почте. |
hired_at | нет | string (date) | Когда человек пришёл в компанию. |
manager_id | нет | string | Кто руководитель человека: id сотрудника. |
phone | нет | string | Телефон человека. |
terminated_at | нет | string (date) | Когда человек ушёл или уйдёт из компании. |
Assignment
Назначение. Где человек числится и в какой роли. is_primary — основное место работы; is_head — человек руководит этим подразделением. Роль приходит идентификатором, а у компании без справочника должностей — только названием в role_name; назначение вовсе без роли означает «числится в подразделении».
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
is_head | да | boolean | Руководит ли человек этим подразделением. |
is_primary | да | boolean | Основное ли это место работы человека. |
unit_id | да | string | В каком подразделении человек числится. |
ended_at | нет | string (date) | По какой день действовало назначение. |
id | нет | string | Номер назначения в системе компании. |
role_id | нет | string | В какой роли человек здесь работает: id из norm_roles_list. |
role_name | нет | string | Название роли, если справочника ролей у компании нет. |
started_at | нет | string (date) | С какого дня действует назначение. |
PersonHourCost
Стоимость часа сотрудника. Сотрудник и его ставки по периодам. Ставки одного человека не пересекаются: контракт это правило описывает, но не проверяет.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
person_id | да | string | Чья ставка: id сотрудника из norm_people_list. |
rates | да | список HourCostRate | Ставки сотрудника, пересекающиеся с периодом, от ранних к поздним. |
HourCostRate
Ставка часа. Стоимость часа сотрудника за период «с — по»: сумма, валюта и основание. Окладов, премий и выплат здесь нет: как получить ставку, решает компания.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
basis | да | HourCostBasis | Личная это ставка или средняя по группе: экран показывает разницу. |
currency | да | string | Валюта ставки, трёхбуквенный код ISO 4217: RUB. |
from | да | string (date) | С какого дня действует ставка, включительно: встречи этого дня и позже считаются по ней. |
hour_cost | да | number | Полная стоимость часа работы сотрудника для компании, как её считает компания. |
to | нет | string (date) | По какой день ставка действовала, включительно; нет — действует и сейчас. |
HourCostBasis
Основание ставки. person — ставка самого сотрудника; group — средняя ставка группы: компания сгладила ставки, чтобы по деньгам нельзя было вычислить чью-то зарплату.
Значения: person, group.
Role
Роль. Чем человек занимается в компании. В обычном кадровом учёте роль — это должность, и у неё есть только идентификатор и название. Компания, которая описывает роли смыслом, добавляет product (что роль производит), customer (главный заказчик результата) и reports_to_role_id (кому роль подчиняется). Цикл в подчинении контракт не запрещает и не проверяет: обходя цепочку, защищайтесь от него сами. Компания со штатным расписанием добавляет headcount_total и headcount_filled (ставки по расписанию и занятые; занятых бывает больше ставок — совместительство, переходный период), grade и grade_note; компания, оценивающая работу, — kpis.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Чтобы найти людей в этой роли: передайте в role_id списка сотрудников. |
name | да | string | Название роли или должности. |
aliases | нет | список string | Другие названия той же роли. |
customer | нет | string | Кому нужен результат роли, если компания это описывает. |
description | нет | string | Пояснение компании, чем занимается роль. |
grade | нет | string | Грейд должности в сетке компании, как его пишет компания: «7», «M2». |
grade_note | нет | string | Пояснение к грейду: «оклад по штатному расписанию». |
headcount_filled | нет | integer | Сколько ставок занято людьми; может быть больше числа ставок. |
headcount_total | нет | integer | Сколько ставок у должности по штатному расписанию: «занято N из M». |
kpis | нет | список RoleKpi | По каким показателям оценивают работу в должности. |
product | нет | string | Что производит роль, если компания это описывает. |
reports_to_role_id | нет | string | Какой роли подчиняется эта: так ищут руководителя. |
substitute | нет | string | Кто замещает на время отсутствия, словами. |
unit_id | нет | string | К какому подразделению привязана роль. |
updated_at | нет | string (date-time) | Когда должность последний раз менялась в системе компании. |
RoleKpi
KPI должности. Показатель, по которому оценивают работу в должности: название и, если компания его ведёт, целевое значение словами. Категорию и идентификатор компания задаёт сама; контракт их словарь не описывает.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
name | да | string | Что измеряют: показать KPI человеку и агенту. |
category | нет | string | Категория показателя в компании: «Effectiveness», «Quality». |
id | нет | string | Идентификатор показателя в системе компании: сослаться на него. |
target | нет | string | Целевое значение словами: «не больше 30 дней», «от 80 %». |
RoleDescriptionVersion
Версия описания должности. Номер, статус, даты утверждения и действия, файл оригинала. Текста здесь нет: его отдаёт norm_role_description окнами. Действующая версия у должности одна; контракт это правило описывает, но не проверяет — при двух действующих показывайте ту, что начала действовать позже. Описание, которое ведётся прямо в системе компании, файла не имеет.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
status | да | RoleDescriptionStatus | Действует ли версия. |
version | да | integer | Номер версии: по нему запрашивают её текст в norm_role_description. |
approved_at | нет | string (date) | Когда версия утверждена. |
effective_from | нет | string (date) | С какого дня версия действует. |
effective_to | нет | string (date) | По какой день версия действовала; нет — действует сейчас или ещё не начиналась. |
file_name | нет | string | Имя файла оригинала, как его видит человек: «ДИ_Рекрутер_v3.docx». |
file_url | нет | string (uri) | Ссылка на оригинал в системе компании; может требовать там входа. |
RoleDescriptionStatus
Статус версии описания. draft — на согласовании; active — действует; superseded — заменена новой версией. Утверждённая версия с будущей датой начала ещё не действует: её статус отличается от active, а дата видна в effective_from.
Значения: draft, active, superseded.
RoleRef
Ссылка на должность. Идентификатор и название другой должности: руководящей или подчинённой.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Открыть эту должность: id для norm_role_get. |
name | да | string | Название должности: показать без листания справочника. |
RejectedField
Непринятое поле. Поле, которое запись не приняла, и причина. Операция при этом выполнена.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
key | да | string | Какое поле не записалось. |
reason | да | string | Почему поле не записалось. |