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 под ключ и получите консультацию бесплатно.