Вместо вступления: философия API-first

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

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

Принцип API-first означает: сначала проектируется и реализуется программный интерфейс, затем — визуальные элементы. Это даёт три вещи:

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

Модели авторизации: две стороны одной медали

Любая интеграция начинается с вопроса: «От чьего имени мы обращаемся?» У нас есть две чётко разделённые модели.

1. First Party (от имени пользователя)

Внешнее приложение работает от имени конкретного пользователя Эра. Это не абстрактная «система», а реальный оператор, супервизор или администратор. Вы используете его учётные данные (или токен, полученный после логина), и API проверяет права доступа именно этого человека.

Где это применяется? CRM-система, в которую встроена телефония (softphone внутри CRM), личный кабинет оператора, мобильное приложение для супервизора. CRM вызывает через User API метод перевода звонка — платформа проверяет, имеет ли оператор такое право, и выполняет действие.

Почему это безопасно? Если оператору отозвали права или он уволился — внешнее приложение автоматически теряет доступ. Никакой параллельной модели безопасности. В терминах ISO 18295 — управляемость, контроль процессов, корректная работа персонала с данными.

Для First Party вы обычно используете OAuth2 или получаете сессионный токен через WebSocket Login.

2. Third Party (от имени интеграционной точки)

Доступ выдаётся не человеку, а техническому каналу — Integration Point. Вы создаёте в платформе точку интеграции, получаете local token (GUID), и эта точка имеет свои собственные права (capabilities), настроенные администратором.

Где это применяется? Сервер-то-серверная интеграция: BI-система раз в час забирает сводку по звонкам; middleware (Kafka, RabbitMQ); боты, которые не являются операторами.

Подключение выполняется с заголовком Authorization: Bearer <integration-point-token>. В ответе ConnectionInfo вы получаете ownerType: "token", integrationPointId и список capabilities (например, rest, websocket, avr, ccs).

Главное отличие: First party — «действую от лица Иванова», Third party — «действую от точки интеграции "BI_Export"».

Транспорты: HTTP и WebSocket — не конкуренты, а партнёры

Многие интеграторы спрашивают: «Что лучше?» Это как сравнивать молоток и отвёртку. У каждой свой класс задач.

HTTP (REST API)

Классический запрос-ответ. Используйте, когда нужно получить список, создать карточку, обновить справочник, загрузить аудиозапись. Стандартные методы: GET, POST, PUT, PATCH, DELETE. Поддерживаются фильтрация, сортировка, пагинация, маскировка полей.

Пример:

GET /api/collection/Companies?filter={"name":{"$like":"%Альфа%"}}&limit=2&order=[{"property":"name","direction":"ASC"}]
Authorization: Bearer <token>

WebSocket (постоянное соединение)

Один раз открываете канал и держите его. По этому каналу можно подписаться на изменения любого класса, отправлять команды, получать мгновенные уведомления без постоянного polling. WebSocket в платформе Эра — полноценный транспорт для API-функций.

Integration Point: Революция в интеграциях (без бэкенда)

Integration Point (канал интеграции) — управляемая точка входа в платформу, которая может принимать данные по HTTP или WebSocket, авторизовываться по токену и передавать входящий JSON сразу в low-code сценарий. Вы настраиваете URL, токен (с возможностью срока действия), сценарий обработки и capabilities. Integration Point заменяет значительную часть кастомной бэкенд-разработки, особенно когда требования меняются каждый день. Это особенно ценно в проектной работе.

Автоматическое API для кастомных классов: магия билдера

Когда вы в билдере создаёте новый класс (сущность), платформа автоматически формирует для него REST API представление. Не нужно писать отдельные эндпоинты и мапперы. Сразу после сохранения класса вы можете через GET /api/collection/NewClass получить записи, через POST — создать, через PATCH — обновить. Срок внедрения новой функциональности для бизнеса сокращается с недель до часов.

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

Польская запись — способ описывать условия отбора, сортировки, группировки и другие параметры через структурированный JSON-формат вместо SQL. Почему не SQL? Прямой SQL создаёт риски: ошибки, перегрузка базы, SQL-инъекции. Внешняя система не пишет SQL, а работает через REST API.

Доступные параметры: фильтрация ($eq, $neq, $gt, $like, $in), сортировка (order), маскировка (mask), лимит и офсет (limit/offset), countOnly (только количество), агрегация (aggregation), группировка (groupBy).

Пример сложного запроса:

GET /api/collection/CallRecord?filter={"duration":{"$gt":30}}&groupBy=operatorId&aggregation={"count":"id"}

Служебные сценарии: визуальная логика интеграции

Служебные сценарии — это наш low-code движок. Вы создаёте цепочку блоков (узлов): принять JSON, обратиться к БД, вызвать REST API внешней системы, отправить уведомление. Сценарии могут запускаться по расписанию (CRON), по событию внутри платформы, по внешнему вызову через Integration Point, вручную.

Практический кейс (нормализация заявок из трёх источников): Сценарий принимает данные из интернет-магазина, CRM и мобильного приложения (в разных форматах), нормализует поля, создаёт унифицированную заявку и возвращает {"status": "ok", "id": ...}. Всё без единой строчки бэкенда.

Искусственный интеллект в сценариях: LLM как инструмент обработки данных

Мы встроили LLM (локальные или облачные) как обычный тип узла в сценарии. Выбираете блок «Вызвать LLM», указываете модель (Qwen, Llama, GPT), пишете промпт. Внешняя система (CRM) вообще не знает, какая модель используется.

Реальные кейсы из проектов:

