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

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

[для разработчиков] Единые правила 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" }

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

HTTP	code	Когда
400	`INVALID_INPUT` / `INVALID_UUID`	неверные/неполные данные
401	`UNAUTHORIZED`	нет/невалидны учётные данные или подпись
403	`FORBIDDEN`	авторизован, но нет прав (роль)
404	`NOT_FOUND`	объект не существует или не виден
429	`RATE_LIMITED`	превышен лимит (смотри заголовок `Retry-After`)
500	`SYSTEM_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 · Кастомные вебхуки
Не получилось? → напиши в саппорт