HTTP API для интеграций

Публичный API Sumvest позволяет читать и изменять таблицы (datasets) и дашборды (dashboards) из ваших скриптов и сторонних сервисов. API доступен на тарифе Pro: ключи создаются только там. Это та же поверхность, что использует веб-приложение, но только методы с данными. Административные, платёжные и служебные методы в публичный контракт не входят.

Спецификация

Машиночитаемая спецификация OpenAPI и интерактивный Swagger UI доступны по адресу:

https://app.sumvest.ru/api/v1/docs

Доступ к спецификации закрыт за авторизацией и включается администратором (флаг окружения ENABLE_SWAGGER). Если страница недоступна, запросите актуальный экспорт спецификации через поддержку.

В спецификации описаны только две группы методов:

• datasets: список/создание/обновление таблиц, полей и строк, серверная агрегация, пакетная замена строк;
• dashboards: дашборды, виджеты, наборы фильтров.

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

Метод	Что делает
GET /datasets, POST /datasets	Список таблиц, создать таблицу
GET /datasets/:id	Таблица и её поля
GET /datasets/:id/rows, POST /datasets/:id/rows	Строки таблицы, добавить строку
POST /datasets/:id/rows/bulk	Добавить много строк за раз
PATCH /datasets/:id/rows/:rowId, DELETE …/rows/:rowId	Изменить или удалить строку
GET /datasets/:id/export?format=csv|json	Выгрузить таблицу
GET /dashboards	Дашборды, их виджеты и фильтры
GET /me/profile	Профиль владельца ключа

Значения строк передаются по ключам полей (латиница, например amount), а не по названиям. Ключи видны в ответе GET /datasets/:id.

Авторизация

Все запросы авторизуются персональным API-ключом в заголовке Authorization. Ключ имеет формат inv_<env>_<hex> (например, inv_live_… для боевого окружения). Создать и отозвать ключ можно в Настройки → API ключи (см. раздел «API-ключи»).

# Список таблиц
curl https://app.sumvest.ru/api/v1/datasets \
  -H "Authorization: Bearer inv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Создать строку в таблице
curl -X POST https://app.sumvest.ru/api/v1/datasets/<datasetId>/rows \
  -H "Authorization: Bearer inv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"values":{"amount":1500,"note":"оплата"}}'

Scope (права ключа)

Каждый ключ ограничен набором scope. Методы проверяют их и возвращают 403 Forbidden, если права недостаточно:

• read:datasets: чтение схемы и строк таблиц;
• write:datasets: создание/изменение/удаление таблиц, полей и строк;
• read:dashboards: чтение дашбордов, виджетов и фильтров;
• write:dashboards: создание/изменение/удаление дашбордов, виджетов и фильтров;
• read:profile: чтение профиля владельца ключа.

В интерфейсе эти права называются «Чтение datasets», «Изменение datasets», «Чтение дашбордов», «Изменение дашбордов» и «Чтение профиля».

Выдавайте ключу минимально необходимый набор scope: если интеграция только читает данные, не давайте write:*.

Лимиты запросов (rate limit)

Запросы, авторизованные API-ключом, считаются по отдельному бакету (независимо от лимита сессионных запросов из браузера). По умолчанию это 120 запросов в минуту на ключ. При превышении метод возвращает 429 Too Many Requests: сделайте паузу и повторите запрос позже.

Отдельные «дорогие» методы (например, серверная агрегация POST /datasets/:id/aggregate) имеют собственный, более строгий лимит.

Приватные таблицы

Для приватных таблиц (сквозное шифрование) сервер не видит содержимого строк: вместо values возвращается зашифрованный valuesEncrypted, а серверная агрегация и экспорт недоступны. Расшифровка выполняется только в браузере после разблокировки хранилища. Через API такие таблицы доступны лишь как зашифрованные блобы.