Частые вопросы

Какой базовый URL у Coverse API?

Базовый URL — https://app.coverse.team/api/v1. Здесь api — это часть пути (/api/v1) на основном хосте app.coverse.team, а не отдельный поддомен. Адрес вида api.coverse.team не существует и не резолвится.

Как аутентифицироваться в API?

Передавайте токен доступа в заголовке Authorization: Bearer ТОКЕН. Токен создаётся в настройках аккаунта и наследует права своего пользователя. Подробнее — Аутентификация.

Почему запись возвращает 422 «Value writes require a collaborative table»?

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

Затирает ли запись остальное содержимое листа?

Нет. Запись (PUT, batchUpdate, append) затрагивает только ячейки переданного блока. Остальные данные листа сохраняются.

Можно ли управлять форматированием ячеек через API?

Нет. Форматирование (объединение ячеек, границы, цвета, шрифты и начертание, выравнивание, перенос, числовые форматы, ширина столбцов и высота строк) через API не задаётся. Доступны только значения ячеек. Записанное число принимает числовой формат своей ячейки: если у ячейки стоит денежный формат, значение покажется как «1 234,50 ₽».

Оформлять ячейки умеют скрипты Coverse: запишите данные через API, а оформление поручите скрипту, например по триггеру «При изменении». См. API или скрипты Coverse.

Почему число записалось как текст?

Число нужно передавать JSON-числом (1234.5), а не строкой. Строка "1234.5" с точкой сохраняется как текст — так же, как при ручном вводе в таблицу. Строка с запятой "1234,5" распознаётся как число. Подробнее — Диапазоны.

Почему запись возвращает 403?

Причин три: у токена нет права sheets.write, лист закрыт защитой от пользователя токена (Защита листов) либо запись не входит в тариф — на бесплатном тарифе доступно только чтение (Лимиты).

Как дописать строки в конец таблицы?

Используйте POST /documents/{id}/values/append. Строки добавляются после последней строки с данными; в ответе приходит startRow — номер строки, с которой начался добавленный блок. Подробнее — Диапазоны.

Как записать столбец, а не строку?

Либо передайте матрицу столбцом ({"values": [[10],[2],[5]]}), либо оставьте строку и укажите ориентацию ({"values": [[10,2,5]], "majorDimension": "COLUMNS"}). От диапазона в пути используется только верхняя-левая ячейка как точка привязки.

Как читать большие таблицы?

Чтение постраничное: используйте параметры offset и limit, а для следующей страницы — значение nextOffset из ответа, пока hasMore равно true. Подробнее — Пагинация.

Какие лимиты по частоте запросов?

Лимит считается в запросах в секунду и зависит от тарифа: от 1 до 10 запросов в секунду на пользователя (запросы всех токенов пользователя складываются). При превышении возвращается код 429 с полем retryAfter. Подробнее — Лимиты.

Можно ли автоматизировать таблицу без своего сервера?

Да, скриптами Coverse: код на JavaScript хранится в таблице и запускается по расписанию, при изменении ячеек, после ответа формы или по вебхуку из внешнего сервиса. Для популярных сервисов есть готовые руководства: Tilda, ЮKassa и Т-Банк, amoCRM и Битрикс24, 1С, Wildberries и Ozon, МойСклад, бот Telegram, Яндекс.Метрика и Директ. Как выбрать между API и скриптами — в статье API или скрипты Coverse.