В аудит-логе Яндекс 360 ровно 26 типов событий. Ни одно из них не про сотрудника

Я полез в документацию Яндекс 360 API за одним — именем события, на которое можно подписаться, чтобы интеграция узнавала о приёме и увольнении людей. Вышел оттуда с перечнем из 26 значений eventType, где двенадцать про письма, четырнадцать про файлы, и ни одного про человека. Дата сверки — 20 августа 2026 года, все ссылки ниже открываются в один клик, спорить со мной удобно.

Я основал компанию +Альянс и руковожу ею; интеграции вокруг облачных офисов — то, чем моя команда занимается каждый день. Никаких инструментов — ни наших, ни чужих — в тексте не будет: разговор про публичную документацию платформы и про то, что из неё следует проектировщику.

Сначала я искал не там, где надо

Логика была простая. Раз есть REST API управления сотрудниками, значит где-то рядом должен лежать раздел про подписку: URL приёмника, секрет, формат доставки. Так устроено у половины корпоративных платформ, и мозг ищет знакомую форму.

Раздел «Доступные разделы» перечисляет 17 сервисов: Organizations, Group, Department, User, ExternalContact, MailUserSettings, MailAntispamIpAllowlist, Routing, DomainPolicies, Mailbox, Domain, DomainDNS, Domain2FA, DomainSessions, DomainPasswords, AuditLog, ServiceApplications.

Организации, группы, подразделения, сотрудники, внешние контакты, почтовые настройки, антиспам, маршрутизация писем, политики домена, ящики, домены, DNS, двухфакторка, сессии, пароли, аудит, сервисные приложения. Всё.

Вебхуков нет. Push-уведомлений нет. Подписки на события нет. Раздела про синхронизацию данных — тоже нет. Я проверял эту страницу дважды, с разницей в несколько дней, и второй раз специально целился в пять слов: лимиты, квоты, вебхуки, подписки, синхронизация. Ноль из пяти.

Оговорюсь про жанр: это не баг-репорт и не претензия к вендору. Документация может отставать от реализации, недокументированный механизм может существовать — но проектировать интеграцию на том, чего нет в документации, я не берусь и вам не советую.

Аудит-лог выглядит как выход. Он им не является

Первая мысль, когда вебхуков не нашлось: ну хорошо, есть же AuditLogService — «сервис для получения истории событий в организации». Формулировка щедрая. История событий в организации — звучит так, будто там всё.

Внутри сервиса два метода: аудит-лог Почты и аудит-лог Диска. У каждого — закрытый перечень допустимых значений eventType.

Почта, 12 значений: mailbox_send, message_receive, message_seen, message_unseen, message_forward, message_purge, message_trash, message_spam, message_unspam, message_move, message_copy, message_answer.

Диск, 14 значений: fs-copy, fs-mkdir, fs-move, fs-set-public, fs-store, fs-trash-append, fs-trash-drop, fs-trash-drop-all, fs-rm, share-activate-invite, share-change-rights, share-change-invite-rights, share-create-group, share-invite-user.

Отправил, принял, прочитал, переслал, пометил спамом, переложил в папку. Скопировал файл, создал каталог, выкинул в корзину, выдал права, пригласил к доступу. Двадцать шесть штук, и все они — про содержимое, а не про людей.

Отдельно про два значения, на которых я сам споткнулся. share-invite-user и share-create-group читаются как «пригласили пользователя» и «создали группу» — и мимо них легко пройти с чувством, что кадровое событие всё-таки нашлось. Оба про Диск: приглашение к общему доступу к файлу и создание группы доступа. Сотрудники и группы оргструктуры живут в UserService и GroupService, и в eventType аудит-лога эти сущности не отражены никак.

Проверку я делал два раза, потому что первым в ошибочном мнении был я сам: я был уверен, что аудит-лог покрывает всё, включая приём и увольнение. Второй прогон был уже не «посмотреть, есть ли раздел», а «выписать полный список значений и предъявить самому себе». Список выше — результат этой перепроверки.

Ни создания пользователя. Ни увольнения. Ни блокировки. Ни перевода в подразделение. Ни переименования отдела.

Значит, поллинг. И вот что для него есть

Раз событий нет, узнать об изменении можно только одним документированным способом — спросить самому. Смотрим, чем метод UserService_List для этого располагает.

Пагинация: page — «Номер страницы ответа. Значение по умолчанию — 1»; perPage — «Количество сотрудников на одной странице ответа. Значение по умолчанию — 10. Максимальное значение — 1000». Курсора нет, только номер страницы. На мой взгляд, для организации, где список сотрудников меняется прямо во время обхода, номерная пагинация опасна тем, что страницы разъезжаются под ногами: между запросом второй и третьей страницы порядок записей может смениться.

В ответе есть поле updatedAt — «Дата и время изменения сотрудника», тип string<date-time>, пример 2025-01-01T00:00:00Z.

Вот на этом месте хочется написать «Яндекс предлагает опрашивать List и сравнивать updatedAt». Не напишу. Поле в ответе есть — это факт документации. Текста, который рекомендовал бы такой паттерн, в документации нет: ни в концепциях, ни на странице метода. Я искал профильные материалы и в справке Яндекса — по вебхукам, событиям директории, интеграции HR-систем, синхронизации сотрудников через API. Профильного раздела не нашлось.

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

