Как создать HTTP-сервис в 1С: настройка, публикация и отладка

HTTP-сервис в 1С позволяет принимать запросы из внешних систем — сайтов, мобильных приложений, других учётных баз — и возвращать данные или выполнять действия прямо в информационной базе. Это стандартный механизм платформы, который не требует сторонних библиотек: достаточно конфигуратора, веб-сервера (IIS или Apache) и модуля расширения веб-сервера 1С.

Типовой сценарий выглядит так: внешняя система отправляет GET-запрос вида /hs/api/orders/123, платформа находит подходящий шаблон URL, вызывает ваш обработчик на встроенном языке, тот читает данные из базы и возвращает JSON. Вся маршрутизация и разбор запроса берёт на себя платформа — разработчику остаётся написать бизнес-логику.

Ниже разобран полный цикл: от создания объекта «HTTP-сервис» в конфигураторе до публикации на веб-сервере, проверки работоспособности и защиты от типовых ошибок. Материал подходит для управляемых приложений на платформе 8.3.

Что такое HTTP-сервис в 1С и когда он нужен

HTTP-сервис — объект метаданных, который связывает URL-шаблон с процедурой-обработчиком. В отличие от веб-сервисов (SOAP), он работает с произвольными форматами: JSON, XML, plain text, двоичные данные. Именно поэтому HTTP-сервисы стали стандартом для REST-подобных интеграций в экосистеме 1С.

Типичные задачи: приём заказов с сайта, выгрузка остатков и цен для маркетплейса, webhook от платёжной системы, мобильное приложение для курьеров, обмен между двумя базами 1С без COM-соединения. Если внешней системе нужно «спросить» базу или «сказать» ей что-то в реальном времени — HTTP-сервис подходит почти всегда.

Альтернативы стоит рассматривать осознанно. Веб-сервисы (SOAP) оправданы, если контрагент строго требует WSDL. Планы обмена лучше подходят для регулярной пакетной синхронизации, а не для мгновенных запросов. Файловый обмен через каталог — самый простой вариант, но без гарантий доставки и моментальности.

Создание объекта HTTP-сервиса в конфигураторе

Откройте конфигуратор, в дереве конфигурации перейдите в ветку Общие → HTTP-сервисы и добавьте новый объект. Задайте имя, например ИнтеграцияСайт, и ключевое свойство — Корневой URL, например api. Итоговый адрес сервиса будет иметь вид http://сервер/база/hs/api/... — префикс hs платформа добавляет автоматически.

Далее создайте шаблон URL. В свойстве «Шаблон» укажите путь относительно корневого URL, например /orders/{НомерЗаказа}. Внутри шаблона добавьте методы — HTTP-глаголы, которые будет обрабатывать этот шаблон: GET, POST, PUT, DELETE и другие. Для каждого метода укажите процедуру-обработчик — платформа создаст её заготовку в модуле HTTP-сервиса.

1. 1
   Создайте объект «HTTP-сервис» в ветке «Общие», задайте корневой URL
2. 2
   Добавьте шаблон URL с параметрами в фигурных скобках
3. 3
   Добавьте метод (GET или POST) и сгенерируйте обработчик
4. 4
   Напишите код обработчика: чтение параметров, логика, формирование ответа
5. 5
   Убедитесь, что роль пользователя веб-сервиса имеет права на нужные объекты
6. 6
   Опубликуйте базу на веб-сервере с флагом «Публиковать HTTP-сервисы»
7. 7
   Проверьте запрос из браузера или Postman

Написание обработчика метода

Обработчик — функция, которая принимает объект HTTPСервисЗапрос и должна вернуть объект HTTPСервисОтвет. Из запроса доступны параметры URL, параметры строки запроса (query string), заголовки и тело. Ответ создаётся конструктором с кодом состояния: 200 — успех, 400 — ошибка в данных запроса, 404 — объект не найден, 500 — внутренняя ошибка.

Пример обработчика GET, возвращающего данные заказа в JSON:

Функция ПолучитьЗаказ(Запрос)
НомерЗаказа = Запрос.ПараметрыURL["НомерЗаказа"];
Ответ = Новый HTTPСервисОтвет(200);
Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");

Заказ = Документы.ЗаказПокупателя.НайтиПоНомеру(НомерЗаказа, ТекущаяДатаСеанса());
Если Заказ.Пустая() Тогда
Ответ.КодСостояния = 404;
Ответ.УстановитьТелоИзСтроки("{""error"":""Заказ не найден""}");
Возврат Ответ;
КонецЕсли;

Данные = Новый Структура;
Данные.Вставить("number", НомерЗаказа);
Данные.Вставить("customer", Строка(Заказ.Контрагент));
Данные.Вставить("sum", Заказ.СуммаДокумента);

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Данные);
Ответ.УстановитьТелоИзСтроки(ЗаписьJSON.Закрыть());
Возврат Ответ;
КонецФункции

Для POST-запросов тело читается методом Запрос.ПолучитьТелоКакСтроку() и разбирается через ЧтениеJSON. Всегда оборачивайте разбор входных данных в попытку/исключение и возвращайте код 400 с понятным описанием ошибки — это сильно упрощает диагностику со стороны внешней системы.

Публикация на веб-сервере

Без публикации HTTP-сервис недоступен извне. В конфигураторе откройте Администрирование → Публикация на веб-сервере. Укажите имя публикации (латиницей, без пробелов), каталог для файлов публикации и обязательно установите флаг Публиковать HTTP-сервисы — по умолчанию он может быть снят, и это самая частая причина «неработающего» сервиса.

