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

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

Механизм появился в платформе 1С:Предприятие 8.3 и стал стандартным инструментом интеграции. До его появления для обмена по HTTP использовались в основном SOAP-ориентированные веб-сервисы, которые тяжелее в настройке и хуже подходят для лёгких интеграций. HTTP-сервисы проще: разработчик сам определяет структуру URL, методы запросов и формат данных.

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

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

HTTP-сервис добавляется в конфигураторе в ветке «Общие» → «HTTP-сервисы». Каждый сервис имеет корневой URL — базовый адрес, по которому он будет доступен после публикации. Внутри сервиса создаются шаблоны URL, а внутри шаблонов — методы (GET, POST, PUT, DELETE и другие), каждому из которых соответствует обработчик на встроенном языке.

Шаблон URL описывает структуру адреса и может содержать параметры в фигурных скобках. Например, шаблон /products/{id} позволит обрабатывать запросы вида /products/123, где значение 123 попадёт в параметр запроса. Также сервису назначается общий модуль, в котором размещаются функции-обработчики методов.

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

Создание простого HTTP-сервиса: пошагово

Разберём создание сервиса, который по GET-запросу возвращает остаток товара по его коду. Порядок действий одинаков для большинства типовых конфигураций и собственных разработок.

1. 1
   В конфигураторе откройте ветку «Общие» → «HTTP-сервисы» и добавьте новый сервис, например «СкладAPI». Укажите корневой URL, например warehouse.
2. 2
   Создайте общий модуль (например, СкладAPI) с флагами «Сервер» и «Вызов сервера»; привяжите его к сервису в свойстве «Модуль».
3. 3
   Добавьте шаблон URL /stock/{code} и внутри него метод GET, указав имя обработчика, например ПолучитьОстаток.
4. 4
   В общем модуле напишите функцию ПолучитьОстаток(Запрос), которая читает параметр, выполняет запрос к регистру остатков и возвращает HTTPСервисОтвет с JSON.
5. 5
   Опубликуйте сервис на веб-сервере через меню «Администрирование» → «Публикация на веб-сервере», отметив флаг публикации HTTP-сервисов.
6. 6
   Проверьте работу запросом из браузера или curl: http://server/base/hs/warehouse/stock/000001

Пример минимального обработчика:

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

// ... запрос к регистру остатков ...

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

Обратите внимание на префикс /hs/ в адресе: все HTTP-сервисы публикуются по пути http://сервер/база/hs/корневойURL/.... Это стандартное соглашение платформы, изменить его нельзя.

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

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

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

Для клиент-серверной базы публикация выполняется аналогично, но веб-сервер должен иметь связь с кластером серверов 1С. Если запрос возвращает ошибку 404 — чаще всего не опубликован сервис или неверно указан корневой URL; ошибка 500 обычно означает исключение в коде обработчика, детали смотрите в технологическом журнале или журнале регистрации.

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

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

Для webhook-уведомлений от внешних сервисов (платёжные шлюзы, телефония) логин-пароль не всегда применим: внешняя система может не уметь их передавать. В таких случаях используют секретный токен в URL или заголовке и проверяют его в начале обработчика, а также проверяют подпись запроса, если сервис её предоставляет.

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

Обработка запросов: методы, форматы, нюансы

GET-запросы подходят для чтения данных: остатки, цены, статусы заказов. POST — для создания и изменения: приём заказа, регистрация оплаты. Тело POST обычно передаётся в JSON; в обработчике оно читается методом Запрос.ПолучитьТелоКакСтроку() и разбирается через ПрочитатьJSON.

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

Важный нюанс — кодировка. Тело запроса читается в кодировке, указанной в заголовке Content-Type; если внешняя система её не передаёт, кириллица может превратиться в «кракозябры». Надёжнее договориться об UTF-8 и явно проверять корректность данных перед записью в базу.

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

Отладка и типичные ошибки

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

Проверять сервис удобно до подключения реальной внешней системы: браузером для GET-запросов, утилитой curl или Postman для POST с телом. Так вы отделите ошибки самого сервиса от ошибок на стороне клиента.

HTTP-сервисы против альтернатив

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

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