Интеграция Outlook Calendar API с сайтом: Microsoft Graph

Отметим: когда на сайте клиники пациент записывается к врачу, а в Outlook врача слот остаётся свободным — начинаются проблемы. Ручная сверка отнимает часы и приводит к двойным броням. Решение — связать сайт с календарями Outlook через Microsoft Graph API. За 3–4 дня мы реализуем автоматическое создание встреч и проверку занятости. Обновление происходит в реальном времени с задержкой менее 2 секунд. Ниже — технические детали интеграции.

Без API Outlook разработчики часто сталкиваются с тремя проблемами. Дублирование броней из-за отсутствия атомарности при записи. Несогласованность времени при ручном переносе событий. Ошибочные слоты из-за неучтённых meeting-серий. Graph API избавляет от этих рисков, но требует грамотной настройки аутентификации и работы с findMeetingTimes. Мы настраиваем OAuth 2.0 с делегированными разрешениями, чтобы приложение работало без доступа к почтовому ящику администратора.

Помимо базовых сценариев, мы решаем сложные задачи: синхронизация нескольких календарей в одном тенанте, обработка повторяющихся событий, поддержка часовых поясов. Благодаря delta-запросам обновления приходят мгновенно, без лишних вызовов API. Средняя скорость запроса — около 200 мс, что в 3 раза быстрее устаревшего EWS.

Как настроить аутентификацию для Outlook Calendar?

Первый шаг — регистрация приложения в Azure AD. Мы создаём сертификат клиента для безопасного обмена токенами, предоставляем приложению разрешения Calendars.ReadWrite.All и User.Read. Это позволяет работать с календарями любого пользователя в тенанте. Затем получаем access-токен через протокол OAuth 2.0 On-Behalf-Of flow (OAuth 2.0 Authorization Framework) — система может действовать от имени авторизованного администратора. Весь процесс занимает около часа и документируется в Postman-коллекции. Для работы с календарями всех пользователей нужно разрешение Calendars.ReadWrite.All. Если требуется только для одного — достаточно Calendars.ReadWrite. Разрешения назначаются в Azure AD через приложение. Мы помогаем выбрать минимально необходимые права.

Как интегрировать Outlook Calendar с помощью Microsoft Graph?

Основной сценарий — чтение событий за неделю вперёд:

import { Client } from '@microsoft/microsoft-graph-client';
const client = Client.initWithMiddleware({ authProvider: tokenCredentialAuthProvider });
async function getCalendarEvents(userId: string): Promise<Event[]> {
  const response = await client
    .api(`/users/${userId}/calendarView`)
    .query({
      startDateTime: new Date().toISOString(),
      endDateTime: new Date(Date.now() + 7 * 86400000).toISOString(),
    })
    .select('subject,start,end,location,isAllDay')
    .orderby('start/dateTime')
    .get();
  return response.value.map((e: any) => ({
    id: e.id,
    title: e.subject,
    start: e.start.dateTime,
    end: e.end.dateTime,
    location: e.location?.displayName,
    allDay: e.isAllDay,
  }));
}

Создание встречи требует привязки к конкретному календарю пользователя:

async function createEvent(userId: string, booking: Booking): Promise<string> {
  const event = await client.api(`/users/${userId}/events`).post({
    subject: booking.serviceName,
    start: {
      dateTime: booking.startsAt,
      timeZone: 'Russian Standard Time'
    },
    end: {
      dateTime: booking.endsAt,
      timeZone: 'Russian Standard Time'
    },
    body: {
      contentType: 'HTML',
      content: `<p>Клиент: ${booking.customerName}</p><p>Телефон: ${booking.phone}</p>`
    },
    attendees: [
      {
        emailAddress: {
          address: booking.customerEmail
        },
        type: 'required'
      }
    ],
    isReminderOn: true,
    reminderMinutesBeforeStart: 60
  });
  return event.id;
}

Обработка ошибок критична: мы учитываем rate limits (10 000 запросов в час на приложение) и повторяем вызовы с экспоненциальной задержкой при получении кода 429. Также проверяем, что событие не пересекается с уже существующими через findMeetingTimes.

Почему Graph API лучше EWS?

EWS (Exchange Web Services) уступает по всем метрикам: он медленнее — TTFB в 3 раза выше (200 мс против 600 мс), требует настройки сертификатов и не поддерживает delta-запросы. Graph API — современное REST-решение на OAuth2 с превосходной документацией. Вот сравнение:

Дополнительные возможности Graph API:

• Работа с встречами через Teams (onlineMeetingProvider, joinWebUrl)
• Поддержка вложений (до 150 МБ на событие)
• Управление напоминаниями и доступностью комнат

Кроме того, Graph API дешевле в сопровождении — не требует обновления сертификатов и поддерживает современные сценарии, такие как совместная работа с календарём через webhook-уведомления. За 5 лет мы реализовали более 30 проектов интеграции корпоративных календарей для клиник, сервисов аренды и HR-платформ.

Частые ошибки при работе с Graph API

Что входит в работу

• Регистрация приложения в Azure AD и генерация сертификатов клиента
• Реализация REST-эндпоинтов чтения, создания и обновления событий
• Настройка уведомлений об изменениях (webhook) для real-time синхронизации
• Интеграция с CMS (WordPress, Drupal, Strapi и др.)
• Документация по интеграции (Postman-коллекция, схема БД)
• Тестирование с учётом N+1-запросов и лимитов API
• Мониторинг ошибок и алерты при падении авторизации

Процесс работы

1. Аналитика: выясняем сценарии — бронирование, синхронизация, публичные слоты.
2. Проектирование: выбираем между делегированными и application-разрешениями.
3. Реализация: пишем сервисный слой на Node.js/Nest.js, подключаем к Redis-кэшу.
4. Тестирование: покрываем юнит-тестами, проверяем edge-кейсы (timezone, meeting series).
5. Деплой: настраиваем CI/CD, добавляем health-эндпоинты.

Сроки ориентировочно

Базовая интеграция (чтение + создание) — 3–4 рабочих дня. С webhook-синхронизацией — до 7 дней. Стоимость рассчитывается индивидуально после анализа вашей схемы бронирования. Экономия времени на ручной сверке составляет до 60%, что окупается уже через 2–3 месяца. Средняя экономия на операционных расходах — около $180–260 в месяц.

У нас за плечами 5+ лет опыта интеграции корпоративных календарей — реализовано более 30 проектов для клиник, сервисов аренды и HR-платформ. Свяжитесь с нами — получите консультацию по оптимизации Core Web Vitals и управлению rate limits Graph API. Закажите интеграцию, и мы покажем примеры рабочих решений.