Заодно выяснилось, что лимитов тоже нет

Естественный следующий вопрос человека, который собрался опрашивать API по расписанию: а сколько можно?

Адрес yandex.ru/dev/api360/doc/ru/concepts/limits отдаёт HTTP 404 Not Found — проверено 20 августа 2026 года. В оглавлении концепций yandex.ru/dev/api360/doc/concepts/ раздела о лимитах и квотах тоже нет.

Формулирую аккуратно, потому что разница существенная: это не «я не нашёл цифры», это «страницы с цифрами не существует по прямому URL и она не упомянута в оглавлении». Числа запросов в секунду, квоты на организацию, поведение при превышении — ничего этого публично нет. Документированных цифр, на которые можно было бы опереться при выборе частоты опроса, попросту не существует: страница отдаёт 404.

Практический вывод из отсутствия цифр ровно один, и он унылый: свою частоту опроса вы подбираете эмпирически и на свой риск, а не по документу.

isDismissed можно прочитать, но нельзя записать

Есть ещё одна деталь, которая всплывает уже на этапе реализации.

В UserService_Update изменяемое поле статуса аккаунта — isEnabled (true — активен, false — заблокирован). Поля isDismissed («Статус сотрудника: true — уволенный, false — действующий») в теле запроса нет вообще. Оно живёт только в ответе, как read-only.

То есть отслеживать статус увольнения через API вы можете, а выставлять его — нет. Максимум, что делает интеграция со стороны API, — блокирует учётную запись. Если ваша HR-система считает себя мастер-системой кадровых статусов и рассчитывает прописать «уволен» в директорию, эту часть схемы придётся переделать до начала кодирования, а не после.

И на всякий случай про Create: 409 вам никто не обещал

Тем, кто строит провижининг, полезно знать заранее, чем платформа отвечает на попытку создать пользователя с уже занятым логином.

UserService_Create документирует пять кодов ответа: 400 Bad Request («Некорректный запрос»), 401 Unauthorized («Пользователь не авторизован»), 403 Forbidden («У пользователя или приложения нет прав на доступ к ресурсу»), 404 Not Found («Запрашиваемый ресурс не найден»), 500 Internal Server Error («Внутренняя ошибка сервиса»).

409 Conflict в этом перечне отсутствует. Описание четырёхсотки общее и не раскрывает, какие валидации под ней скрываются — проверка уникальности nickname в том числе.

Значит, обработчик конфликта уникальности вы пишете не по документации, а по тому, что увидели на своём тенанте. Мой совет здесь скучный: снимите поведение экспериментом на тестовой организации, зафиксируйте код и тело ответа в комментарии к коду вместе с датой — и перепроверьте, когда что-нибудь сломается.

Чем это оборачивается в проектировании

Дальше — рассуждение, а не цитаты. Помечаю явно, потому что документация про последствия молчит, а реальных инцидентов, которые я мог бы предъявить с цифрами, у меня нет.

Что меняется в архитектуре, когда подписки не существует:

• Реакция интеграции отстаёт от события на интервал опроса. Не «на N секунд» — на столько, на сколько вы сами настроите, и в худшем случае почти на полный интервал.

• Появляется состояние, которого при подписке не было бы: снимок прошлого опроса надо где-то хранить и с чем-то сравнивать. Хранилище снимков, диффер, расписание, дедупликация — всё это ваш код и ваш эксплуатационный груз.

• Промежуточные состояния между опросами не видны в принципе. Создали человека и через минуту перевели в другой отдел — при получасовом интервале вы увидите сразу результат, а не два шага. Иногда это безразлично, иногда ломает бизнес-логику, которая рассчитывала на оба события.

• Частота опроса упирается в стену, у которой нет обозначенной высоты: страница yandex.ru/dev/api360/doc/ru/concepts/limits отдаёт 404.

Ни один из этих пунктов не превращает поллинг в плохое решение. Он единственный документированный, и спорить тут не с чем. Просто закладывайте его в оценку трудоёмкости с самого начала, а не после того, как неделю искали вебхуки, которых нет.

Как проверить, что я не наврал и не устарел

Документация меняется без анонсов, а моя сверка — от 20 августа 2026 года. Пять минут вашего времени:

1. Откройте yandex.ru/dev/api360/doc/concepts/ и поищите на странице слова «вебхук», «webhook», «подписка», «события».

2. Откройте оба метода AuditLogService и разверните список допустимых значений eventType. Считать не обязательно — достаточно найти хоть одно, где фигурирует пользователь как сотрудник, а не как участник шаринга.

3. Дёрните yandex.ru/dev/api360/doc/ru/concepts/limits и посмотрите на код ответа.

4. Откройте UserService_Update и поищите isDismissed в теле запроса, а не в ответе.

Если хоть один из четырёх пунктов у вас сегодня даёт другой результат — это отличная новость, и она куда полезнее моей статьи. Приносите ссылку в комментарии: я перепишу свою часть схемы раньше, чем вы допишете реплику.