Как написать HTTP-сервис в 1С: практическое руководство

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

Механизм доступен в управляемом приложении и работает через публикацию на веб-сервере (IIS или Apache). Внешняя система отправляет запрос на заранее заданный URL, 1С выполняет код обработчика и возвращает ответ — обычно в формате JSON. Ниже разобран полный цикл: от создания объекта в конфигураторе до проверки работоспособности и защиты от типовых ошибок.

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

Когда HTTP-сервис подходит, а когда лучше выбрать другое

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

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

Сравнение вариантов интеграции

HTTP-сервис

Гибкий формат запросов и ответов, полный контроль логики. Требует кода и публикации на веб-сервере.

OData

Стандартный интерфейс без программирования, подходит для чтения данных. Слабо подходит для сложной бизнес-логики.

Планы обмена

Гарантированная доставка между базами 1С, но не предназначены для произвольных внешних систем.

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

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

Обратите внимание на свойство «Повторное использование сеансов». Значение «Использовать» ускоряет обработку запросов за счёт переиспользования сеансов, но требует аккуратности с состоянием. Для простых сервисов безопаснее оставить «Не использовать» — каждый запрос будет обрабатываться в чистом контексте.

Настройка шаблонов URL и методов

Внутри HTTP-сервиса создайте шаблон URL — он определяет структуру адреса. Например, шаблон /goods/{id} позволит принимать запросы вида /api/goods/000000001, где часть в фигурных скобках станет параметром, доступным в коде через Запрос.ПараметрыURL["id"]. Допустимы шаблоны из нескольких сегментов: /orders/{number}/status.

Для каждого шаблона добавьте методы — HTTP-глаголы, которые будет обрабатывать сервис. Чаще всего используются GET (получение данных) и POST (создание или изменение). В свойствах метода укажите обработчик — имя функции, которую платформа создаст в модуле HTTP-сервиса.

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

Код обработчика: приём запроса и формирование ответа

Функция-обработчик получает один параметр — объект HTTPСервисЗапрос, а возвращает объект HTTPСервисОтвет. Из запроса доступны параметры URL, параметры строки запроса (ПараметрыЗапроса), заголовки и тело. Типовой обработчик GET выглядит так:

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

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

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

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

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

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

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

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

Для публикации на IIS потребуются права администратора и установленные компоненты расширения веб-сервера 1С. На Apache проверьте, что модуль расширения подключён и версия веб-сервера совместима с вашей версией платформы. После публикации перезапустите веб-сервер, чтобы изменения вступили в силу.

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

Базовый уровень — аутентификация средствами платформы: в файле публикации (default.vrd) включается проверка пользователей 1С, и внешняя система передаёт логин и пароль через Basic-аутентификацию. Создайте отдельного пользователя с минимально необходимыми правами — только на те объекты, которые реально нужны сервису.

Дополнительные меры: ограничение доступа по IP на уровне веб-сервера или файрвола, работа только по HTTPS, проверка токена в заголовке запроса внутри обработчика. Не храните пароли в коде обработчика и не передавайте их в URL — параметры адресной строки попадают в логи веб-сервера.

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

Простейшая проверка GET-метода — открыть адрес в браузере: http://сервер/база/hs/api/goods/000000001. Для POST и запросов с заголовками удобнее Postman или curl. Ответ 200 с корректным JSON означает, что цепочка «веб-сервер → платформа → обработчик» работает.

Если приходит ошибка 404 — проверьте, отмечен ли сервис на закладке публикации и совпадает ли корневой URL с адресом запроса (учитывайте регистр и слэши). Ошибка 401 указывает на проблему аутентификации, 500 — на исключение в коде обработчика; текст исключения ищите в журнале регистрации. Для пошаговой отладки включите в конфигураторе отладку по протоколу HTTP (Отладка → Подключение → HTTP-сервисы) и поставьте точку останова в обработчике.

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

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

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

Норма

Код 200 и ожидаемый JSON в теле ответа

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

404 — сервис не опубликован или неверный URL; 401 — ошибка аутентификации

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

Норма

Нет ошибок при выполнении запроса

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

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

Кодировка ответа

Норма

Кириллица читается корректно

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

Кракозябры — не задан charset в Content-Type

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

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

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

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

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

Да, но только если файловая база опубликована на веб-сервере. Без публикации механизм не работает. Для нагруженных сценариев файловый режим не рекомендуется — используйте клиент-серверный вариант.

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

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

Почему запрос возвращает 404, хотя сервис создан?

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

Как передать в ответе файл, например PDF?

Используйте метод УстановитьТелоИзДвоичныхДанных объекта HTTPСервисОтвет и укажите соответствующий Content-Type, например application/pdf. Двоичные данные получают из хранилища значения или с диска сервера.

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

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

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

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