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

Что нового

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

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

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

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

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

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

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

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

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

Изменения​

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.
  • Тарифные лимиты по частоте запросов, токенам и вебхукам.