HTTP-сервис в 1С 8.3 от пустой конфигурации до ответа 200

Чтобы запустить веб-сервис в 1С 8.3, нужны три вещи: HTTP-сервис в конфигурации (Общие → HTTP-сервисы), функция-обработчик метода в его модуле и публикация базы на веб-сервере через Администрирование → Публикация на веб-сервере в Конфигураторе. После этого сервис отвечает по адресу вида http://сервер/имя_публикации/hs/корневой_URL/шаблон.

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

Подготовка: что нужно до создания веб-сервиса

Сначала решите, какой сервис вы делаете. В 1С есть два механизма, и их часто путают.

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

Что подготовить:

• 🖥️ Веб-сервер. Apache 2.4 (или 2.2) либо IIS на Windows, Apache на Linux.
• 🧩 Модули расширения веб-сервера. Это компонент установщика платформы. Без него публикация не появится в Конфигураторе или не заработает.
• ⚖️ Одинаковая разрядность. 64-битный Apache работает с модулем 64-битной платформы, 32-битный — с 32-битной. Несовпадение даёт ошибку загрузки модуля при старте Apache.
• 🔑 Права администратора Windows. Конфигуратор для публикации запускают от имени администратора, иначе он не сможет записать файлы в каталог веб-сервера и в httpd.conf.
• 💾 Копия конфигурации. Сервис вы добавляете в конфигурацию, поэтому перед правкой выгрузите её через Конфигурация → Сохранить конфигурацию в файл. Для типовой базы на поддержке удобнее делать сервис в расширении конфигурации — так он переживёт обновление.

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

Откройте конфигурацию (Конфигурация → Открыть конфигурацию), в дереве разверните Общие, на ветке HTTP-сервисы нажмите Добавить.

Свойства самого сервиса

1. Имя — внутреннее имя объекта, например API.
2. Корневой URL — часть адреса после /hs/, например api. Латиница, без пробелов и слешей.
3. Повторное использование сеансов — Не использовать, Использовать или Автоматически. Для частых коротких запросов повторное использование снижает накладные расходы на открытие сеанса.
4. Время жизни сеанса — сколько секунд сеанс ждёт следующего запроса, если повторное использование включено.

Шаблоны URL и методы

Внутри сервиса добавьте шаблон URL — это путь после корневого адреса. В фигурных скобках задаются параметры:

