Платформа
Программный интерфейс
Интерфейс предназначен для встраивания платформы в существующие системы организации: отправка уведомлений из документооборота, создание встреч из календаря, получение записей, синхронизация справочника сотрудников.
Получение доступа
Ключ выдаётся организации по заявке, в которой указываются назначение интеграции, состав обрабатываемых данных и ответственное лицо. Ключ ограничен областью действия: набор методов, перечень диалогов и каналов, максимальная частота обращений. Тестовый ключ работает в изолированном контуре с ограниченным числом учётных записей.
Все обращения выполняются по защищённому соединению, ключ передаётся в заголовке Authorization. Ключ, оказавшийся в открытом доступе, отзывается: платформа отслеживает публикации ключей в общедоступных репозиториях.
Основные методы
| Метод | Назначение | Область доступа |
|---|---|---|
| POST /messages | Отправка сообщения в диалог или канал | messages:write |
| GET /messages | Получение сообщений диалога с пагинацией | messages:read |
| POST /meetings | Создание встречи, возврат ссылки и кода | meetings:write |
| GET /meetings/{id}/records | Записи и стенограмма после завершения | meetings:read |
| POST /broadcasts | Подготовка эфира, выдача ключа потока | broadcasts:write |
| POST /files | Загрузка файла частями | files:write |
| GET /directory/users | Справочник сотрудников организации | directory:read |
| POST /channels/{id}/posts | Публикация в канале с сегментацией | channels:write |
Пример обращения
Отправка уведомления в диалог
HTTPPOST /v1/messages HTTP/1.1
Host: api.altaterra-vologda.ru
Authorization: Bearer <ключ организации>
Content-Type: application/json
Idempotency-Key: 7f14c0a2-doc-48219
{
"chat_id": "ch_5518204",
"text": "Документ № 48-219 поступил на согласование. Срок — 28 июля.",
"attachments": [{ "file_id": "fl_9a02c7" }],
"actions": [
{ "label": "Открыть документ", "url": "https://edo.example.ru/d/48219" }
],
"silent": false
}
HTTP/1.1 201 Created
{
"id": "ms_7710482",
"chat_id": "ch_5518204",
"created_at": "2026-07-24T11:04:18+03:00",
"delivery": "queued"
}
Заголовок Idempotency-Key обязателен для методов, создающих объекты: повторный запрос с тем же значением возвращает ранее созданный объект, а не создаёт второй. Это защищает от дубликатов при повторе после сетевой ошибки.
Вебхуки
Платформа сообщает о событиях запросом на указанный организацией адрес. Подпись передаётся в заголовке X-Vesta-Signature и проверяется получателем по общему секрету. Неподтверждённая доставка повторяется с возрастающим интервалом в течение 24 часов.
| Событие | Когда возникает |
|---|---|
| message.created | Новое сообщение в отслеживаемом диалоге |
| meeting.started | Встреча началась |
| meeting.ended | Встреча завершена, доступен список участников |
| record.ready | Запись и стенограмма обработаны |
| broadcast.live | Приём сигнала эфира начался |
| user.deactivated | Сотрудник исключён из справочника |
Справочник и единый вход
Синхронизация сотрудников выполняется по протоколу SCIM 2.0: создание, изменение и отключение учётных записей, состав подразделений, должности. Единый вход поддерживается по SAML 2.0 и OpenID Connect с сопоставлением подразделений и групп доступа. Настройка выполняется администратором организации без обращения в поддержку.
Лимиты и ошибки
| Код | Значение | Что делать |
|---|---|---|
| 400 | Ошибка в составе запроса | Проверить поля, описание — в теле ответа |
| 401 | Ключ отсутствует или отозван | Проверить ключ, при необходимости запросить новый |
| 403 | Недостаточная область доступа | Запросить расширение области у оператора |
| 409 | Конфликт: объект уже создан | Использовать возвращённый идентификатор |
| 429 | Превышена частота обращений | Повторить после срока в заголовке Retry-After |
| 503 | Служба временно недоступна | Повторить с возрастающим интервалом |
Базовый лимит — 600 запросов в минуту на организацию и 60 запросов в минуту на отдельный диалог. Отправка одинакового текста большому числу получателей рассматривается как рассылка и требует использования канала, а не метода отправки сообщений.
Библиотеки
Поддерживаемые библиотеки: Python, Java, C#, Go, JavaScript для серверного окружения. Библиотеки берут на себя повторы, идемпотентность, проверку подписи вебхуков и постраничную выборку. Исходный код открыт, обновления выходят вместе с версиями интерфейса; предыдущая версия интерфейса поддерживается 12 месяцев после выхода следующей.