Тема
Календарь
Семейство calendar.
norm_calendar_events_list
События календарей сотрудников за дни from–to: что запланировано, кто приглашён, что отменили. emails — от 1 до 200 почт сотрудников из norm_people_list, по одной на человека, регистр не важен. from и to — дни включительно по поясу календаря, за один день from = to; в ответ попадает событие, которое хотя бы частью приходится на эти дни, а момент end_at в событие не входит. Отметки календаря о месте работы, дни рождения и подобные событиями не считаются. calendars — строка на каждую почту: ok — календарь прочитан, нет событий — значит, их нет; unavailable — календаря нет, доступа к нему нет или он вне круга видимости вызывающего, причины не различаются. range — за какие дни у сервера вообще есть события: за его границами «событий нет» значит «данных нет». Одна встреча в календарях нескольких людей приходит строкой на каждый календарь с одним id: считайте её по id один раз. Отменённые события приходят со status: cancelled. У личного события (visibility: private) только время, состояние и вид. Связи с записанными встречами в ответе нет: сопоставляйте по conference, его platform и conference_id пишутся так же, как platform и platform_meeting_id у norm_meeting_get. Почты в ответе — в нижнем регистре. Порядок — по времени начала; на странице не больше limit событий, и она укладывается в предел размера ответа; total — сколько событий подошло всего. Для следующей страницы передайте page.next_cursor как cursor с теми же emails, from и to. Ответ — по правам вызывающего; реализация вправе отказать unauthorized_scope тому, кому календари сотрудников не открыты. Доменное состояние not_ready — календари компании не подключены.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
emails | да | список string | Чьи календари читать: почты сотрудников из norm_people_list, по одной на человека, в любом регистре. |
from | да | string (date) | С какого дня нужны события, включительно, по поясу календаря. |
to | да | string (date) | По какой день нужны события, включительно; за один день передайте тот же день, что во from. |
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
calendars | да | список Calendar | По строке на каждую запрошенную почту: прочитан ли её календарь. |
events | да | список CalendarEvent | События этой страницы по времени начала, от ранних к поздним. |
range | да | DateRange | За какие дни у сервера вообще есть события календарей: за этими границами «событий нет» значит «данных нет». |
total | да | integer | Сколько событий подошло под запрос всего, на всех страницах. |
error | нет | DomainError | Почему данных нет: календари компании не подключены. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "calendar:2026-10-13..2026-10-13",
"label": "Календари на 13 октября"
}
],
"freshness": {
"as_of": "2026-10-13T17:45:00.000Z",
"ttl_sec": 3600,
"stale": false
},
"page": {
"has_more": true,
"next_cursor": "eyJvIjo1fQ"
},
"data": {
"range": {
"from": "2026-09-08",
"to": "2026-10-27"
},
"calendars": [
{
"email": "a.novikova@example.com",
"status": "ok"
},
{
"email": "m.petrov@example.com",
"status": "ok"
},
{
"email": "s.ilin@example.com",
"status": "unavailable"
}
],
"total": 7,
"events": [
{
"id": "5r4e3w2q8a",
"calendar_email": "m.petrov@example.com",
"status": "confirmed",
"start_at": "2026-10-13T00:00:00+03:00",
"end_at": "2026-10-14T00:00:00+03:00",
"all_day": true,
"visibility": "default",
"kind": "out_of_office",
"title": "Отпуск"
},
{
"id": "7kq2v0m3b9d8e6f5g4h2j0k_20261013T060000Z",
"calendar_email": "a.novikova@example.com",
"status": "confirmed",
"start_at": "2026-10-13T09:00:00+03:00",
"end_at": "2026-10-13T09:30:00+03:00",
"all_day": false,
"visibility": "default",
"kind": "event",
"title": "Планёрка отдела продаж",
"organizer_email": "a.novikova@example.com",
"attendees": [
{
"email": "a.novikova@example.com",
"name": "Анна Новикова",
"response": "accepted"
},
{
"email": "m.petrov@example.com",
"name": "Михаил Петров",
"response": "declined"
},
{
"email": "s.ilin@example.com",
"name": "Сергей Ильин",
"response": "needs_action",
"optional": true
}
],
"agenda": "1. Воронка за неделю. 2. Правило квалификации лида. 3. Разное.",
"recurring_series_id": "7kq2v0m3b9d8e6f5g4h2j0k",
"conference": {
"platform": "conference",
"conference_id": "884 2210 9931",
"url": "https://meetings.example.com/j/88422109931"
}
},
{
"id": "7kq2v0m3b9d8e6f5g4h2j0k_20261013T060000Z",
"calendar_email": "m.petrov@example.com",
"status": "confirmed",
"start_at": "2026-10-13T09:00:00+03:00",
"end_at": "2026-10-13T09:30:00+03:00",
"all_day": false,
"visibility": "default",
"kind": "event",
"title": "Планёрка отдела продаж",
"organizer_email": "a.novikova@example.com",
"attendees": [
{
"email": "a.novikova@example.com",
"name": "Анна Новикова",
"response": "accepted"
},
{
"email": "m.petrov@example.com",
"name": "Михаил Петров",
"response": "declined"
},
{
"email": "s.ilin@example.com",
"name": "Сергей Ильин",
"response": "needs_action",
"optional": true
}
],
"agenda": "1. Воронка за неделю. 2. Правило квалификации лида. 3. Разное.",
"recurring_series_id": "7kq2v0m3b9d8e6f5g4h2j0k",
"conference": {
"platform": "conference",
"conference_id": "884 2210 9931",
"url": "https://meetings.example.com/j/88422109931"
}
},
{
"id": "3t9u8v7w6x5y4z",
"calendar_email": "a.novikova@example.com",
"status": "cancelled",
"start_at": "2026-10-13T14:00:00+03:00",
"end_at": "2026-10-13T15:00:00+03:00",
"all_day": false,
"visibility": "default",
"title": "Разбор рекламации",
"organizer_email": "a.novikova@example.com",
"attendees": [
{
"email": "a.novikova@example.com",
"name": "Анна Новикова",
"response": "accepted"
},
{
"email": "k.orlova@example.com",
"name": "Ксения Орлова",
"response": "tentative"
}
]
},
{
"id": "9p8o7i6u5y4t",
"calendar_email": "a.novikova@example.com",
"status": "confirmed",
"start_at": "2026-10-13T16:00:00+03:00",
"end_at": "2026-10-13T17:00:00+03:00",
"all_day": false,
"visibility": "private"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "calendar"
}
],
"freshness": {
"as_of": "2026-10-13T17:45:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Календари компании не подключены: источника событий нет. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}Объекты семейства
Объекты, из которых состоят аргументы и ответы инструментов этого семейства.
Calendar
Календарь из запроса. Почта из запроса и прочитан ли её календарь. Строка есть на каждую запрошенную почту и повторяется на каждой странице ответа.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
email | да | string | Чей это календарь: почта из запроса в нижнем регистре. |
status | да | CalendarStatus | Прочитан ли календарь: unavailable — его событий в ответе нет. |
CalendarStatus
Состояние календаря. ok — календарь прочитан: его события в ответе, и если их нет, значит, их нет; unavailable — календарь не прочитан: его нет, к нему нет доступа или он вне круга видимости вызывающего. Причины не различаются, чтобы перебором почт нельзя было узнать о чужих календарях.
Значения: ok, unavailable.
CalendarEvent
Событие календаря. Событие в календаре одного сотрудника: когда, состоится ли, кто приглашён, о чём и где пройдёт. Одна встреча в календарях нескольких людей — отдельное событие в каждом календаре с одним id; пара calendar_email и id в ответе единственна. У личного события (visibility: private) только id, calendar_email, status, start_at, end_at, all_day, visibility и kind.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
all_day | да | boolean | Событие занимает целые дни, без времени начала и конца. |
calendar_email | да | string | Чей это календарь: почта из запроса в нижнем регистре. |
end_at | да | string (date-time) | Когда событие кончается, в поясе календаря; сам этот момент в событие не входит: у события на весь день это начало дня после последнего. |
id | да | string | Идентификатор события: у одной встречи в календарях разных людей он один, по нему встречу считают один раз. |
start_at | да | string (date-time) | Когда событие начинается, в поясе календаря; у события на весь день — начало первого дня. |
status | да | CalendarEventStatus | Состоится ли событие: отменённое тоже приходит, чтобы было видно, что встречу отменили. |
visibility | да | CalendarEventVisibility | Открыты ли подробности: у личного события есть только время, состояние и вид. |
agenda | нет | string | Повестка: описание события без ссылок и реквизитов подключения, до 2000 знаков; длиннее — обрезана. |
attendees | нет | список CalendarAttendee | Кто приглашён и что ответил, до 50 человек; владелец календаря, если он приглашён, в списке есть всегда. |
attendees_omitted | нет | boolean | true — приглашённых больше 50 и перечислены не все: отсутствие человека в списке ничего не значит. |
conference | нет | CalendarConference | Где событие пройдёт онлайн: по этому полю его сопоставляют с записанной встречей. |
kind | нет | CalendarEventKind | Вид события: встреча, отсутствие или время без встреч; нет поля — обычное событие. Отметок других видов в ответе нет. |
organizer_email | нет | string | Почта организатора: по ней находят организатора среди сотрудников. |
recurring_series_id | нет | string | Серия повторяющейся встречи: у всех её экземпляров один идентификатор, по нему узнают регулярную встречу. |
title | нет | string | Название события: по нему узнают встречу, в том числе регулярную. |
CalendarAttendee
Приглашённый. Человек из приглашения на событие: почта, имя, ответ и признак необязательного участника. Переговорные и другие ресурсы приглашёнными не считаются и в список не входят.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
email | да | string | Почта приглашённого в нижнем регистре: по ней его находят среди сотрудников. |
response | да | CalendarAttendeeResponse | Что приглашённый ответил на приглашение. |
name | нет | string | Как приглашённый назван в календаре. |
optional | нет | boolean | Приглашён необязательным участником: так его отметил организатор. |
CalendarAttendeeResponse
Ответ на приглашение. accepted — придёт; declined — отказался; tentative — может быть; needs_action — ещё не ответил.
Значения: accepted, declined, tentative, needs_action.
CalendarConference
Онлайн-встреча события. Встреча в сервисе конференций, привязанная к событию: сервис, номер встречи в нём и ссылка без пароля. Пара platform и conference_id пишется так же, как platform и platform_meeting_id у norm_meeting_get: по ней платформа сама сопоставляет событие с записанной встречей.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
platform | да | string | Сервис конференций тем же словом, что platform у norm_meeting_get: по нему событие сопоставляют с записанной встречей. |
conference_id | нет | string | Номер встречи в сервисе конференций, написанный так же, как platform_meeting_id у norm_meeting_get. |
url | нет | string (uri) | Ссылка на встречу для человека, без пароля и кода доступа. |
CalendarEventKind
Вид события. event — обычное событие; out_of_office — человек отсутствует; focus_time — время, которое человек закрыл для работы без встреч. Отметки календаря других видов — где человек работает, дни рождения и подобные — событиями не считаются, и сервер их не отдаёт.
Значения: event, out_of_office, focus_time.
CalendarEventStatus
Состояние события. confirmed — событие состоится; tentative — под вопросом; cancelled — отменено: событие осталось в ответе, чтобы было видно, что встречу отменили.
Значения: confirmed, tentative, cancelled.
CalendarEventVisibility
Видимость события. default — подробности события открыты; private — владелец календаря их закрыл: у события есть только время, состояние и вид, а название, повестка, приглашённые, организатор, конференция и серия не отдаются.
Значения: default, private.
DateRange
Окно дат. Начало и конец включительно.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
from | да | string (date) | Первый день окна. |
to | да | string (date) | Последний день окна. |