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

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

Механизм появился как более гибкая альтернатива классическим web-сервисам на SOAP. Вместо жестких XML-конвертов разработчик сам определяет формат запроса и ответа — чаще всего это JSON, но можно работать с любыми данными: текстом, файлами, двоичным содержимым. Это делает HTTP-сервисы стандартным инструментом интеграции 1С с интернет-магазинами, CRM, банковскими системами и мобильными клиентами.

Работает схема так: в конфигураторе создается объект «HTTP-сервис», в нем описываются шаблоны URL и методы (GET, POST, PUT, DELETE и другие), для каждого метода пишется обработчик на встроенном языке. Затем база публикуется на веб-сервере (IIS или Apache), и входящие запросы по указанным адресам попадают в эти обработчики.

Чем HTTP-сервис отличается от web-сервиса (SOAP)

В 1С исторически существует два механизма приема внешних запросов: web-сервисы и HTTP-сервисы. Web-сервис работает по протоколу SOAP: строгое описание интерфейса через WSDL, обмен XML-пакетами фиксированной структуры, автоматическая генерация клиентского кода. Это удобно для интеграции «система — система», когда обе стороны поддерживают SOAP, но избыточно для легковесных клиентов.

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

Как создать HTTP-сервис в конфигураторе

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

Далее внутри сервиса создаются шаблоны URL — это маски адресов, например /goods/{id} или /orders/*. Параметры в фигурных скобках передаются в обработчик как именованные значения, звездочка означает произвольное окончание пути. Для каждого шаблона добавляются методы (GET, POST и т.д.), а для метода указывается процедура-обработчик в модуле сервиса.

1. 1
   В конфигураторе откройте Общие → HTTP-сервисы и добавьте новый объект
2. 2
   Укажите корневой URL, например api
3. 3
   Добавьте шаблон URL, например /goods/{id}
4. 4
   Добавьте метод GET и задайте имя обработчика
5. 5
   Напишите код обработчика в модуле HTTP-сервиса
6. 6
   Обновите конфигурацию базы данных
7. 7
   Опубликуйте базу на веб-сервере с включенной публикацией HTTP-сервисов

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

Обработчик — это функция в модуле HTTP-сервиса, которая принимает объект ЗапросHTTP (или HTTPСервисЗапрос) и должна вернуть объект HTTPСервисОтвет. Из запроса доступны параметры URL, параметры строки запроса, заголовки и тело. Ответ формируется вручную: указывается код состояния, тело и при необходимости заголовки.

Типичный обработчик чтения данных выглядит так: извлечь параметр из URL, найти объект в базе, сериализовать его в JSON через ЗаписьJSON, вернуть ответ с кодом 200. Если объект не найден — вернуть код 404 с понятным описанием ошибки. Оборачивать логику в попытку/исключение обязательно: необработанное исключение вернет клиенту код 500 без внятного пояснения.

Функция ПолучитьТовар(Запрос)
    Ответ = Новый HTTPСервисОтвет(200);
    КодТовара = Запрос.ПараметрыURL["id"];
    Ссылка = Справочники.Номенклатура.НайтиПоКоду(КодТовара);
    Если Ссылка.Пустая() Тогда
        Ответ.КодСостояния = 404;
        Ответ.УстановитьТелоИзСтроки("{\"error\": \"Товар не найден\"}");
        Возврат Ответ;
    КонецЕсли;
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, Новый Структура("Наименование", Ссылка.Наименование));
    Ответ.УстановитьТелоИзСтроки(ЗаписьJSON.Закрыть());
    Ответ.Заголовки.Вставить("Content-Type", "application/json");
    Возврат Ответ;
КонецФункции

Для методов POST и PUT тело запроса читается через Запрос.ПолучитьТелоКакСтроку() или ПолучитьТелоКакПоток(), после чего разбирается через ПрочитатьJSON. Перед записью данных в базу входные значения нужно проверять: обязательность полей, типы, существование связанных ссылок.

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

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

После публикации адрес сервиса строится по схеме: http://сервер/имя_публикации/hs/корневой_url/путь_шаблона. Сегмент «hs» — служебный признак обращения именно к HTTP-сервисам (для web-сервисов используется «ws»). Проверить доступность можно простым GET-запросом из браузера или утилиты curl.

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

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

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

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

Базовая проверка — отправить GET-запрос браузером или curl и убедиться, что приходит ожидаемый ответ с правильным кодом. Если возвращается 404, чаще всего не совпадает корневой URL или шаблон, либо сервис не опубликован. Ошибка 500 указывает на исключение в обработчике — причина ищется в журнале регистрации. Отказ в доступе (401/403) означает проблему с аутентификацией или правами пользователя.

Для отладки удобно временно добавить в обработчик запись входящих параметров в журнал регистрации через ЗаписьЖурналаРегистрации — это показывает, что реально пришло от клиента. После отладки избыточное логирование убирают: на нагруженном сервисе оно замедляет работу и раздувает журнал.

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

Интеграция с сайтом и интернет-магазином

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

Мобильные приложения и внешние клиенты

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

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