API

API Планёрки позволяет управлять записями из вашей системы: показывать свободное время на своём сайте, создавать и отменять встречи, забирать данные о записях в CRM. Всё, что делает гость на странице записи, можно сделать запросом к API.

Запросы выполняются от имени владельца ключа: API видит только его типы встреч и его записи. Расписание, буферы, минимальное время до встречи и занятость учитываются так же, как на обычной странице записи, поэтому забронировать занятое или нерабочее время через API нельзя.

API доступно на любом платном тарифе и в течение пробного периода. На бесплатном тарифе ключ не работает — запросы возвращают ошибку 401.

Что можно делать через API

• получать свободные слоты по типу встречи;
• создавать запись на конкретное время;
• получать запись по идентификатору и список записей с фильтрами;
• отменять запись;
• получать список своих типов встреч и профиль владельца ключа.

Чего пока нет: переноса записи (делается как отмена и новая запись), подтверждения и отклонения заявок, редактирования записей, типов встреч и расписаний. Типы встреч доступны только на чтение — настраиваются они в личном кабинете.

Как запрашивать слоты, чтобы приложение работало плавно

Свободное время не лежит готовой таблицей — Планёрка считает его на каждый запрос: сводит график работы, буферы до и после встреч, минимальное время до записи, уже занятое время и события из подключённых внешних календарей. У round robin и коллективных встреч этот расчёт выполняется для каждого участника: у всех свои настройки доступности и свои календари, а участников может быть много. Чем шире окно дат и чем больше участников, тем дольше ответ — это не сбой, а объём работы.

Поэтому главное правило: не пытайтесь забрать сразу все слоты. Запрашивайте их лесенкой, от ближнего к дальнему, и складывайте в свой кеш:

1. сегодняшний день — гость почти сразу видит первое доступное время;
2. ближайшие три дня;
3. неделя;
4. месяц;
5. остаток месяца и даты дальше — докачивайте в фоне, пока человек смотрит на уже показанное.

Так первый экран появляется мгновенно, а тяжёлые запросы уходят в фон и заполняют кеш. Это работает в любом приложении поверх API Планёрки — от формы записи на сайте до внутренней CRM.

Ещё несколько правил гигиены:

• Кешируйте ответы у себя. Минуты-двух достаточно: за это время календарь редко меняется. Обновляйте кеш в фоне, а не на каждое движение пользователя по календарю.
• Не просите больше, чем показываете. Если записи открыты на 30 дней вперёд, запрашивать год незачем — дальше окна записи слотов всё равно нет.
• Не разгоняйте расчёт параллельными запросами по одному аккаунту: быстрее не станет. Идите шагами лесенки последовательно.
• Не перепроверяйте слот перед записью. POST /rest/v2/bookings сам проверит время и вернёт 409, если его успели занять, — лишний запрос слотов только замедлит сценарий.

Ограничения по частоте запросов

Чтобы API оставался быстрым для всех, мы просим держаться в пределах 5 запросов в секунду и 100 запросов в минуту на аккаунт. Для формы записи на сайте, синхронизации с CRM и обычных интеграций этого запаса хватает с большим избытком — особенно если вы забираете слоты лесенкой и кешируете ответы.

Нужны другие лимиты — например, вы запускаете массовую интеграцию или сервис с большим потоком записей? Напишите в поддержку: обсудим сценарий и подберём условия.

Шаг 1. Создайте API-ключ

Откройте раздел «Разработчикам» → «API-ключи» и нажмите «Создать ключ».

• Метка — чтобы потом понимать, где этот ключ используется: «сайт», «интеграция с CRM».
• Права. Готовые наборы: «Публичный для сайта», «Только чтение», «Полный доступ». Вариант «Пользовательский» и кнопка «Расширенно» открывают точечный выбор прав — подробно разбираем их в следующем разделе.
• Разрешённые сайты — это решение вопроса с CORS. Перечислите адреса, со страниц которых браузер будет обращаться к API напрямую. Поддерживается только https, протокол писать не нужно; www.site.ru и site.ru — разные адреса. Когда разработчик тестирует у себя, в этот же список добавляется localhost — иначе браузер заблокирует запросы с локальной страницы. Список можно менять и потом, в карточке ключа; изменения применяются примерно за 45 секунд.

