HTTP-сервис в 1С 8.3: от объекта в Конфигураторе до рабочей интеграции

Чтобы внешняя система (сайт, мобильное приложение, другая учётная база) могла обращаться к данным 1С по обычным HTTP-запросам, в конфигурации создают объект HTTP-сервис, задают ему корневой URL, шаблоны и методы под нужные действия, а затем публикуют базу на веб-сервере. После публикации сервис доступен по адресу вида http://сервер/база/hs/корневой-url/... и отвечает на GET, POST и другие запросы тем, что вы напишете в обработчиках.

HTTP-сервисы появились в платформе начиная с версии 8.3.5. В отличие от SOAP-веб-сервисов (/ws/), они работают по принципу REST: лёгкие запросы, свободный формат тела, чаще всего JSON. Это основной способ связать 1С с внешним миром, когда на той стороне не умеют разбирать тяжёлый XML-конверт SOAP.

Ниже — весь путь: от создания объекта в Конфигураторе до проверки готового сервиса через curl и подключения отладчика.

Чем HTTP-сервис отличается от веб-сервиса и внешнего соединения

Три механизма решают разные задачи, их часто путают.

HTTP-сервис выигрывает простотой: вы сами решаете, что принимать и что отдавать. Обработчик получает объект запроса, вы читаете из него тело и параметры, формируете ответ и возвращаете его. Никаких схем и описаний, как в SOAP, соблюдать не нужно.

Что подготовить перед работой

Сервис не заработает без трёх вещей. Проверьте их заранее, иначе публикация завершится ошибкой.

• 🧩 Модуль расширения веб-сервера. Это отдельный компонент платформы (Модули расширения веб-сервера). Разрядность модуля должна совпадать с разрядностью веб-сервера, а не платформы: для 64-битного Apache нужен 64-битный модуль.
• 🌐 Сам веб-сервер — Apache или IIS, установленный и запущенный на той же машине, где стоит сервер 1С (или где лежит файловая база).
• 🔢 Платформа не ниже 8.3.5. Для современных возможностей (работа с большими телами запросов, потоковая отдача) лучше актуальный релиз.

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

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

Сначала создаётся сам объект метаданных, затем внутри него — шаблоны URL и методы.

1. Откройте Конфигуратор, в дереве конфигурации найдите ветку Общие → HTTP-сервисы. Правой кнопкой → Добавить.
2. Задайте имя (например, Интеграция) и корневой URL (например, exchange). Корневой URL — это то, что встанет в адрес после /hs/. Он должен быть уникальным среди всех сервисов конфигурации.
3. Внутри сервиса добавьте шаблон URL. Шаблон описывает путь, по которому вызывается конкретное действие. Пример: /goods/{Артикул}. Фигурные скобки — это параметр, его значение попадёт в обработчик.
4. Внутри шаблона добавьте метод. У метода два ключевых свойства: HTTP-метод (GET, POST, PUT, DELETE и т. д.) и Имя обработчика.
5. Нажмите на свойство Имя обработчика — платформа создаст пустую функцию в модуле сервиса. Её вы и будете наполнять кодом.

Структура получается вложенной: один сервис → несколько шаблонов URL → в каждом шаблоне несколько методов под разные HTTP-глаголы.

Полный адрес вызова после публикации сложится так:

http://сервер/ИмяБазы/hs/exchange/goods/0001

где exchange — корневой URL, goods/0001 — конкретный шаблон с подставленным параметром.

Как опубликовать базу на веб-сервере

Объект создан — теперь его нужно опубликовать, иначе снаружи он недоступен.

1. В Конфигураторе откройте меню Администрирование → Публикация на веб-сервере.
2. В окне публикации задайте имя публикации — это то, что встанет в адрес после имени сервера (/ИмяБазы/). Укажите каталог, где веб-сервер будет держать файлы публикации.
3. Выберите веб-сервер из списка (Apache или IIS — платформа определит установленные).
4. Перейдите на закладку, где перечислены HTTP-сервисы. Отметьте флажок у вашего сервиса или включите «Публиковать HTTP-сервисы по умолчанию» — без этого сервис опубликован не будет.
5. Нажмите Опубликовать. Платформа создаст файл default.vrd в каталоге публикации и попросит перезапустить веб-сервер .

Файл default.vrd — это описание публикации в формате XML. В нём есть секция <httpServices>, где перечислены опубликованные сервисы. Если позже понадобится что-то поправить вручную (например, добавить сервис без перепубликации), правьте именно его, а затем перезапустите веб-сервер.

Для боевой эксплуатации публикацию обязательно переводят на HTTPS: настраивают SSL-сертификат на стороне веб-сервера и обращаются к сервису по https://. Почему это не опционально — в разделе про безопасность.

Как разобрать запрос и сформировать ответ

Вся логика сервиса живёт в обработчиках. Обработчик — это функция в модуле HTTP-сервиса, которая принимает объект запроса и возвращает объект ответа.

Метод GET: отдать данные