• /ping — без параметров, для проверки «живой ли сервис»;
• /items/{code} — с параметром code, который потом читается в коде;
• /* — любой путь, если разбирать адрес будете сами.

У каждого шаблона создайте методы: GET, POST, PUT, DELETE и другие. В свойстве метода нажмите на лупу в поле Обработчик — Конфигуратор создаст в модуле сервиса пустую функцию вида ТоварGET(Запрос).

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

Функция-обработчик получает объект HTTPСервисЗапрос и обязана вернуть HTTPСервисОтвет. Из запроса доступны:

• Запрос.ПараметрыURL — параметры из шаблона ({code});
• Запрос.ПараметрыЗапроса — то, что после ? в адресе;
• Запрос.Заголовки — HTTP-заголовки;
• Запрос.ПолучитьТелоКакСтроку() — тело запроса, обычно JSON.

Пример GET: отдать товар по коду

Пример рассчитан на конфигурации со справочником Номенклатура (Бухгалтерия, УТ). Для другой базы замените справочник на свой.

Функция ТоварGET(Запрос)

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

	Если Товар.Пустая() Тогда
		Возврат ОтветJSON(404, Новый Структура("error", "Товар не найден"));
	КонецЕсли;

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

	Возврат ОтветJSON(200, Данные);

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

Функция ОтветJSON(КодСостояния, Данные)

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

	Ответ = Новый HTTPСервисОтвет(КодСостояния);
	Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
	Ответ.УстановитьТелоИзСтроки(Запись.Закрыть(), КодировкаТекста.UTF8,
		ИспользованиеByteOrderMark.НеИспользовать);

	Возврат Ответ;

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

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

Пример POST: принять JSON

Функция ТоварPOST(Запрос)

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

	Если Не Данные.Свойство("name") Тогда
		Возврат ОтветJSON(422, Новый Структура("error", "Не передано поле name"));
	КонецЕсли;

	// Здесь — создание или изменение объекта по данным Данные.name

	Возврат ОтветJSON(201, Новый Структура("result", "ok"));

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

ПрочитатьJSON без второго параметра возвращает Структура, поэтому проверка поля идёт через Свойство(). Если ключи в JSON могут быть кириллическими или с дефисом, читайте в соответствие: ПрочитатьJSON(Чтение, Истина), тогда проверка — через Получить().

Коды ответа выбирайте осознанно: 200 — успех, 201 — создано, 400 — кривой запрос, 404 — объект не найден, 422 — данные не прошли проверку. Внешней системе так проще понять, повторять запрос или нет.

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

Сервис в конфигурации ещё не доступен снаружи. Его открывает публикация.

1. Запустите Конфигуратор от имени администратора и откройте базу.
2. Выберите Администрирование → Публикация на веб-сервере.
3. Имя — имя публикации, оно станет частью адреса. Например trade.
4. Веб-сервер — выберите Apache 2.4, Apache 2.2 или IIS из найденных.
5. Каталог — папка, куда запишется файл default.vrd, например C:\Apache24\htdocs\trade.
6. Перейдите на вкладку HTTP-сервисы. Отметьте флаг публикации HTTP-сервисов и галочку у нужного сервиса в списке.
7. Нажмите Опубликовать и согласитесь на перезапуск веб-сервера.

Если галочка у сервиса на вкладке HTTP-сервисы не стоит, он отвечает 404, хотя публикация работает. Это самая частая причина «сервис не запускается» после первой публикации.

Для сервера без графического интерфейса или для скриптов развёртывания есть утилита webinst из каталога bin платформы:

webinst -publish -apache24 -wsdir trade -dir "C:\Apache24\htdocs\trade" -connstr "Srvr=srv1c;Ref=trade;" -confpath "C:\Apache24\conf\httpd.conf"

Для файловой базы строка подключения выглядит как File=D:\Bases\Trade;.

Флажки сервисов хранятся в default.vrd. Фрагмент, который отвечает за HTTP-сервисы, выглядит примерно так:

<httpServices publishByDefault="false">
    <service name="API" rootUrl="api" enable="true" reuseSessions="autouse" sessionMaxAge="20"/>
</httpServices>

При publishByDefault="false" работают только сервисы, перечисленные с enable="true". Если вы добавили новый сервис в конфигурацию, а публикацию не переделали, его в этом списке нет.

Права учётной записи веб-сервера

• Для файловой базы пользователь, от которого работает служба Apache или пул приложений IIS, должен иметь права на чтение и запись в каталог базы. Иначе — ошибка доступа к файлу 1Cv8.1CD.
• Для клиент-серверной базы веб-сервер ходит к агенту сервера 1С на порт 1540, далее к менеджеру кластера и рабочим процессам. Порты должны быть открыты между веб-сервером и сервером 1С.

Адрес веб-сервиса 1С и первая проверка доступности

Адрес собирается из четырёх частей:

http://<сервер>/<имя публикации>/hs/<корневой URL сервиса>/<шаблон>

Для примера выше:

• http://localhost/trade/hs/api/ping
• http://localhost/trade/hs/api/items/00-00000012

Начните с шаблона /ping, который просто возвращает 200 и строку ok. Он отсекает проблемы публикации от проблем в коде.

Проверка из командной строки (curl есть в Windows 10 и новее):

curl -i -u apiuser:Pa55word http://localhost/trade/hs/api/ping

Ключ -i показывает заголовки ответа: сразу видно код состояния. POST с телом:

curl -i -u apiuser:Pa55word -X POST -H "Content-Type: application/json" -d "{\"name\":\"Тест\"}" http://localhost/trade/hs/api/items/1

Те же запросы удобно собирать в Postman или Insomnia: там сохраняется история и проще менять тело. Проверьте адрес сначала с самого веб-сервера, потом с другой машины. Если локально работает, а снаружи нет — смотрите брандмауэр и привязку Apache к адресу (директива Listen).

Безопасность и права доступа к HTTP-сервису

По умолчанию сервис требует аутентификации пользователя 1С. Клиент передаёт логин и пароль заголовком Authorization по схеме Basic. Дальше код обработчика выполняется в сеансе этого пользователя, с его ролями.

Как сделать правильно:

1. Отдельный технический пользователь. Заведите в Администрирование → Пользователи (или в списке пользователей Конфигуратора) учётную запись только для интеграции. Не давайте внешней системе логин бухгалтера или администратора.
2. Минимальная роль. Создайте роль, где есть только чтение и запись нужных объектов. Если сервис только отдаёт данные — только чтение.
3. Латиница в логине. Кириллический логин в заголовке Basic часто ломается из-за кодировки на стороне клиента. Логин apiuser избавит от загадочных 401.
4. HTTPS. Basic передаёт пароль в Base64, это не шифрование. Наружу сервис публикуют только через HTTPS: сертификат на Apache (модуль mod_ssl) или на IIS, либо обратный прокси с TLS перед веб-сервером.
5. Не зашивать пароль в публикацию. В строке подключения публикации можно указать Usr= и Pwd=, и тогда сервис откроется без логина. Это превращает базу в открытую дверь для всех, кто знает адрес.

Ограничьте доступ и на сетевом уровне. Если сервисом пользуется один внешний сервер, разрешите в брандмауэре или в настройках Apache только его IP-адрес.

Отладка веб-сервиса 1С

Отладчик Конфигуратора умеет останавливаться в коде HTTP-сервиса. Для этого:

1. Включите отладку в публикации. В default.vrd должен быть элемент отладки, например <debug enable="true" protocol="http" url="http://localhost:1550"/>. В диалоге публикации это делается флажком отладки, после чего публикацию нужно обновить.
2. В Конфигураторе выберите протокол отладки HTTP в параметрах (Сервис → Параметры, закладка запуска 1С:Предприятия) и перезапустите Конфигуратор.
3. Откройте Отладка → Подключение, затем окно автоматического подключения и отметьте тип HTTP-сервис.
4. Поставьте точку останова в функции-обработчике и отправьте запрос из curl или Postman.

Отладчик подключится к сеансу, который создаётся под запрос, и остановится на строке. Следите за таймаутом клиента: пока вы стоите на точке останова, Postman может прервать ожидание.

Не включайте отладку на рабочей публикации надолго. Она замедляет обработку и открывает лишний порт. Отладили — выключили.

Без отладчика помогают:

• 📜 Журнал регистрации. Необработанное исключение в обработчике попадает туда с текстом ошибки и номером строки модуля, а клиент получает 500.
• 🧾 Своя запись в журнал. В начале обработчика вызывайте ЗаписьЖурналаРегистрации("API.Входящий", УровеньЖурналаРегистрации.Информация, , , Запрос.ПолучитьТелоКакСтроку()) — видно, что именно пришло.
• 🌐 Логи веб-сервера. В access.log Apache видно, дошёл ли запрос вообще и с каким кодом ушёл ответ.

Частые ошибки при запуске веб-сервиса

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

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