Ключ вида cal_… показывается один раз — сразу скопируйте и сохраните его. В базе Планёрки хранится только хеш ключа, восстановить значение мы не сможем. Потерянный ключ отзовите и создайте новый.

Ключ работает от вашего имени, поэтому храните его так, как позволяют выданные ему права: ключ с чтением или отменой записей — только на сервере. Разбор по правам — в следующем разделе.

В списке ключей видно последний запрос и статус. Кнопка «Отозвать» мгновенно выключает ключ, «Подробнее» — показывает права и позволяет поменять список разрешённых сайтов.

Права ключа: что можно открыть, а что прятать

У каждого ключа свой набор прав — он определяет, какие запросы этим ключом вообще возможны. Права задаются при создании и потом не меняются: нужен другой набор — отзовите ключ и создайте новый. Запрос вне выданных прав получит ошибку 403.

Право	Что открывает
Типы встреч (чтение)	Список ваших типов встреч: id, ссылка, длительность, цена
Слоты (чтение)	Свободное время — то же, что видит гость на странице записи
Создание броней	Запись гостя на выбранное время
Брони (чтение)	Список и карточки записей — вместе с данными гостей: имена, почта, телефоны, ответы на вопросы
Отмена броней	Отмена любой вашей записи
Профиль владельца	Имя, аватар, часовой пояс — чтобы подписать форму записи

Главный смысл прав такой: правильно подобранный набор решает, можно ли держать ключ на виду.

• «Публичный для сайта» — типы встреч, слоты, создание записей и профиль. Такой ключ ничего не показывает о ваших гостях и не может отменить встречу, поэтому его допустимо держать в открытом коде страницы: в скрипте формы записи, в шаблоне Tilda, в исходниках фронтенда. Обязательно перечислите для него разрешённые сайты — тогда браузер сможет обращаться к API только с ваших страниц.
• «Только чтение» — типы встреч, слоты, чтение записей и профиль. Подходит для дашборда или выгрузки в CRM, но такой ключ отдаёт персональные данные гостей, поэтому живёт только на сервере, в переменных окружения.
• «Полный доступ» и любой набор с правом отмены — держите как пароль: только на сервере, никогда в коде страницы, в мобильном приложении и в публичном репозитории. Ключ с отменой позволяет снять любую вашу встречу.

Правило простое: давайте ключу ровно те права, которые нужны сценарию. Форме записи на сайте не нужно уметь читать чужие записи и тем более их отменять — а если такой ключ всё же утечёт, ограничьте ущерб заранее, а не после.

Под разные задачи заводите разные ключи: один публичный для сайта, второй серверный для CRM. Тогда при утечке достаточно отозвать один, не останавливая остальные интеграции.

Если ключ создан давно, когда прав ещё не было, у него полный доступ. Такой ключ лучше отозвать и создать новый с нужным набором.

Шаг 2. Первый запрос

Базовый адрес — https://planerka.app/rest/v2. В каждом запросе нужны два заголовка:

• Authorization: Bearer cal_ВАШ_КЛЮЧ
• cal-api-version: 2024-08-13

Проверить ключ проще всего запросом профиля:

curl "https://planerka.app/rest/v2/me" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13"

Ответ всегда приходит в одинаковой обёртке — успешный:

{"status": "success", "data": { ... }}

и ошибочный:

{"status": "error", "error": {"code": "NOT_FOUND", "message": "..."}}

Основные методы

Метод	Что делает
GET /rest/v2/event-types	Ваши типы встреч: id, ссылка, длительность, буферы, нужно ли подтверждение, цена
GET /rest/v2/slots	Свободные слоты за период по типу встречи
POST /rest/v2/bookings	Создать запись на конкретное время
GET /rest/v2/bookings	Список записей с фильтрами и постраничной выдачей
GET /rest/v2/bookings/{uid}	Запись по её идентификатору
POST /rest/v2/bookings/{uid}/cancel	Отменить запись
GET /rest/v2/me	Профиль владельца ключа

Как записать гостя: типовой сценарий

1. Узнайте id типа встречи. Один раз запросите GET /rest/v2/event-types и сохраните нужный id у себя.

2. Покажите свободное время.

curl "https://planerka.app/rest/v2/slots?eventTypeId=123\
&start=2026-08-10T00:00:00Z&end=2026-08-17T00:00:00Z\
&timeZone=Europe/Moscow" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-09-04"

