API

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

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

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

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

Что можно делать через 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.

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

• «Публичный для сайта» — типы встреч, слоты, создание записей и профиль. Такой ключ ничего не показывает о ваших гостях и не может отменить встречу, поэтому его допустимо держать в открытом коде страницы: в скрипте формы записи, в шаблоне 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": "..."}}

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

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

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": "клиент перенёс встречу"}'

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

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

Чтобы получить не все записи, а нужные, добавьте фильтры в запрос GET /rest/v2/bookings:

Какие значения у фильтра status

• upcoming — встреча еще не началась
• past — встреча закончилась
• unconfirmed — организатор еще не подтвердил запись
• cancelled — встреча отменена

Как передать несколько статусов и несколько фильтров

Перечислите статусы через запятую в одном параметре, и запрос вернет записи, подходящие под любой из них. Например, status=upcoming,unconfirmed вернет и предстоящие встречи, и неподтвержденные записи.

Разные фильтры работают вместе: запись должна подходить под каждый из них. Например, eventTypeId=123&status=upcoming,unconfirmed вернет записи типа встречи 123, которые предстоящие или неподтвержденные.

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

Те же фильтры и то же правило работают в MCP-инструменте list_bookings, через который с записями работают AI-ассистенты.

Примеры запросов

# Только предстоящие встречи
curl "https://planerka.app/rest/v2/bookings?status=upcoming" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13"

# Предстоящие и неподтвержденные
curl "https://planerka.app/rest/v2/bookings?status=upcoming,unconfirmed" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13"

# Встречи за период: с 2026-09-25 по 2026-10-01
curl "https://planerka.app/rest/v2/bookings?afterStart=2026-09-25T00:00:00Z&beforeEnd=2026-10-01T23:59:59Z" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13"

# Предстоящие встречи для конкретного типа
curl "https://planerka.app/rest/v2/bookings?eventTypeId=123&status=upcoming" \
  -H "Authorization: Bearer cal_ВАШ_КЛЮЧ" \
  -H "cal-api-version: 2024-08-13"

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

Планёрка считает занятость по всему вашему календарю: время, занятое встречей одного типа, не будет предложено по другому. Учитываются записи, где вы организатор или участник, события из подключённых календарей и буферы до и после встреч. Если вы ведёте через 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 по запросам тех, кто им пользуется.