Skip to content

Календарь ​

Семейство 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нетbooleantrue — приглашённых больше 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)Последний день окна.