HTTP-сервис в 1С: что это и как его использовать

HTTP-сервис в 1С — это объект конфигурации, который позволяет информационной базе принимать и обрабатывать HTTP-запросы извне: от других программ, мобильных приложений, сайтов и внешних информационных систем. Проще говоря, это способ превратить 1С в полноценный сервер API: внешняя система отправляет запрос по адресу вида https://server/base/hs/exchange/orders, а 1С выполняет нужный код и возвращает ответ — например, данные в формате JSON.

Механизм появился в платформе 1С:Предприятие 8.3 и стал стандартным инструментом интеграции. До этого для обмена по HTTP приходилось использовать веб-сервисы (SOAP) или внешние компоненты. HTTP-сервисы проще, гибче и лучше подходят под современную архитектуру REST API, поэтому именно их выбирают для связи 1С с интернет-магазинами, CRM, мобильными приложениями и складскими системами.

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

Как устроен HTTP-сервис в конфигурации 1С

В дереве конфигурации HTTP-сервисы находятся в ветке «Общие» → «HTTP-сервисы». Каждый сервис состоит из корневого URL (например, exchange) и набора шаблонов URL — они определяют, какие адреса будет обрабатывать сервис. Шаблон может содержать параметры: шаблон /orders/{id} примет запрос /orders/123, и значение 123 станет доступно в коде как параметр.

Для каждого шаблона URL создаются методы — обработчики конкретных HTTP-глаголов: GET, POST, PUT, DELETE, PATCH и других. В модуле метода пишется код на встроенном языке 1С, который получает объект HTTPСервисЗапрос и должен вернуть объект HTTPСервисОтвет. Из запроса можно прочитать тело, заголовки, параметры строки запроса и параметры шаблона URL.

Логика обработки полностью на вашей стороне: внутри метода можно читать и записывать данные базы, вызывать запросы, формировать документы, запускать регламентные операции. Единственное требование — вернуть корректный HTTP-ответ с кодом состояния (200, 400, 404, 500 и т.д.) и, при необходимости, телом ответа.

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

В 1С существуют два похожих механизма, и их часто путают. Веб-сервис (Web-сервис) работает по протоколу SOAP: обмен идёт строго в формате XML, структура описывается через WSDL, а клиент обычно генерируется автоматически по этому описанию. HTTP-сервис ничего этого не требует — формат запроса и ответа вы определяете сами, чаще всего это JSON или обычный текст.

На практике выбор простой: если интеграция строится с современными системами (интернет-магазин, мобильное приложение, Telegram-бот, облачный сервис), берите HTTP-сервис. Веб-сервисы оправданы, когда внешняя система умеет работать только по SOAP или требует WSDL для автоматической генерации клиента.

Как создать HTTP-сервис: пошагово

Создание сервиса выполняется в конфигураторе и занимает несколько минут. Ниже — типовой порядок действий для сервиса, который будет возвращать данные о номенклатуре.

1. 1
   В конфигураторе откройте ветку «Общие» → «HTTP-сервисы» и добавьте новый объект, задайте имя, например «КаталогAPI».
2. 2
   В свойстве «Корневой URL» укажите префикс, например «catalog» — все адреса сервиса начнутся с /hs/catalog/.
