Если у клиники есть своя разработка — портал пациента, мобильное приложение, самописная МИС — робота проще всего встроить через программный интерфейс. REST API Stexa даёт разработчику управлять звонками, записями и данными напрямую из своего кода: запустить обзвон, получить результат звонка, синхронизировать слоты. Разбираем, как устроена авторизация, какие есть методы и события и с чего начать интеграцию по API.
REST API — это программный интерфейс, через который разработчик клиники управляет голосовым роботом из своего кода: создаёт звонки, читает их результаты, передаёт данные о пациентах и слотах. Вместо ручных настроек в кабинете всё делается запросами. Это нужно там, где робот встраивается в собственные системы клиники — приложение, портал, самописную МИС.
Смысл API в гибкости: логику интеграции пишет сама клиника под свои процессы, а не подстраивается под готовые шаблоны.
Разберём авторизацию, основные группы методов, события через вебхуки и порядок подключения.
Готовые интеграции с YClients, amoCRM или Битрикс24 закрывают типовые задачи без единой строки кода — их и стоит выбирать, если клиника работает в этих системах. API нужен, когда у клиники своя разработка или нестандартный процесс, которого нет в готовых коннекторах. Тогда разработчик связывает робота напрямую.
Порог входа у API выше: нужен программист. Зато он снимает любые ограничения готовых сценариев.
Часто их сочетают: базовые связки берут из коробки, а уникальную логику дописывают через API.
Доступ к API открывается по секретному токену, который клиника получает в кабинете. Токен передаётся в заголовке каждого запроса и однозначно определяет, от чьего имени идёт вызов. Его нельзя публиковать в коде фронтенда или репозитории — он хранится на стороне сервера клиники. При компрометации токен отзывается и выпускается новый.
Токен даёт ровно те права, что нужны интеграции, — принцип минимально необходимого доступа снижает риск при утечке.
Для разных задач можно завести отдельные токены и отзывать их независимо, не ломая остальные интеграции.
Базовый набор методов покрывает жизненный цикл звонка: создать исходящий вызов на номер, получить статус и результат звонка, прочитать расшифровку разговора. Отдельная группа — записи: передать слоты, создать или перенести визит, отменить его. Этого достаточно, чтобы управлять роботом из своей системы под большинство сценариев клиники.
Каждый метод возвращает структурированный ответ, который разработчик разбирает в своём коде — например, статус «записан» или «недозвон».
Запросы идут по защищённому протоколу, а персональные данные пациентов передаются в соответствии с 152-ФЗ.
Не всё удобно опрашивать запросами — часть событий приходит сама через вебхуки. Клиника указывает адрес своего обработчика, и робот шлёт туда уведомления: звонок начался, завершился, пациент записался, дозвониться не удалось. Так система клиники узнаёт о событии в момент, когда оно случилось, без постоянных опросов API.
Вебхуки экономят запросы и дают реальное время: обработчик реагирует сразу, а не с задержкой очередного опроса. Событие приходит на вебхук за 1-2 секунды, а первый метод подключается примерно за 15 минут.
Каждое событие приходит с данными звонка — кто, когда, с каким итогом, — чтобы обработчик принял решение.
Если расписание живёт в собственной системе клиники, слоты отдаются роботу через API: разработчик передаёт свободные окна, а бот предлагает их пациентам и пишет запись обратно. Обмен двусторонний — изменение с любой стороны отражается на другой. Это позволяет держать единое расписание без ручной сверки между ботом и внутренней программой.
Двусторонний обмен важен, чтобы не возникало двойных записей на один слот из разных каналов.
Как в принципе устроена двусторонняя синхронизация записей, разобрано в гайде про двустороннюю синхронизацию.
API построен по привычным для разработчика принципам REST: запросы идут на понятные адреса методов, данные передаются в JSON, результат возвращается кодом ответа и телом. Ошибки приходят со стандартными кодами и описанием причины, поэтому их легко обрабатывать в коде. Специфического протокола учить не нужно — всё знакомо по любому современному API.
Единый формат JSON и на входе, и на выходе упрощает разбор: одна библиотека сериализации на все методы.
Понятные коды ошибок помогают быстро отличить проблему авторизации от неверных данных запроса.
Перед боевым запуском интеграцию отлаживают на тестовых данных, не тратя реальные звонки и не беспокоя пациентов. Разработчик проверяет сценарии, смотрит структуру ответов и вебхуков, ловит ошибки в своём коде. Только убедившись, что связка ведёт себя предсказуемо, её переключают на боевые звонки.
Отладка на тесте экономит деньги и репутацию: баг в коде не приведёт к странному звонку живому пациенту.
Логи запросов и событий помогают понять, что именно ушло роботу и что он вернул в спорных случаях.
Интеграция по API требует базовой гигиены безопасности: хранить токен на сервере, ходить по защищённому протоколу, проверять подпись входящих вебхуков и выдавать токену минимум прав. Персональные данные пациентов при обмене остаются в российском контуре, как требует 152-ФЗ. Эти правила закрывают основные риски самописной интеграции.
Проверка подписи вебхука защищает обработчик от поддельных уведомлений якобы от робота.
Общие требования к защите персональных данных в голосовых сервисах собраны в материале про 152-ФЗ и голосовые боты.
Частые ошибки — держать токен в коде фронтенда, опрашивать API вместо подписки на вебхуки и не обрабатывать коды ошибок. Первое грозит утечкой доступа, второе перегружает интеграцию лишними запросами, третье прячет сбои. Все три устраняются на этапе проектирования: секреты на сервере, события через вебхуки, честная обработка ответов.
Ещё ошибка — сразу лить боевые звонки без теста и получить массовый сбой на живых пациентах.
Общий обзор граблей внедрения собран в материале про ошибки при внедрении бота.
У API есть разумные лимиты на частоту запросов, чтобы одна интеграция не перегружала систему. Разработчику стоит закладывать их в код: обрабатывать ответ о превышении лимита и повторять запрос с паузой. Для событий лучше использовать вебхуки, которые не упираются в лимиты постоянного опроса.
Правильная работа с лимитами делает интеграцию устойчивой: она не падает под собственной нагрузкой в час пик звонков.
Массовые операции — например, большой обзвон — разбивают на порции, а не шлют одним всплеском запросов, который упрётся в лимит.
API развивается, поэтому методы версионируются: старые продолжают работать, а новые возможности приходят в новых версиях. Это защищает интеграцию клиники от внезапных поломок при обновлениях. Разработчику стоит следить за уведомлениями об изменениях и переходить на новые версии планово.
Обратная совместимость важна для медицины: интеграция, от которой зависит запись пациентов, не должна ломаться без предупреждения.
Планово обновляя версию на тесте перед боем, разработчик избегает сюрпризов на живых звонках пациентов.
Начните с получения токена в кабинете и простого запроса — например, создать один тестовый звонок и разобрать ответ. Затем подключите обработчик вебхуков и проверьте, что события приходят. После этого добавляйте методы записи и синхронизацию слотов под свой сценарий. Так интеграция собирается пошагово и предсказуемо.
Разумно сначала закрыть один сценарий целиком — например, обзвон с записью результата, — а потом расширять.
Попробовать API можно бесплатно 7 дней без карты и на тестовых звонках убедиться, что связка ведёт себя как нужно.
7 дней бесплатно, без карты. Подключение к вашему номеру за 15 минут.