#Документация платформы Sapport для интеграторов
Публичная документация по подключению к платформе Sapport: чаты с ИИ-продажником, аналитика, публикатор статей, CRM и агенты, стратег, дашборды. Язык — русский.
Важно. Документация описывает и то, что уже работает (виджет, загрузчик, трекер, модули CMS, коннектор), и серверный API по секретному ключу (чтение уже доступно, запись частично проектируется). Статус каждой страницы указан в плашке в её начале и в таблицах ниже. Статус «Планируется» не является обещанием срока.
#Легенда статусов
| Статус | Значение |
|---|
| Доступно | Работает в боевых ячейках. Контракт можно использовать в продакшене; изменения — по политике версий |
| Бета | Работает, но контракт может измениться без срока уведомления. Использовать осознанно |
| Планируется | Проектируется, ещё не выпущено. Описание — целевое поведение; имена полей и детали могут уточняться. В продакшене не использовать |
Серверный API: чтение (/me, /wallet, диалоги, аналитика, дашборды, лиды, статьи, стратег) и вебхуки v2 — «Доступно»; запись (ответы в диалогах, правка лидов и статей, решения по темам и действиям), события и конверсии, генерация, песочница — «Планируется». Виджет, Chat API, загрузчик, JS-трекер, модули CMS и коннектор — «Доступно». Страницы со смешанным статусом помечают в плашке, какая часть уже работает.
Единая форма плашки в начале каждой страницы: > **Статус: …**.
#Модули и их статус
| Модуль | Что уже работает (Доступно) | Серверный API (Планируется) | Страницы |
|---|
| Чаты и ИИ-продажник | Виджет, Chat API (/api/widget/*) | Чтение диалогов и сообщений — Доступно; запись и ответ ИИ в своём канале (api) — Планируется | chat/ |
| Аналитика | Загрузчик, JS-трекер, серверный маяк, модули Bitrix и WordPress | Чтение аналитики и дашбордов — Доступно; приём событий и конверсий — Планируется | analytics/ |
| Публикатор статей | Публикация через модуль CMS и коннектор | Чтение статей — Доступно; задания генерации, правка, утверждение, публикация — Планируется | articles/ |
| CRM и агенты | Оценка и статусы лидов внутри платформы | Чтение лидов — Доступно; запись лидов, режимы CRM, запросы действий, карта статусов — Планируется | crm/ |
| Стратег | Отчёты и чат в кабинете | Отчёты, темы и действия (чтение) — Доступно; решения, разговор — Планируется | strategist/ |
| Дашборды | Экраны «Обзор» и «Пульс» в кабинете | Чтение по API — Доступно; встраивание — этап 4, Планируется | analytics/08-dashboards.md |
| Вебхуки | Вебхуки прежней версии (v1) | Вебхуки v2: подпись, повторы, ротация, журнал — Доступно | 06-webhooks.md |
#С чего начать
#Оглавление
#Сквозные разделы
| Файл | О чём | Статус |
|---|
| 01-introduction.md | Платформа для интегратора, модули, два вида API, схема связей | Доступно / Планируется |
| 02-quickstart.md | Ключ, адрес ячейки, GET /me, первый вызов, виджет | Доступно (песочница — Планируется) |
| 03-authentication.md | Интеграции, ключи, области, права, IP, тестовые ключи, утечка | Доступно (тестовые ключи — Планируется) |
| 04-cells-and-data.md | Ячейки RU/EN/ID, адреса, wrong_cell, ПДн, журнал выдач | Доступно |
| 05-conventions.md | Формат, ошибки и каталог кодов, пагинация, идемпотентность, асинхронные операции, пределы, версии, платные операции | Планируется |
| 06-webhooks.md | Вебхуки v2: подписки, события, подпись и проверка, повторы, ротация, журнал доставок | Доступно |
| 07-wallet.md | Кошелёк арендатора: состояния, GET /wallet, остановка обмена при отрицательном балансе (402 wallet_suspended), вебхуки, возобновление | Планируется |
| 90-changelog.md | Журнал изменений и политика устаревания | Доступно |
| 91-glossary.md | Глоссарий | Доступно |
#Чаты и ИИ-продажник — chat/
#Аналитика — analytics/
#CRM и агенты — crm/
#Публикатор статей — articles/
#Стратег — strategist/
#Карта серверного API по областям
Полная таблица областей и соответствие конечным точкам — 03-authentication.md.
#Открытые вопросы
Остались только вопросы, на которые решения пока нет. Всё остальное зафиксировано в тексте страниц. Полные перечни по модулям — в разделах «Открытые вопросы» на страницах разделов.
#К владельцу
- Адрес API. Принят путь
/api/public/v1 на домене ячейки; вариант поддомена api.<домен> (DNS и nginx на трёх ячейках) не отвергнут окончательно. - Тестовый режим. Откроются ли песочница и тестовые ключи вместе с ядром серверного API или позже. До решения описаны как «Планируется».
- Пределы по тарифам и
api_access. Стартовые пределы единые (чтение 600, запись 120, платные 30 в минуту); привязка к тарифам и перечень тарифов с api_access не определены. - Режимы CRM
external и both на всех ячейках, в том числе на ID (юрлицо партнёра-реселлера), и удаление ПДн по запросу клиента. - Языки документации. Состав и порядок выпуска английской и индонезийской версий.
- Эталон правил
type/id страницы для виджета и модулей (расхождение №6 в chat/02-widget-embed.md). - Мелкие продуктовые решения по модулям: правка темы стратега до утверждения, тариф и точность оценки генерации статьи, публикация модулей FastAPI и Nuxt, текст согласия для EN и ID, окно давности событий аналитики, мультивалютность офлайн-конверсий, отдельная область для конверсий.
#Техническое
- Право доступа. Принято
integrations.manage; реестр прав и боевые роли трёх баз предстоит обновить, иначе ключ без роли-хозяина означает «запретить всем». - Расхождения виджета и Chat API с проектом (расхождения 1–8, 12, 13, 22 из файла фактов): форма перед чатом, загрузка файлов, параметры канала, frame-ancestors, регулярки типа и id страницы.
- Пробелы контракта серверного API, которые закроет OpenAPI: право для
GET /disclosures; видимость GET /operations/{id} (по умолчанию — операции своей интеграции); код ошибки для просроченного курсора (принят 422 validation_failed с указателем /cursor); код для внутренней ошибки сервера (в каталоге его нет); состав data у crm.mode_changed; формат тела PUT /crm/status-map. - Изменения кода при выделении сервиса, которых требует контракт: хранение
reason оценки лида (score_reason, scored_at, score_source), неделя в granularity, data_as_of в DTO отчётов стратега, перевод bing в список источников после проверки, единые пределы статьи в PROTOCOL.md коннектора, отклонение темы только из proposed и в кабинете. - Определения метрик аналитики (
sessions, visitors, единицы) и привязка session_id аналитики к диалогу виджета.
#Обратная связь
Нашли неточность или не хватает описания — укажите страницу и X-Request-Id проблемного запроса (если есть) при обращении в поддержку своей ячейки.