Окно дат берите по лесенке из раздела выше: сначала сегодня, потом три дня, неделя, месяц — и докачивайте остальное в фоне.

Слоты приходят сгруппированными по датам в том часовом поясе, который вы передали:

{"status": "success", "data": {
  "2026-08-10": [{"start": "2026-08-10T09:00:00.000+03:00"}, ...]
}}

3. Создайте запись. Обязательны время начала и данные гостя; имя и часовой пояс гостя — минимально необходимое.

curl -X POST "https://planerka.app/rest/v2/bookings" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 123,
    "start": "2026-08-10T09:00:00.000Z",
    "attendee": {
      "name": "Иван",
      "email": "ivan@example.com",
      "timeZone": "Europe/Moscow"
    }
  }'

В ответе придёт запись с полем uid — сохраните его: по нему потом можно получить или отменить встречу. Если у типа встречи есть вопросы к гостю, ответы передаются в bookingFieldsResponses, а коллег можно добавить списком адресов в guests.

Дальше всё происходит как при обычной записи: гость и организатор получают письма и уведомления, встреча появляется в подключённых календарях, создаётся ссылка на видеовстречу, срабатывают вебхуки.

4. Отмена.

curl -X POST "https://planerka.app/rest/v2/bookings/UID_ЗАПИСИ/cancel" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13" \
  -H "Content-Type: application/json" \
  -d '{"cancellationReason": "клиент перенёс встречу"}'

Повторная отмена уже отменённой записи ошибкой не считается.

Занятость общая для всех типов встреч

Планёрка считает занятость по всему вашему календарю: время, занятое встречей одного типа, не будет предложено по другому. Учитываются записи, где вы организатор или участник, события из подключённых календарей и буферы до и после встреч. Если вы ведёте через API два разных направления, дополнительная проверка на вашей стороне не нужна.

Оплата перед записью

Отдельного метода «придержать слот на время оплаты» в API нет. Надёжный порядок такой: сразу создавайте запись через POST /rest/v2/bookings — это единственная операция, которая атомарно занимает время и вернёт 409, если слот успели занять с другого канала. Если оплата не прошла или истёк ваш таймер, отмените запись через /cancel.

Держать «резерв» только у себя в базе ненадёжно: Планёрка о нём не знает, и то же время может занять гость с вашей страницы записи.

Если своя платёжная система не обязательна, посмотрите встроенную оплату — там удержание слота и снятие неоплаченной записи уже работают: Платные встречи через Prodamus.

Вебхуки вместо постоянных запросов

Чтобы узнавать о новых, перенесённых и отменённых встречах, не нужно опрашивать список записей — подключите вебхуки: Планёрка сама отправит данные на ваш адрес. Как это настроить, описано в статье Webhooks.

Справочник с примерами

В личном кабинете есть интерактивный «Справочник API»: все методы, поля запросов и ответов, примеры кода. Запросы можно выполнять прямо со страницы — подставьте свой ключ. Та же документация открыта по адресу planerka.app/rest/v2/doc, а машиночитаемая спецификация OpenAPI — по адресу https://planerka.app/rest/v2/doc.json.

У каждого метода есть готовый пример запроса и разбор ответа — можно скопировать команду и подставить свой ключ.

Отдельного тестового окружения у Планёрки нет. Для отладки удобно завести скрытый тип встречи и отдельный ключ, а тестовые записи после проверки отменять.

Что означают коды ошибок

• 401 — ключ не передан, отозван, истёк или у аккаунта закончился платный тариф.
• 403 — у ключа нет нужного права или запрос идёт с сайта, которого нет в списке разрешённых. Проверьте карточку ключа.
• 404 — тип встречи или запись не найдены либо принадлежат другому аккаунту.
• 409 — время уже занято, предложите гостю другой слот.
• 400 — время не попадает в сетку слотов, в нерабочий день или за пределы окна записи; также если передана длительность, отличная от настроек типа встречи.

Если вы работаете с AI-ассистентом

Те же операции доступны ассистентам вроде Claude или Cursor через MCP-сервер — обычными словами, без запросов к API: MCP — управление бронированиями через AI-ассистента.

Не хватает метода, поля в ответе или события в вебхуках? Напишите нам — мы дорабатываем API по запросам тех, кто им пользуется.