Содержание конференции

Один из вопросов на сертификации по платформе Эра звучит так: «Что нельзя сделать в платформе, используя только API?» Ответ прост: через API можно сделать всё. Более того, собственные веб-приложения платформы работают через API и никак иначе. Никаких секретных методов или неопубликованных способов нет и не планируется.

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

Лайфхак: чтобы понять внутреннюю механику, откройте инструмент разработчика в браузере (F12) и посмотрите, какие API-методы вызываются приложением. Всё прозрачно.

Модели авторизации

First Party — внешнее приложение работает от имени конкретного пользователя платформы (оператора, супервизора). CRM-система может обращаться к платформе через User API, используя авторизацию текущего пользователя. Все действия выполняются в рамках его реальных прав. Если пользователь уволился — внешний интерфейс автоматически теряет доступ.

Third Party — доступ выдаётся не человеку, а интеграционной точке (Integration Point). Это системная интеграция: подключаются CRM, боты, middleware, аналитические системы. Права задаются настройками точки интеграции через доступные возможности (capabilities).

Главное различие: First party — приложение действует от имени пользователя; Third party — система действует от имени интеграционной точки.

Транспортные механизмы: HTTP и WebSocket

HTTP (REST API) — классический запрос-ответ. Используется для CRUD-сценариев: создания, чтения, изменения, удаления ресурсов. Это основной транспорт для обычных API-запросов.

WebSocket — постоянное двустороннее соединение. Создаётся долгоживущий канал, стороны обмениваются сообщениями без повторного открытия соединения. WebSocket используется там, где одного разового запроса недостаточно: подписка на события, мгновенная реакция в реальном времени.

HTTP удобен для транзакционных операций, WebSocket — для реактивной модели.

Integration Point — ключевой механизм интеграции

Integration Point (канал интеграции) — единая управляемая точка входа для внешних CRM, ERP, мессенджеров, ботов. Вам не нужно каждый раз разрабатывать отдельный бэкенд под конкретную интеграцию. Вы настраиваете точку внутри платформы, описываете, какие данные принимаете и как их обрабатываете.

Это единая точка входа по HTTP/HTTPS/WebSocket, точка авторизации с токеном (локальным ключом). Входящие данные обрабатываются служебными сценариями платформы (low-code). Инженер может настроить сценарий: принять JSON, разобрать поля, выполнить проверки, создать или изменить записи. Ключевая ценность — создание проектных API без разработки бэкенда.

Integration Point заменяет значительную часть кастомной бэкенд-разработки в интеграционных проектах и значительно ускоряет запуск интеграции.

Автоматическое REST API для кастомных классов

Когда вы создаёте в билдере кастомный класс (прикладную модель данных под задачи заказчика), платформа автоматически формирует для него REST API представление. Не нужно отдельно разрабатывать API-слой. Внешние системы сразу могут взаимодействовать с новым классом через стандартный интерфейс. Это сокращает время вывода функционала в эксплуатацию и снижает количество ошибок.

Польская запись (условный язык запросов)

Платформа не даёт внешним системам писать SQL напрямую — это рискованно. Вместо этого используется структурированный формат (польская запись), который передаётся в параметрах REST-запроса. Вы можете задавать фильтрацию, сортировку, маскировку полей, пагинацию (offset/limit), агрегацию и группировку. Это даёт гибкость, похожую на SQL, но без доступа к базе данных. Платформа контролирует структуру запроса, права доступа и нагрузку.

Документация: подробное описание и примеры — в статье «Польская запись» на wiki. Там показана фильтрация по подстроке, группировка, агрегация, сортировка, маскирование полей.

Служебные сценарии

Служебные сценарии — это процедуры или функции, создаваемые low-code инструментом. Сценарии вызываются извне через Integration Point. Внешняя система передаёт параметры, платформа принимает данные, сценарий обрабатывает их набором визуальных компонентов и возвращает результат. Типовые кейсы: приём заявок с сайта и маршрутизация, создание обратного звонка по событию, нормализация заявок из разных систем в единый формат, проверка внешних данных перед запуском процесса.

Искусственный интеллект в сценариях

Мы показали, как LLM-модели (локальные или облачные) могут быть использованы внутри сценариев. Примеры из проектов: определение пола клиента по ФИО, классификация заявки по тексту (техподдержка, продажи, жалоба), приоритизация, определение часового пояса, поиск зависших заявок, оценка качества заполнения карточки. Внешняя система просто отправляет запрос в платформу и получает ответ — ей не нужно заботиться о подключении к LLM.

Исходящие вебхуки: платформа генерирует запросы во внешние системы

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

• Асинхронные (уведомления) — платформа уведомляет, что что-то произошло (изменился статус вызова, завершилось взаимодействие). Сценарий не блокирует работу.
• Синхронные (запрос разрешения) — платформа делает запрос и ждёт результат, прежде чем перейти к следующему шагу. Например, перед звонком проверить во внешней CRM, можно ли звонить.

Управление звонками через API

Внешняя система может получать события звонков в реальном времени через WebSocket (подписка на callevents). Также можно инициировать исходящий вызов, переводить звонок, ставить на удержание, завершать, отправлять DTMF, получать ссылку на запись разговора. Для этого используется REST API (эндпоинт /rest/v1/uc/calls) и WebSocket.

Документация: полное описание событий звонка (invite, dlg_start, dlg_stop, hold, unhold, referring_invite, records_moved) и примеры запросов — в статье «Управление звонками через API» на wiki.

WebSocket песочница

Для отладки интеграций в платформу встроен инструмент — WebSocket песочница. Он позволяет подключаться к WebSocket (User-API или Token-API), настраивать соединение, авторизоваться, читать данные классов, подписываться на изменения, выполнять операции insert/update/delete, вызывать сервисы и вручную отправлять сообщения. Есть готовые шаблоны: «Мой статус», «Управление звонками», «Мои архивные звонки» и другие.

Документация: пошаговое руководство — в статье «WebSocket песочница» на wiki.

Что не рекомендуется делать

• Не редактируйте current-классы напрямую (CurrentCalls, CurrentUserStates) — используйте инвокейшены (SetReady, AnswerCall и т.д.), иначе подписчики не получат уведомления.
• Не пытайтесь получить все записи за один раз — используйте пагинацию (limit/offset).
• Не храните токены в клиентском коде.
• Не делайте синхронные вызовы внешних API внутри критического пути звонка дольше 3 секунд.

Практические примеры (из демонстрации)

На вебинаре показали базовые операции через REST API в Postman: получение списка записей, фильтрацию, сортировку, создание записи (POST), частичное обновление (PATCH), удаление. Также продемонстрировали управление статусом оператора (SetNotReady, SetReady) и отправку внутренних уведомлений. Работа с AI: отправка сообщения модели, продолжение диалога в контексте. Управление звонками через WebSocket в песочнице: ответ на звонок, удержание, завершение.

Важно: для изменения статусов пользователей вызывайте инвокейшены, а не прямые изменения классов — иначе заинтересованные подписчики не получат обновления.

Материалы вебинара

Запись вебинара на VK Video: Смотреть

Презентация: Скачать