Для IIS потребуется установленный компонент «Модули расширения веб-сервера» из дистрибутива платформы и включённый ISAPI. Для Apache — подключённый модуль wsap24.dll (имя зависит от версии платформы) в конфигурации httpd.conf. После публикации платформа формирует файл default.vrd, где в секции <point name="..."> перечислены опубликованные сервисы.

Учётная запись, под которой работает пул приложений IIS или служба Apache, должна иметь доступ к каталогу информационной базы (для файлового режима) и право запускать процессы. Ошибки доступа на этом этапе проявляются как отказ в соединении или пустой ответ — проверяйте журналы веб-сервера в первую очередь.

Права доступа и аутентификация

Каждый запрос к HTTP-сервису выполняется от имени пользователя информационной базы. В файле публикации можно задать пользователя по умолчанию, либо требовать аутентификацию: тогда логин и пароль передаются в заголовке Authorization (basic auth) или через параметры строки подключения.

Правильный подход — создать отдельного пользователя, например WebService, и выдать ему роль с минимально необходимыми правами: чтение нужных справочников и документов, без доступа к интерфейсу и административным функциям. Никогда не публикуйте сервис под полными правами — уязвимость в обработчике превратится в полный доступ к базе.

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

Проверка работоспособности и отладка

Простейшая проверка — открыть GET-адрес сервиса в браузере: http://сервер/база/hs/api/orders/123. Если видите JSON — сервис работает. Код 404 означает, что не найден шаблон или не выполнена публикация; 401/403 — проблема с аутентификацией или правами; 500 — исключение в обработчике, смотрите журнал регистрации.

Для POST-запросов используйте Postman, curl или аналогичный инструмент — браузер тело запроса не отправит. Отладка обработчика выполняется стандартно: в конфигураторе включите Отладка → Подключение → HTTP-сервисы (автоматическое подключение), поставьте точку останова и отправьте запрос — сеанс отладки подхватит вызов.

Контрольные точки

Как проверить результат

Запрос из браузера/Postman

Норма

Код 200 и корректное тело ответа

Тревожный признак

404 (нет шаблона/публикации), 401/403 (права), 500 (ошибка в коде)

Файл default.vrd в каталоге публикации

Норма

Присутствует секция point с именем вашего сервиса

Тревожный признак

Секции нет — публикация выполнена без флага HTTP-сервисов

Журнал регистрации

Норма

Нет ошибок сеансов веб-сервиса

Тревожный признак

Исключения из обработчика с текстом ошибки

Права пользователя сервиса

Норма

Только необходимые объекты, без административных прав

Тревожный признак

Роль «Полные права» или доступ к лишним данным

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

Ограничения и производительность

HTTP-сервисы 1С не предназначены для высоконагруженных публичных API. Каждый запрос занимает сеанс и лицензию (в клиент-серверном режиме — сеансовую лицензию на время обращения). При десятках одновременных обращений возможны очереди и таймауты. Для тяжёлых операций принимайте запрос, ставьте задачу в очередь (регистр сведений, фоновое задание) и сразу возвращайте 202 с идентификатором задачи.

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

Маршрут решения

Как выбрать действие

Нужен разовый запрос данных извне в реальном времениHTTP-сервис с методом GET и минимальными правами

Внешняя система присылает документы пачками по расписаниюРассмотрите план обмена или файловый обмен вместо HTTP-сервиса

Ожидается высокая частота одновременных запросовВынесите тяжёлую логику в очередь, из сервиса возвращайте 202 и ID задачи

Контрагент требует строгий контракт WSDL/SOAPИспользуйте веб-сервисы 1С вместо HTTP-сервисов

Держите формат ответа стабильным: зафиксируйте состав полей JSON и никогда не удаляйте поля без версионирования. Проще всего добавить версию в корневой URL — /hs/api/v1/... — тогда изменение контракта не сломает уже работающие интеграции.

Часто задаваемые вопросы

Чем HTTP-сервис отличается от веб-сервиса (SOAP) в 1С?

Веб-сервис работает по протоколу SOAP с жёстким описанием WSDL и XML-конвертами. HTTP-сервис работает с произвольным содержимым запроса и ответа — обычно JSON. Для современных интеграций с сайтами и мобильными приложениями чаще выбирают HTTP-сервисы: они проще, легче и понятнее внешним разработчикам.

Почему сервис отвечает 404, хотя в конфигураторе всё создано?

Чаще всего при публикации не установлен флаг «Публиковать HTTP-сервисы» либо после изменения шаблонов не выполнена повторная публикация. Откройте файл default.vrd в каталоге публикации и убедитесь, что там есть секция с именем вашего сервиса. Также проверьте, что адрес набран с префиксом /hs/ и корневым URL.

Можно ли отлаживать обработчик HTTP-сервиса?

Да. В конфигураторе включите автоматическое подключение предметов отладки «HTTP-сервисы» (Отладка → Подключение), установите точку останова в обработчике и отправьте запрос. Сеанс отладки подключится автоматически. В клиент-серверном режиме отладка должна быть разрешена на сервере 1С.

Как передать файл через HTTP-сервис?

В теле POST-запроса — как двоичные данные, которые читаются методом ПолучитьТелоКакДвоичныеДанные(), либо в формате multipart/form-data с самостоятельным разбором. Для отдачи файла установите тело ответа методом УстановитьТелоИзДвоичныхДанных() и укажите корректный Content-Type, например application/pdf.

Расходуют ли HTTP-сервисы лицензии 1С?

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

Как защитить сервис, если база опубликована в интернете?

Минимальный набор: HTTPS, отдельный пользователь с узкой ролью, базовая аутентификация или проверка токена в обработчике, ограничение доступа по IP на веб-сервере. Дополнительно логируйте обращения и ограничивайте частоту запросов средствами веб-сервера.