Запрос на чтение — самый частый случай. Клиент запрашивает GET /hs/exchange/goods/0001, сервис возвращает JSON с данными по товару.

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

    Ответ = Новый HTTPСервисОтвет(200);

    Артикул = Запрос.ПараметрыURL["Артикул"];

    // ... здесь запросом к базе находим товар по артикулу
    // и собираем нужные поля в структуру

    СтруктураТовара = Новый Структура;
    СтруктураТовара.Вставить("Артикул", Артикул);
    СтруктураТовара.Вставить("Наименование", Наименование);
    СтруктураТовара.Вставить("Остаток", Остаток);

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

    Ответ.УстановитьТелоИзСтроки(ТелоОтвета);
    Ответ.Заголовки["Content-Type"] = "application/json; charset=utf-8";

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

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

Что здесь происходит по шагам:

• Запрос.ПараметрыURL["Артикул"] достаёт значение из фигурных скобок шаблона /goods/{Артикул}.
• Запрос.ПараметрыЗапроса — если бы адрес был ?склад=основной, параметр читался бы отсюда.
• JSON формируется объектом ЗаписьJSON: записываем структуру, забираем результат строкой.
• Заголовок Content-Type с charset=utf-8 обязателен — иначе клиент может неверно распознать кодировку.

Метод POST: принять данные

Запрос на запись приходит с телом. Клиент шлёт POST /hs/exchange/order и кладёт в тело JSON нового заказа.

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

    ТелоЗапроса = Запрос.ПолучитьТелоКакСтроку();

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

    // ДанныеЗаказа — это Соответствие с полями из тела запроса.
    // Создаём документ, заполняем, проводим...

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

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

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

ПолучитьТелоКакСтроку() отдаёт тело запроса целиком. Если ждёте файл или картинку — берите ПолучитьТелоКакДвоичныеДанные(). Функция ПрочитатьJSON по умолчанию возвращает Соответствие, из которого вы достаёте поля по именам.

Коды ответа ставьте осмысленно: 200 — успех, 201 — объект создан, 400 — в запросе ошибка клиента, 401 — не прошла авторизация, 404 — объект не найден, 500 — сбой на стороне 1С. Клиент на той стороне строит логику именно по коду, поэтому возвращать 200 на любую ситуацию — плохая практика.

Авторизация и безопасность сервиса

Сервис выполняет запросы от имени пользователя информационной базы. Это главный принцип: платформа не пускает анонимов, если в базе есть список пользователей.

Как это работает: внешняя система передаёт логин и пароль методом Basic-авторизации (заголовок Authorization: Basic ...). Платформа проверяет их по списку пользователей ИБ и выполняет запрос под этим пользователем — с его правами и ограничениями RLS.

Отсюда несколько жёстких правил:

• 🔐 Только HTTPS. Basic-авторизация передаёт логин и пароль в кодировке base64 — это не шифрование, а почти открытый текст. По открытому HTTP их перехватит любой в сети. Публикуйте сервис только через HTTPS с настроенным SSL-сертификатом.
• 👤 Отдельный технический пользователь. Не отдавайте наружу учётку администратора. Заведите пользователя под интеграцию и дайте ему роли ровно под те операции, что делает сервис. Если сервис только читает товары — прав на изменение документов у него быть не должно.
• 🧱 Проверяйте входные данные. Всё, что пришло в теле и параметрах, — это данные извне. Проверяйте типы, обязательные поля, допустимые значения до того, как создавать документы или писать в регистры.
• 📓 Логируйте обращения. Пишите в журнал регистрации, кто и что запросил. При разборе инцидентов это единственный способ понять, что происходило.

Если нужна авторизация строже Basic (например, по токену), её реализуют вручную: клиент передаёт токен в заголовке, а обработчик в начале проверяет Запрос.Заголовки["Authorization"] и сам решает, пускать запрос дальше или вернуть 401. Но и в этом случае канал должен быть HTTPS.

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

Проверять сервис начинают с самого простого запроса и постепенно усложняют.

1. GET прямо из браузера. Самый быстрый тест: вбейте адрес метода GET в адресную строку. Браузер покажет логин-пароль Basic-авторизации и выведет ответ. Если ответ пришёл — публикация и маршрут работают.

2. curl из командной строки. Для POST и заголовков удобнее консоль:

curl -u Интеграция:пароль -X POST ^
  -H "Content-Type: application/json" ^
  -d "{\"номенклатура\":\"0001\",\"количество\":5}" ^
  https://сервер/ИмяБазы/hs/exchange/order

3. Postman или аналог. Для регулярной отладки интеграции удобнее графический клиент: сохраняете запросы, видите коды ответов и заголовки, подставляете авторизацию в один клик.

Подключение отладчика. Чтобы встать на точку останова внутри обработчика:

1. В свойствах рабочего сервера в консоли администрирования (или при запуске агента сервера) должна быть разрешена отладка.
2. В Конфигураторе откройте Сервис → Параметры → закладка «Отладка» и включите отладку по протоколу, затем в меню Отладка → Подключение выберите предмет отладки, соответствующий вызову HTTP-сервиса.
3. Поставьте точку останова в обработчике и выполните запрос снаружи — отладчик остановится на вашей строке.

Если предмет отладки не появляется, чаще всего причина в том, что на сервере отладка не разрешена или Конфигуратор подключён не к тому серверу, на котором исполняется сервис.

Типовые сбои при первом запуске и что проверить:

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