#Введение
Статус: Доступно / Планируется. Страница описывает платформу целиком. Статус каждого модуля указан в таблицах ниже. Серверный API по секретному ключу — Планируется; виджет, загрузчик, JS-трекер, модули для CMS и коннектор — Доступно.
Эта страница объясняет, что такое платформа Sapport с точки зрения интегратора: какие модули есть, какие бывают API, как всё связано между собой и с чего начать чтение.
#Для кого эта документация
- Разработчик на стороне арендатора — подключает чат с ИИ-продажником к своему сайту или мессенджеру, забирает аналитику в BI, публикует статьи на собственный сайт, получает лиды в свою CRM.
- Разработчик внешней системы (CRM, BI, CMS, мобильное приложение) — работает с платформой по серверному API.
- Технический специалист владельца сайта — ставит загрузчик или модуль для Bitrix/WordPress и подключает виджет чата.
Документация не описывает внутреннее устройство платформы и кабинет персонала. Она описывает то, что можно вызвать, встроить и получить.
#Основные понятия
| Понятие | Что это |
|---|---|
| Арендатор | Ваша организация на платформе. Все данные, ключи и деньги привязаны к арендатору. |
| Ячейка | Независимая боевая копия платформы со своей базой, своими секретами и своим юридическим лицом. Три ячейки: RU, EN, ID. Подробнее — Ячейки и данные. |
| Интеграция | Служебная учётная запись арендатора для программного доступа. Без входа в кабинет. Владеет ключами. |
| Ключ API | Секретная строка sap_<ячейка>_<режим>_<идентификатор>_<секрет>. Подробнее — Аутентификация. |
| Область (scope) | Право, которое ключ получает при выпуске: например leads:read. |
Полный словарь — Глоссарий.
#Модули платформы
| Модуль | Что делает для интегратора | Серверный API | Клиентская часть |
|---|---|---|---|
| Чаты и ИИ-продажник | Принимает обращения посетителей, отвечает от имени ИИ-продажника, передаёт диалог оператору. Свой канал арендатора подключается через API. | Диалоги (чтение) — Доступно; запись — Планируется | Виджет и Chat API — Доступно |
| Аналитика | Собирает посещения, источники, поведение, цели и конверсии; считает воронку и видимость в поиске и ИИ-ответах. | Чтение — Доступно; приём событий — Планируется | Загрузчик, JS-трекер, модули — Доступно |
| Публикатор статей | Генерирует статьи по профилю редакции, согласует и публикует их на сайт арендатора. | Чтение — Доступно; генерация и запись — Планируется | Модули Bitrix и WordPress, коннектор — Доступно |
| CRM и агенты | Хранит лиды и контакты, оценивает лиды, ведёт агентов продаж. Работает как наша CRM, как проекция вашей внешней CRM или в смешанном режиме. | Чтение — Доступно; запись — Планируется | — |
| Стратег | ИИ-маркетолог: регулярные отчёты с доказательствами, очередь тем, действия чата, разговор. | Чтение отчётов, тем и действий — Доступно; решения и разговор — Планируется | — |
| Дашборды | Готовые срезы «Обзор» и «Пульс» с честной датой актуальности по каждому источнику. | Чтение — Доступно | Встраивание дашбордов — этап 4, Планируется |
Документ фиксирует состояние и замысел, а не календарь.
#Два вида API
Платформа предлагает два принципиально разных способа взаимодействия. Их нельзя путать: у них разный уровень доверия.
#Серверный API (по секретному ключу)
- Вызывается только с вашего сервера — «сервер–сервер». CORS не включён намеренно.
- Авторизация — секретный ключ в заголовке
Authorization: Bearer …. Проверка ключа и ваших прав —GET /me. - Арендатор определяется только по ключу; передать чужой идентификатор арендатора нельзя.
- Базовый адрес у каждой ячейки свой:
https://<домен ячейки>/api/public/v1. - Покрывает: диалоги и ИИ-продажник, лиды и CRM, аналитику и дашборды, статьи, стратега, вебхуки.
- Статус: Доступно (чтение, кошелёк, вебхуки v2); запись, события, конверсии, генерация и песочница — Планируется.
#Клиентские интерфейсы (из браузера и со страниц)
| Интерфейс | Назначение | Доверие | Статус |
|---|---|---|---|
Виджет чата (/widget.js) | Готовое окно чата на вашем сайте | Открытый идентификатор канала; сессия — подписанный токен | Доступно |
Chat API (/api/widget/*) | Свой интерфейс чата («headless») | Открытый channel_id и токен сессии; секретного ключа нет и быть не должно | Доступно |
Загрузчик (/api/v1/connector/loader.js?k=…) | Одна строка: трекер, поведение, чат, согласие | Публичный ключ загрузчика | Доступно |
JS-трекер (/api/v1/track/js?t=…) | Минимальный учёт загрузок страниц | Токен трекера | Доступно |
| Серверный маяк модулей | Подписанная отправка визитов с сервера CMS (видит ботов и ИИ-краулеры) | Подписанный запрос | Доступно |
Правило безопасности. Секретный ключ серверного API никогда не попадает в браузер, мобильное приложение, репозиторий и журналы. Всё, что работает в браузере, использует только клиентские интерфейсы.
#Как всё связано
Ваша сторона Платформа Sapport (ячейка: RU / EN / ID)
┌────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ Посетитель │ │ │
│ │ │ │ ┌──────────────┐ ┌───────────────────┐ │
│ ▼ │ виджет / Chat API │ │ Чаты │◄──►│ ИИ-продажник │ │
│ Ваш сайт ── <script widget.js> ───────────┼────────────────────►│ │ (диалоги) │ │ (платно, кошелёк) │ │
│ │ └ <script loader.js> ───────────┼──── события, UTM ──►│ └──────┬───────┘ └─────────┬─────────┘ │
│ │ │ │ │ лиды │ │
│ ▼ │ подписанный маяк │ ▼ ▼ │
│ CMS-модуль (Bitrix / WP / …) ─────────────┼────────────────────►│ ┌──────────────┐ ┌───────────────────┐ │
│ ▲ публикация статей ◄──────────────────┼─────── задания ─────│ │ CRM и агенты │ │ Аналитика │ │
│ │ │ │ └──────┬───────┘ └─────────┬─────────┘ │
│ │ │ │ │ │
│ Ваши серверы │ Bearer-ключ, TLS │ ┌──────▼──────────────────────▼─────────┐ │
│ (CRM, BI, свой канал, мессенджер) ◄──────►┼◄───────────────────►│ │ Серверный API /api/public/v1 │ │
│ ▲ │ │ │ области · идемпотентность · пределы │ │
│ │ вебхуки (подпись, повторы) │ │ └──────┬──────────────────────┬─────────┘ │
│ └────────────────────────────────────────┼◄────────────────────│ ▼ ▼ │
└────────────────────────────────────────────┘ события │ ┌──────────────┐ ┌───────────────────┐ │
│ │ Стратег │ │ Дашборды │ │
│ │ (отчёты) │ │ («Обзор», «Пульс»)│ │
│ └──────────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────┘Как читать схему:
- Посетитель попадает на ваш сайт. Загрузчик и модуль CMS передают платформе источник перехода, UTM, поведение и (по вашему выбору) подписанный серверный маяк.
- Виджет открывает диалог. ИИ-продажник отвечает, при необходимости создаёт лид и зовёт оператора.
- Лид, диалоги и аналитика попадают в модули CRM, аналитики и стратега.
- Ваши серверы забирают данные и управляют ими через серверный API, а об изменениях узнают из вебхуков.
- Статьи, подготовленные платформой, уходят на ваш сайт через коннектор (подписанные задания) либо вы забираете их сами по событию
article.ready.
#Принципы, на которых построен API
- Арендатор — только из ключа. Идентификатор чужого ресурса даёт
404 not_found, а не403: платформа не подтверждает существование чужих данных. - Ключ живёт в одной ячейке. Данные ячеек не смешиваются; ключ другой ячейки отклоняется ответом
wrong_cell. - Наименьшие права. Ключ получает только нужные области; фактические права — пересечение областей, роли интеграции, текущих прав владельца и тарифа.
- Деньги видимы. Платные операции — отдельные области; стоимость возвращается в ответе (
usage), а траты ограничены предельными значениями. См. Соглашения. - Долгое — асинхронно. Операции, которые идут дольше нескольких секунд (ответ ИИ, оценка лида, генерация статьи, ход стратега), возвращают
202и конвертoperation; результат — запросомGET /operations/{id}либо событиемoperation.completed(Соглашения). - Контракт первичен. Спецификация OpenAPI 3.1 строится из тех же схем, которые проверяют запросы и ответы в рантайме.
- Площадочное закрыто. Внутренние таблицы и сервисы самой платформы (её собственный блог, курсы, публичные страницы) в публичный API не выходят.
#С чего начать
| Задача | Куда идти |
|---|---|
| Поставить чат на сайт за пять минут | Быстрый старт, затем Встраивание виджета |
| Получить первый ответ от серверного API | Быстрый старт |
| Понять ключи, области и права | Аутентификация |
| Выбрать адрес и понять границы данных | Ячейки и данные |
| Обрабатывать ошибки, пагинацию, повторы | Соглашения |
| Получать события | Вебхуки |
| Подключить внешнюю CRM | Режимы CRM |
Полное оглавление — в README.
#Заметки
- Примеры серверного API в документации иллюстративны до публикации спецификации OpenAPI: имена необязательных полей могут уточняться. Обязательные соглашения (аутентификация, формат ошибок, пагинация, подпись вебхуков) зафиксированы на страницах 03–06.
- Документация ведётся на русском языке.