Інтеграція 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. Економія на ручному звірянні може сягати 30 000 грн на місяць для середнього бізнесу, що окупається за 2–3 місяці.
Як налаштувати аутентифікацію для 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) поступається за всіма метриками: Graph API кращий за EWS в 3 рази за швидкістю запитів (200 мс проти 600 мс), вимагає налаштування сертифікатів і не підтримує delta-запити. Graph API — сучасне REST-рішення на OAuth2 з чудовою документацією. Ось порівняння:
| Характеристика | Graph API | EWS |
|---|---|---|
| Аутентифікація | OAuth 2.0 (без паролів) | Basic або складне налаштування OAuth |
| Швидкість запитів | ~200 мс на запит | ~600 мс |
| Пропускна здатність | 10 000 запитів / год на застосунок | 1 000 / год |
| Delta-синхронізація | Є (change notifications) | Немає |
Додаткові можливості Graph API:
- Робота з зустрічами через Teams (onlineMeetingProvider, joinWebUrl)
- Підтримка вкладень (до 150 МБ на подію)
- Керування нагадуваннями та доступністю кімнат
Крім того, Graph API дешевший у супроводі — не вимагає оновлення сертифікатів і підтримує сучасні сценарії, такі як спільна робота з календарем через webhook-сповіщення. Маємо понад 5 років досвіду інтеграції корпоративних календарів для клінік, сервісів оренди та HR-платформ — реалізовано більше 30 проектів. Наші спеціалісти сертифіковані Microsoft.
Типові помилки при роботі з Graph API
Таблиця типових помилок
| Код помилки | Причина | Рішення |
|---|---|---|
| 429 Too Many Requests | Перевищено rate limits | Реалізувати повтор з експоненційною затримкою |
| 401 Unauthorized | Закінчився або невірний токен | Оновити токен через refresh-механізм |
| 404 Not Found | Користувача не знайдено | Перевірити userId в тенанті |
Що входить в роботу
- Реєстрація застосунку в Azure AD та генерація сертифікатів клієнта
- Реалізація REST-ендпоінтів читання, створення та оновлення подій
- Налаштування сповіщень про зміни (webhook) для real-time синхронізації
- Інтеграція з CMS (WordPress, Drupal, Strapi та ін.)
- Документація з інтеграції (Postman-колекція, схема БД)
- Тестування з урахуванням N+1-запитів та лімітів API
- Моніторинг помилок та алерти при падінні авторизації
- Гарантія на інтеграцію — 12 місяців безкоштовної підтримки
Процес роботи
- Аналітика: з'ясовуємо сценарії — бронювання, синхронізація, публічні слоти.
- Проектування: вибираємо між делегованими та application-дозволами.
- Реалізація: пишемо сервісний шар на Node.js/Nest.js, підключаємо до Redis-кешу.
- Тестування: покриваємо юніт-тестами, перевіряємо edge-кейси (timezone, meeting series).
- Деплой: налаштовуємо CI/CD, додаємо health-ендпоінти.
Строки орієнтовно
Базова інтеграція (читання + створення) — 3–4 робочих дні, вартість від 49 000 грн. З webhook-синхронізацією — до 7 днів, вартість від 69 000 грн. Економія часу на ручному звірянні становить до 60%, що окупається вже через 2–3 місяці.
Маємо понад 5 років досвіду інтеграції корпоративних календарів — реалізовано більше 30 проектів для клінік, сервісів оренди та HR-платформ. Зв'яжіться з нами — отримайте консультацію з оптимізації Core Web Vitals та управління rate limits Graph API. Замовте інтеграцію, і ми покажемо приклади робочих рішень.