3. 3
   Добавьте шаблон URL, например «/goods/*» или «/goods/{Код}» для передачи параметра.
4. 4
   В шаблоне добавьте метод GET и откройте его модуль для написания обработчика.
5. 5
   Напишите код: прочитайте параметры запроса, получите данные из базы, сформируйте HTTPСервисОтвет с кодом 200 и телом в JSON.
6. 6
   Опубликуйте базу на веб-сервере (Администрирование → Публикация на веб-сервере), отметив флаг публикации HTTP-сервисов.
7. 7
   Проверьте работу запросом из браузера или curl: https://сервер/база/hs/catalog/goods/000001.

Минимальный обработчик метода выглядит так:

Функция ТоварыПолучить(Запрос)
КодТовара = Запрос.ПараметрыURL["Код"];
Товар = Справочники.Номенклатура.НайтиПоКоду(КодТовара);

Ответ = Новый HTTPСервисОтвет(200);
Ответ.Заголовки["Content-Type"] = "application/json; charset=utf-8";

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

Данные = Новый Структура;
Данные.Вставить("code", КодТовара);
Данные.Вставить("name", Строка(Товар));

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

Возврат Ответ;
КонецФункции

Обратите внимание: функция обязательно должна вернуть объект HTTPСервисОтвет. Если код завершится исключением, платформа вернёт клиенту ошибку 500 с текстом исключения — поэтому критичные участки стоит оборачивать в попытку/исключение и возвращать осмысленные коды ошибок.

Публикация на веб-сервере и проверка работы

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

Итоговый адрес сервиса складывается из трёх частей: адрес публикации базы + /hs/ + корневой URL сервиса и шаблон. Например, если база опубликована как https://server/trade, корневой URL сервиса — catalog, а шаблон — /goods/{Код}, полный адрес будет https://server/trade/hs/catalog/goods/000001. Префикс hs зарезервирован платформой именно для HTTP-сервисов (у веб-сервисов — ws).

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

Как проверить, что сервис работает

Запрос GET из браузера на адрес сервиса

Норма

Возвращается ожидаемый JSON или текст с кодом 200

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

Ошибка 404 — сервис не опубликован или неверный URL; ошибка 500 — исключение в коде обработчика

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

Норма

Нет ошибок, связанных с вызовом сервиса

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

Записи об ошибках в модуле метода — смотрите текст исключения

Ответ при неверном параметре

Норма

Возвращается осмысленный код 400 или 404 с описанием

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

Падение с 500 и раскрытием внутреннего текста ошибки

Для отладки удобно использовать отладку HTTP-сервисов в конфигураторе: включите в настройках отладки пункт «Отладка по протоколу HTTP» и установите флаг автоматического подключения HTTP-сервисов — тогда точки останова в модуле метода будут срабатывать при внешних вызовах.

Аутентификация и безопасность

Опубликованный HTTP-сервис доступен из сети, поэтому вопрос защиты — не опция, а обязательное требование. По умолчанию при обращении к сервису веб-сервер запрашивает аутентификацию пользователя 1С: логин и пароль передаются в заголовке Basic-аутентификации. Это работает, но требует хранить реальные учётные данные во внешней системе.

Более управляемый подход — создать отдельного служебного пользователя 1С с минимально необходимыми правами только на те объекты, которые нужны сервису. Никогда не публикуйте сервисы под пользователем с полными правами: при утечке логина злоумышленник получит полный доступ к базе.

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

Типичные сценарии применения

Чаще всего HTTP-сервисы 1С используются для интеграции с интернет-магазинами: сайт запрашивает остатки и цены, а 1С получает новые заказы. Второй массовый сценарий — мобильные приложения для сотрудников: торговые представители отправляют заказы с планшета, курьеры отмечают доставку, руководители смотрят показатели.

Также сервисы применяют для приёма вебхуков от внешних систем (уведомления об оплате, события телефонии, статусы доставки), обмена между распределёнными базами 1С без COM и OLE, интеграции с весовым и складским оборудованием, а также как лёгкий API для BI-систем и отчётных инструментов.

Что выбрать для интеграции с 1С

HTTP-сервис 1С

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

Веб-сервис (SOAP)

Когда внешняя система умеет только SOAP или требует WSDL. Больше служебного трафика, меньше гибкости.

План обмена / файловый обмен

Когда системы не могут вызывать друг друга напрямую или нужен офлайн-режим. Данные передаются с задержкой, а не в реальном времени.

Подключение из 1С к чужому API

Когда 1С должна сама инициировать обмен: используйте HTTPСоединение на клиенте/сервере без публикации сервисов.

Ограничения и типичные ошибки

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

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

Частые вопросы

Можно ли использовать HTTP-сервис в файловой базе без веб-сервера?

Нет. HTTP-сервис обрабатывает запросы, которые принимает веб-сервер (IIS или Apache) и передаёт платформе. Без публикации базы обратиться к сервису невозможно. Для локальных сценариев без веб-сервера подойдут другие механизмы: COM-соединение, файловый обмен или внешние обработки по расписанию.

Какой формат данных лучше использовать для ответов?

Чаще всего JSON: он компактен, легко читается и нативно поддерживается практически всеми языками и системами. В 1С для работы с ним есть объекты ЧтениеJSON/ЗаписьJSON и функции ПрочитатьJSON/ЗаписатьJSON. XML имеет смысл, если его требует внешняя система.

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

Файл передаётся в теле запроса методом POST или PUT. В обработчике тело читается через метод ПолучитьТелоКакДвоичныеДанные() объекта запроса, после чего данные можно сохранить в хранилище значений, присоединённые файлы или на диск. При отдаче файла используйте УстановитьТелоИзДвоичныхДанных() и заголовок Content-Type, соответствующий типу файла.

Чем отличаются параметры URL от параметров запроса?

Параметры URL (ПараметрыURL) — это значения, подставленные в шаблон адреса, например {Код} в шаблоне /goods/{Код}. Параметры запроса (ПараметрыЗапроса) — это пары «ключ=значение» после знака вопроса в адресе: ?date=...&limit=.... Первые обычно идентифицируют ресурс, вторые — уточняют выборку или фильтрацию.

Нужна ли отдельная лицензия 1С для HTTP-сервисов?

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

Что делать, если сервис возвращает ошибку 500?

Ошибка 500 означает необработанное исключение в коде обработчика. Посмотрите журнал регистрации — там будет текст ошибки и место в коде. Затем включите отладку HTTP-сервисов в конфигураторе и повторите запрос с точкой останова в модуле метода. После исправления оберните рискованные участки в Попытка/Исключение и возвращайте клиенту осмысленный код ошибки вместо падения.