Документация › Для разработчиков › Формат данных

Формат данных и интеграция фронта

Обновлено 13 августа 2026 г.

[для разработчиков] Единые правила API, как выглядят успех и ошибка, пагинация, realtime, авторизация. Если строишь интеграцию или свой фронтенд, начни отсюда.

⏱ 8 мин · 👤 для разработчика · 🟢 live

За 30 секунд:
  • Успех: { "data": … }. Ошибка: { "error": "текст", "code": "КОД" }.
  • Пагинация: ?page=&limit= (по умолчанию 100, максимум 200).
  • Realtime: через Supabase-каналы (INSERT/UPDATE/DELETE по таблице с фильтром проекта).
  • Авторизация: сессия-cookie (браузер) или API-ключ Bearer dos_sk_live_… (API).

Конверт ответа

Все ответы API это в едином формате.

Успех:

{ "data": { ... } }

HTTP 200 (или другой 2xx).

Ошибка:

{ "error": "Человеко-читаемое сообщение", "code": "ERROR_CODE" }

Коды ошибок и статусы

HTTPcodeКогда
400INVALID_INPUT / INVALID_UUIDневерные/неполные данные
401UNAUTHORIZEDнет/невалидны учётные данные или подпись
403FORBIDDENавторизован, но нет прав (роль)
404NOT_FOUNDобъект не существует или не виден
429RATE_LIMITEDпревышен лимит (смотри заголовок Retry-After)
500INTERNAL_ERRORнеобработанная ошибка (полный текст в логах и Sentry, наружу только общий)
500DATABASE_ERRORсбой запроса к базе

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

Пагинация

Параметры запроса: ?page= и ?limit=.

  • по умолчанию limit = 100, максимум 200;
  • page начинается с 1 (ограничен сверху, чтобы не уехать в гигантский offset);
  • в ответ обычно приходит блок pagination: { page, limit, total, has_more }.

Realtime

UI обновляется без перезагрузки через Supabase Realtime: подписка на изменения таблицы (postgres_changes) с фильтром по проекту (project_id=eq.<id>), события INSERT / UPDATE / DELETE.

Что важно интегратору:

  • подписка возвращает статус (подключено / ошибка / закрыто) и умеет переподключаться после обрыва сети;
  • на DELETE приходит только первичный ключ (если не включён полный снимок строки);
  • глобальный индикатор «нет связи» загорается, только когда отвалились все каналы.
💡 На клиенте это обёрнуто в хуки use-realtime-* (по одному на сущность), после любой мутации список обновляется сам. Подробнее про продукт-поведение: Диалоги.

Авторизация

СпособДля чего
Сессия-cookieбраузерный кабинет (httpOnly-cookie Supabase)
API-ключ Authorization: Bearer dos_sk_live_…внешние интеграции, серверный код, см. Публичный API

Оба проходят одни и те же проверки доступа (роли/проекты): отдельной «облегчённой» авторизации нет. Ключ только для чтения на мутирующем методе → отказ.

Простыми словами

Это шпаргалка для тех, кто пишет код поверх платформы. Договорённости простые и одинаковые везде, если всё хорошо в ответе лежит data с данными; если плохо, error с понятным текстом и коротким code, по которому удобно ветвить логику. Списки отдаются порциями (постранично, до 200 за раз). Живые обновления (новое сообщение, новый лид) прилетают сами через подписку, не надо опрашивать сервер по таймеру.

Заходить можно двумя дверями: обычной сессией из браузера или API-ключом для своего кода, и за обеими дверями работают одни и те же правила доступа, так что ключ не даёт ничего сверх твоих прав. Если строишь свой интерфейс или интеграцию, этих правил достаточно, чтобы начать.

Дальше: → Бот не отвечает
Связано: Публичный API · Кастомные вебхуки
Не получилось? → напиши в саппорт