• Определение пола по ФИО (для корректных обращений в исходящих SMS).
• Классификация заявки по тексту (техподдержка, продажи, жалоба).
• Приоритизация (анализ тональности и срочности).
• Определение часового пояса (чтобы не звонить ночью).
• Поиск зависших заявок (анализ истории и предложение действий).
• Оценка качества заполнения карточки (создание задачи на уточнение).

Платформа становится единым узлом доступа к AI для всей компании. Интеграция с AI через API работает просто: POST /api/ai/chat/completions с текстом — получаете ответ.

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

Платформа может сама инициировать запросы во внешние системы.

Асинхронные (уведомления)

Платформа отправляет POST во внешний URL, не блокируя основной процесс. События: завершился звонок, клиент написал в чат, изменился статус заявки.

Синхронные (запрос разрешения)

Платформа делает запрос и обязана дождаться ответа, чтобы решить, как действовать дальше. Пример: Перед звонком исходящей кампании сценарий обращается к внешней CRM: если {"allowed": false} — звонок отменяется. Синхронные запросы не должны быть долгими (рекомендуем не более 3 секунд).

Практическая работа с API: от простого к сложному

Примеры реальных операций, которые мы демонстрируем на вебинарах.

GET list с польской записью

GET /api/collection/SmartCompanies?limit=2&filter={"name":{"$like":"%Альфа%"}}

Ответ — JSON с записями и мета-информацией (total, limit, offset).

Создание записи (POST)

POST /api/collection/SmartCompanies
{"name": "Омега Интеграция", "city": "Казань"}

Частичное обновление (PATCH)

PATCH /api/collection/SmartCompanies/{id}
{"city": "Самара"}

Управление статусом оператора

POST /api/invocations/SetNotReady
{"userId": "operator_123", "reason": "Обед"}

Отправка уведомления оператору

POST /api/invocations/SendInternalNotification
{"userId": "operator_123", "message": "Привет, это сценарий"}

Работа с AI через API

POST /api/ai/chat/completions
{
  "model": "qwen3.5-32b-local",
  "messages": [{"role": "user", "content": "Привет! Как дела?"}]
}

Получение ссылки на запись разговора

GET /api/collection/CallRecord/{callId}/downloadLink

Ответ: {"url": "https://storage.era.com/temp/recording_123.mp3?expires=...", "expiresIn": 3600}. Ссылка одноразовая или живёт час.

Что категорически не рекомендуется делать (и почему)

• Не редактируйте current-классы напрямую (CurrentCalls, CurrentUserStates). Используйте инвокейшены (AnswerCall, SetReady), иначе внутренние подписчики не узнают об изменениях.
• Не пытайтесь получить все записи за один раз. Всегда используйте пагинацию: limit=100&offset=0, потом offset=100 и т.д.
• Не храните токены в коде клиентской части. Для веб-приложений используйте бэкенд-прокси.
• Не делайте синхронные вызовы внешних API внутри критического пути звонка. Если внешняя CRM отвечает 10 секунд — звонок «зависнет». Используйте асинхронные очереди.

Инструменты, которые облегчат жизнь интегратору

• WebSocket «Песочница» — встроенный инструмент для тестирования WebSocket-подключений, подписки на классы и выполнения инвокейшенов.
• Приложение «Объектная модель» — автоматическая документация по всем классам: поля, инвокейшены, связи. Генерируется автоматически.
• Postman коллекции — готовые коллекции для REST API с предустановленными заголовками и примерами.
• F12 в браузере — откройте любое веб-приложение Эра, перейдите на вкладку Network, и вы увидите все API-вызовы, которые можно использовать в своей интеграции.

Частые вопросы и ответы от команды поддержки

Вопрос: Нужна ли отдельная лицензия на интеграцию?
Ответ: В модели First Party — нет, вы используете лицензию пользователя. В модели Third Party — Integration Point не требует отдельной платной лицензии, но количество одновременных подключений может быть ограничено тарифом.

Вопрос: Как часто можно вызывать API? Есть ли лимиты?
Ответ: Платформа защищена от DDoS. По умолчанию: не более 100 запросов в секунду на один токен. Для массовых выгрузок используйте пагинацию и limit не более 1000.

Вопрос: Можно ли подписаться на события через WebSocket с другого сервера? Нужен ли публичный IP?
Ответ: WebSocket работает через тот же домен. Если платформа развёрнута в private cloud, WebSocket доступен внутри вашей сети. Если нет — настройте reverse proxy.

Вопрос: Как отладить служебный сценарий, который вызывается через Integration Point?
Ответ: В интерфейсе сценария есть кнопка «Трассировка». Также все вызовы через Integration Point логируются в разделе «Журнал интеграции».

Вопрос: Поддерживается ли OpenAPI (Swagger)?
Ответ: Да, по адресу /api/docs/swagger (если включено в настройках домена).

Заключение: Эра — это операционная система для контакт-центра

Платформа Эра — это не просто «колл-центр в коробке». Это среда разработки и интеграции, где каждый компонент доступен через API. Вы можете:

• Заменить стандартный интерфейс оператора на свой (через First Party API).
• Подключить ботов, аналитику, CRM, ERP (через Third Party и WebSocket).
• Автоматизировать бизнес-процессы без программирования (через служебные сценарии).
• Добавить искусственный интеллект в любой канал (через AI API).
• Создавать новые сущности и сразу иметь к ним API (через автоматическое REST).

Интеграция без компромиссов — это не маркетинговый слоган. Это обещание: если что-то можно сделать в интерфейсе — это можно сделать и через API. И часто даже быстрее.

Для начала — откройте Postman, вставьте свой токен и выполните первый GET. Увидите — всё работает именно так, как мы рассказываем.

Команда инженерной поддержки платформы Эра