API-інтеграція з Notion: headless CMS для динамічного сайту

Проблема ручної синхронізації контенту та її вирішення через Notion API

Уявіть: ваша команда веде документацію в Notion, а сайт працює на WordPress. Кожне оновлення статті потребує ручного копіювання — на це йде до 2 годин на тиждень. Помилки неминучі: забули оновити посилання, втратили форматування. Ми зіткнулися з цим на проекті з 200+ сторінками документації — синхронізація вручну забирала понад 40 годин на місяць. Рішення — використовувати Notion як headless CMS через API. База даних Notion стає єдиним джерелом даних для блогу, документації або каталогу. Редагуєте в Notion — сайт оновлюється автоматично. За останні 5 років ми реалізували понад 15 таких інтеграцій — підхід перевірений на проектах від стартапів до enterprise з об'ємом контенту до 5000 сторінок.

За даними Notion API documentation, API дозволяє гнучко працювати з базами даних та блоками. Однак без грамотного кешування та архітектури ви швидко впертеся в rate limit у 3 запити на секунду. Розберемо, як це обійти.

Як ми реалізуємо інтеграцію Notion API

Робота з базами даних Notion

import { Client, isFullPage } from '@notionhq/client'; const notion = new Client({ auth: process.env.NOTION_API_KEY }); // Отримання записів з бази даних async function getBlogPosts(): Promise<BlogPost[]> { const response = await notion.databases.query({ database_id: process.env.NOTION_BLOG_DB!, filter: { property: 'Published', checkbox: { equals: true } }, sorts: [{ property: 'Date', direction: 'descending' }], }); return response.results .filter(isFullPage) .map(page => ({ id: page.id, title: (page.properties.Title as any).title[0]?.plain_text ?? '', slug: (page.properties.Slug as any).rich_text[0]?.plain_text ?? '', date: (page.properties.Date as any).date?.start ?? '', excerpt: (page.properties.Excerpt as any).rich_text[0]?.plain_text ?? '', cover: page.cover?.type === 'external' ? page.cover.external.url : null, tags: (page.properties.Tags as any).multi_select.map((t: any) => t.name), })); } 

Отримання контенту сторінки

Notion зберігає контент як блоки. notion-to-md конвертує їх у Markdown:

import { NotionToMarkdown } from 'notion-to-md'; import { unified } from 'unified'; import remarkParse from 'remark-parse'; import remarkHtml from 'remark-html'; const n2m = new NotionToMarkdown({ notionClient: notion }); async function getPageContent(pageId: string): Promise<string> { const mdBlocks = await n2m.pageToMarkdown(pageId); const mdString = n2m.toMarkdownString(mdBlocks); const result = await unified() .use(remarkParse) .use(remarkHtml) .process(mdString.parent); return String(result); } 

ISR з on-demand revalidation

При зміні запису в Notion — Zapier або Make.com викликають webhook сайту, який інвалідує кеш конкретної сторінки:

// Next.js: on-demand revalidation export async function POST(request: Request) { const { page_id, slug } = await request.json(); await revalidatePath(`/blog/${slug}`); await revalidatePath('/blog'); return Response.json({ revalidated: true }); } 

Порівняння продуктивності Notion API та традиційної CMS

За швидкістю впровадження інтеграція Notion випереджає класичні CMS: налаштування займає 3–5 днів проти 5–10 днів для WordPress, якщо рахувати лише базову функціональність. На продуктивність впливає кешування — при правильній архітектурі час завантаження сторінок знижується в 3–5 разів порівняно з прямими запитами до API.

Порівняння з платними headless CMS

Чому Notion підходить для блогу чи документації?

Для команд, які вже використовують Notion, це природний вибір: не потрібно вчити нову адмінку, контент зберігається у знайомій структурі баз даних. За нашою статистикою, час публікації статті скорочується на 60% — просто написали в Notion, виставили прапорець "Published" і готово. Додатковий плюс — безкоштовний тариф покриває до 1000 блоків на сторінку, чого вистачає для більшості статей.

Як обійти обмеження Notion API?

Головні обмеження: 3 запити на секунду та відсутність нативних вебхуків. Rate limit вирішується кешуванням — ми використовуємо Redis або CDN з TTL 1–5 хвилин. Для статичних сторінок (документація) цілком допустимо оновлювати кеш раз на годину. Вебхуки реалізуємо через Zapier або Make — вартість таких зв'язок невисока і окупається за рахунок відсутності необхідності у платній CMS. Практично 95% трафіку віддається з кешу, тому швидкість відгуку сайту залишається високою.

Забезпечення продуктивності при rate limit

Кеш — ваш головний інструмент. Ми комбінуємо Redis на сервері та CDN з тривалим TTL для статичних сторінок. Для динамічних розділів (наприклад, пошук) використовуємо edge-функції з коротким кешем або fallback на ISR. Такий підхід дозволяє тримати швидкість завантаження під контролем навіть при частих оновленнях контенту.

Чек-лист для запуску інтеграції

• Створити інтеграцію в Notion (отримати API-ключ).
• Налаштувати базу даних з потрібними полями.
• Розробити endpoint для отримання записів.
• Реалізувати кешування (Redis, CDN).
• Налаштувати webhook при зміні контенту.
• Протестувати оновлення сторінок.

Процес роботи та терміни

Етапи:

1. Аналітика: вивчаємо структуру вашої Notion-бази, узгоджуємо схему даних.
2. Проектування: обираємо стек (частіше Next.js + ISR), проектуємо компоненти.
3. Реалізація: розробляємо API-шар, верстку, кешування.
4. Тестування: перевіряємо коректність даних, час завантаження, обробку помилок.
5. Деплой: розгортаємо на вашому хостингу, налаштовуємо вебхуки.

Що входить у роботу

• Документація щодо API та структури даних.
• Вихідний код з коментарями.
• Доступи до сервера та репозиторію.
• Навчання команди роботі з інтеграцією.
• Гарантія 30 днів на усунення дефектів.

Терміни: базова інтеграція (список + детальна сторінка) — 3–5 робочих днів. Складні проекти — до 3 тижнів. Зв'яжіться з нами для точної оцінки вашого проекту. Замовте інтеграцію Notion API під ключ та отримайте консультацію безкоштовно.