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

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

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

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

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

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

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

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

Авторизация

Все запросы авторизуются персональным 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 — создание/изменение/удаление дашбордов, виджетов и фильтров.

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

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

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

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

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

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