Перейти к основному содержимому

Что нового

История изменений API и правила версионирования.

Политика версионирования​

Версия API указана в адресе: /api/v1. Мы придерживаемся простого правила — существующие интеграции не должны ломаться без предупреждения.

Считается совместимым изменением (может появиться в любой момент, без смены версии):

  • добавление новых эндпоинтов;
  • добавление новых необязательных параметров запроса;
  • добавление новых полей в ответ;
  • добавление новых значений в списки (где это не меняет смысл существующих).

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

Считается несовместимым изменением (выходит только в новой версии, например /v2):

  • удаление или переименование эндпоинтов, параметров или полей;
  • изменение типа или смысла существующего поля;
  • ужесточение обязательности параметров.

О несовместимых изменениях и о выводе версий из эксплуатации мы предупреждаем заранее.

Изменения​

2026-10-17 — удаление листа с защищёнными диапазонами​

  • Удалить лист с защищёнными диапазонами может только владелец таблицы. Для остальных DELETE /documents/{document}/sheets/{sheet} возвращает 403 с кодом sheet_protected. Раньше защищённый диапазон удаление листа не останавливал.
  • Вебхук через AI-агента. Создание вебхука из подключения по OAuth (например, через MCP) больше не завершается ошибкой 500.

2026-10-17 — подписки на вебхуки после потери доступа​

  • Без доступа уведомления не отправляются. Пока создатель подписки не может редактировать таблицу или токен, через который она создана, удалён, просрочен или ограничен другими таблицами, уведомления по подписке не уходят, в том числе повторные. Подписка при этом не выключается: когда доступ возвращается, отправка возобновляется. Раньше такие подписки продолжали присылать изменения таблицы. Подписка, созданная AI-агентом через подключение по OAuth, не привязана к токену: она работает, пока у пользователя есть право редактировать таблицу.

2026-10-16 — код отказа из-за защиты и поля вебхука​

  • Код sheet_protected. Отказ 403 из-за защиты листа или диапазона при записи, добавлении строк, очистке, переименовании и удалении листа теперь содержит поле "error": "sheet_protected", а текст упоминает защиту листа и диапазона; в ответе batchUpdate указан и адрес диапазона. Тот же код получил отказ 403 в чтении листа со скрытыми значениями (GET /values/{range}), текст этого отказа прежний. В ответе batchGet диапазон скрытого листа, кроме текста в error, получил поле "errorCode": "sheet_protected". По коду интеграция отличает защиту от нехватки прав токена.
  • Вебхук: ranges описывает те же ячейки, что и cells, поэтому при обрезке (truncated = true) он больше не перечисляет все изменения листа.
  • Вебхук: скрытые листы. Уведомление больше не содержит ячеек листа, значения которого скрыты от пользователя, создавшего подписку: их нет в cells, ranges, changes и cellCount. Если изменились только такие ячейки, уведомление не отправляется.
  • Вебхук: удалённый лист. Ячейки листа, удалённого до отправки уведомления, больше не приходят в cells, ranges и changes без названия листа; в cellCount они по-прежнему учтены.

2026-10-15 — защита листа при записи и очистке​

  • Защищённый лист. Пользователь, который не является владельцем таблицы, записывает значения только в открытые ячейки листа (исключения), а если для исключений указан список участников, только при условии, что он есть в этом списке. Раньше лист, защищённый без списка участников, принимал запись через API от любого редактора.
  • Защищённый диапазон. Записывать в него могут только участники из его списка. Раньше защита диапазонов при записи через API не проверялась.
  • Очистка диапазона (POST /values/clear) проверяет защиту так же, как запись: закрытая ячейка в диапазоне возвращает 403, и ничего не очищается.
  • Переименование и удаление защищённого листа доступны только владельцу таблицы. Раньше лист, защищённый без списка участников, мог переименовать или удалить любой редактор, а лист со списком — участники из этого списка.

Это ужесточение прав по правилам приложения; отличия API описаны на странице Защита листов. Интеграция, которая писала в защищённые ячейки от имени редактора, получит 403: откройте нужные ячейки в настройках защиты, добавьте пользователя в список или снимите защиту.

2026-10-10 — числа, числовой формат и защита при операциях с листами​

  • Дробные числа. Число, переданное JSON-числом (12.75), сохраняется как число, а не как текст. При чтении числовая ячейка всегда приходит JSON-числом, даже если в таблице оно введено с запятой: 2500.5 вместо строки "2500,5". Строка "12.75" по-прежнему сохраняется как текст.
  • Числовой формат. Записанное значение и результаты зависящих от него формул показываются в числовом формате ячейки (m): 1 234,50 ₽, а не 1234.5. Значение v при этом не меняется.
  • Защита листа при операциях с листами. Переименование и удаление листа, закрытого защитой от пользователя токена, возвращают 403 (PATCH и DELETE /sheets/{sheet}).
  • Ячейки с датой помечены полем t: "d" — по нему дату можно отличить от обычного числа.

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

2026-09-07 — защита листов на чтении и записи​

  • API теперь учитывает защиту листа. Если значения листа скрыты от пользователя токена, чтение диапазона этого листа возвращает 403 (values/{range}), а в batchGet такой диапазон приходит с полем error.
  • Если лист закрыт от редактирования, а пользователь токена не в списке разрешённых, запись возвращает 403 (PUT, append, batchUpdate). batchUpdate атомарный, поэтому отклоняется весь запрос.
  • Владелец таблицы под ограничения защиты не попадает. Подробнее — Защита листов.

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

2026-08-21 — ориентация значений и итог записи​

  • Параметр majorDimension (ROWS по умолчанию / COLUMNS) — на чтении (values/{range}, batchGet) задаёт форму сетки, на записи (PUT, append, batchUpdate) позволяет писать столбцами.
  • В ответах записи добавлены updatedRange (фактический записанный диапазон с именем листа), updatedRows, updatedColumns, updatedCells.

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

2026-08-05 — роли документов и ограничение токенов таблицами​

  • В ответах GET /documents и GET /documents/{id} появилось поле permission — ваша роль в документе: owner, edit, comment, view.
  • Фильтр GET /documents?permission=edit — только таблицы, доступные для записи (владелец или редактор).
  • Токен можно ограничить конкретными таблицами (при создании ключа в настройках): для такого токена GET /documents возвращает только разрешённые таблицы, а обращение к таблице вне списка возвращает 403.

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

2026-07-09 — первый публичный выпуск​

  • Документы: список и получение по идентификатору.
  • Чтение значений: диапазон, batchGet, пагинация, открытые диапазоны.
  • Запись значений: PUT, batchUpdate, append, clear, формулы и спилл.
  • Идемпотентность записи через заголовок Idempotency-Key.
  • Листы: список, создание, переименование, удаление.
  • Вебхуки: подписки, доставка с HMAC-подписью, канал Telegram.
  • Аудит изменений через API.
  • Тарифные лимиты по частоте запросов, токенам и вебхукам.