Как работает интеграция Max с 1С

Февраль 2026 · Редакция «Арете-ИТ»

Отправить тестовое сообщение из 1С можно одной процедурой. Рабочая интеграция устроена шире: она сопоставляет пользователей, принимает события, вызывает разные методы API, повторяет неудачные операции и оставляет понятный журнал. Всё это можно собрать на штатных объектах платформы — без внешней службы и без привязки к конкретной конфигурации.

Сопоставление пользователей

Max присылает user_id и доступные поля профиля отправителя. В 1С этому идентификатору нужно сопоставить сотрудника, контрагента или отдельную карточку пользователя мессенджера. Имени для надёжного сопоставления недостаточно: оно меняется и не обязано быть уникальным.

Минимальная модель — регистр сведений с измерениями «бот» и «идентификатор Max», ресурсом «пользователь 1С». Если одному человеку можно писать через несколько ботов, измерение «бот» позволяет отдельно хранить факт начатого диалога и настройки связи. Для групп и каналов заведите отдельное соответствие по chat_id.

Связь удобно создавать после bot_started: пользователь запускает бота по персональной ссылке или вводит одноразовый код из 1С. Сам бот не может первым открыть личный диалог, поэтому заранее заполненный user_id ещё не гарантирует доставку.

События: опрос или webhook

Два официальных способа. GET /updates можно использовать при разработке: не нужен доступный снаружи HTTP-сервис. Для рабочей эксплуатации Max требует webhook, поскольку long polling ограничен по скорости и сроку хранения событий. При активной подписке webhook метод GET /updates не работает.

Для webhook используется POST /subscriptions: публичный HTTPS-адрес на порту 443, сертификат доверенного УЦ или Минцифры и ответ HTTP 200 не позднее чем через 30 секунд. Если при подписке указан secret, каждый запрос нужно сверять с заголовком X-Max-Bot-Api-Secret. После неудачной доставки Max делает до десяти повторов и через восемь часов без успешного ответа снимает подписку.

На стороне 1С webhook принимает HTTP-сервис. Он сравнивает секрет, читает JSON, сохраняет событие в очередь и возвращает 200. Проведение документов, построение отчётов и обращения к Max лучше выполнять уже после ответа: endpoint обязан уложиться в 30 секунд.

Функция Webhook(Запрос)

	Секрет = Запрос.Заголовки.Получить("X-Max-Bot-Api-Secret");
	Если Секрет <> "ваш_secret_из_подписки" Тогда
		Возврат Новый HTTPСервисОтвет(403);
	КонецЕсли;

	Событие = Неопределено;
	ЧтениеJSON = Новый ЧтениеJSON;
	ЧтениеJSON.УстановитьСтроку(Запрос.ПолучитьТелоКакСтроку());
	Событие = ПрочитатьJSON(ЧтениеJSON);
	ЗаписатьСобытиеMaxВОчередь(Событие); // Собственная процедура записи в регистр.

	// Ответ 200 нужно вернуть за 30 секунд, иначе Max начнёт повторные доставки.
	// Разбор update_type и прикладную обработку выполнит фоновое задание.

	Возврат Новый HTTPСервисОтвет(200);

КонецФункции

Если для теста выбран GET /updates, сохраняйте возвращённый marker после успешной записи событий. При пустом marker API отдаёт только последнее обновление, а передача нового marker отмечает предыдущие как прочитанные.

Общий модуль для запросов к API

Кроме отправки текста бот загружает файлы, отвечает на callback, редактирует сообщения и управляет чатами. У каждого метода свои параметры пути, query и тела. Если собирать HTTP-запрос в каждой процедуре, правила авторизации и обработки ошибок быстро начнут расходиться.

Вынесите в серверный общий модуль четыре операции: создание соединения, сериализацию JSON, выполнение запроса и проверку ответа. Токен передавайте только в заголовке Authorization, JSON — в UTF-8 без BOM. В вызывающий код возвращайте разобранный ответ, а при ошибке сохраняйте HTTP-код и исходное тело.

Практические заготовки есть в статьях про текстовое сообщение и файл. Вторая содержит законченную процедуру с POST /uploads, multipart и POST /messages, собранную только на стандартных средствах 1С.

Очередь и повторные попытки

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

Повторяйте только временные ошибки: недоступность сети, 429, 503 и attachment.not.ready. Ошибку авторизации 401 бессмысленно гонять по кругу — задание нужно остановить и сообщить администратору. Соблюдайте два независимых ограничения: не более двух сообщений в секунду в один диалог и не более 30 запросов в секунду к platform-api2.max.ru.

Кеш и журнал

Фраза «бот не ответил» ничего не говорит о причине. Для расследования нужны входящее событие, параметры метода, код и тело ответа, число повторов и связь с рассылкой. Отдельно стоит фиксировать marker long polling и состояние файлового token. Сам токен бота и персональные данные в журнал без маскирования записывать не следует.

Часто отправляемые вложения можно кешировать по контрольной сумме двоичных данных: хранить token, тип и имя файла в регистре сведений. Настройки и HTTP-соединения допустимо держать в повторно используемом модуле, если при изменении настройки предусмотрен явный сброс.

Что уже собрано в «Арете — сервер мессенджеров, Max edition»

В подсистеме описанная схема представлена готовыми метаданными: пользователи и чаты, настройки ботов, методы Max, списки получателей, рассылки и журнал. Входящий HTTP-сервис проверяет секрет и направляет событие в нужный обработчик, а общий модуль собирает запрос и раскладывает параметры по пути, query и JSON.

Настройки, соединения и маршруты кешируются с управляемым сбросом; токены файлов хранятся по контрольной сумме. Это та же архитектура, которую можно собрать вручную по шагам выше, но уже оформленная как расширение и пригодная для нескольких ботов.

Полный состав показан на странице продукта, первая настройка — в пошаговом руководстве.

Читать дальше