Как создать и настроить HTTP-сервис в 1С 8.3 для интеграции с внешними системами?

← На главную

В современной разработке на платформе 1С:Предприятие 8.3 интеграция через HTTP-сервисы стала стандартом де-факто. В отличие от тяжеловесного SOAP (Web-сервисов), HTTP-сервисы работают быстрее, используют меньше трафика и позволяют легко взаимодействовать с веб-сайтами, мобильными приложениями и другими сторонними API. Проанализируем, как реализовать этот механизм с нуля, разберем основные объекты платформы и напишем код для обработки входящих данных.

Шаг 1. Создание и настройка объекта HTTP-сервис

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

Имя: Внутреннее имя объекта в метаданных (например, api_integration).
Корневой URL: Это часть адреса, по которой сервис будет доступен извне. Проанализируем пример: если мы укажем v1, то путь к сервису будет выглядеть как .../hs/v1/.
Модуль сервиса: Здесь мы будем писать основную логику обработки запросов.

После создания объекта необходимо настроить Шаблоны URL. Шаблон определяет, какую именно команду или ресурс запрашивает клиент. Разберем ситуацию: нам нужно получить список товаров. Мы создаем шаблон с именем GetItems и шаблоном /items. Если нам нужно передать конкретный ID товара, шаблон будет выглядеть так: /items/{id}.

Шаг 2. Реализация методов (GET и POST)

Внутри каждого шаблона создаются Методы. Для каждого метода мы выбираем тип HTTP-запроса (GET, POST, PUT, DELETE) и указываем имя обработчика в модуле. Рассмотрим подробнее, как написать код для обработки простейшего GET-запроса.

Выясним причину, почему важно правильно формировать HTTPСервисОтвет. Если мы не вернем ответ, клиент получит ошибку 500. Посмотрим на пример кода в модуле сервиса:


Функция itemsGetItems(Запрос)
    
    // Создаем объект ответа
    Ответ = Новый HTTPСервисОтвет(200);
    
    // Формируем структуру данных для возврата
    Данные = Новый Структура;
    Данные.Вставить("Status", "Success");
    Данные.Вставить("Timestamp", ТекущаяДата());
    
    // Сериализуем данные в JSON
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, Данные);
    СтрокаJSON = ЗаписьJSON.Закрыть();
    
    // Устанавливаем тело ответа и заголовки
    Ответ.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8);
    Ответ.Заголовки.Вставить("Content-Type", "application/json");
    
    Возврат Ответ;

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

Шаг 3. Обработка входящих данных в POST-запросах

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

Разберем по шагам процесс обработки:

Получаем строку из тела запроса методом ПолучитьТелоКакСтроку().
Используем объект ЧтениеJSON для десериализации данных в Структура или Массив.
Выполняем бизнес-логику (поиск или создание элементов).
Возвращаем статус выполнения (например, 201 Created).

Посмотрим на пример кода для обработки POST-запроса:


Функция itemsCreateItem(Запрос)
    
    // Читаем тело запроса
    ТелоЗапроса = Запрос.ПолучитьТелоКакСтроку("UTF-8");
    
    Если ПустаяСтрока(ТелоЗапроса) Тогда
        Возврат Новый HTTPСервисОтвет(400); // Bad Request
    КонецЕсли;
    
    // Парсим JSON
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(ТелоЗапроса);
    ДанныеОбъекта = ПрочитатьJSON(ЧтениеJSON);
    ЧтениеJSON.Закрыть();
    
    // Создаем элемент справочника (пример)
    Попытка
        НовыйТовар = Справочники.Номенклатура.СоздатьЭлемент();
        НовыйТовар.Наименование = ДанныеОбъекта.name;
        НовыйТовар.Артикул = ДанныеОбъекта.sku;
        НовыйТовар.Записать();
        
        Ответ = Новый HTTPСервисОтвет(201);
        Ответ.УстановитьТелоИзСтроки("Объект успешно создан", КодировкаТекста.UTF8);
    Исключение
        Ответ = Новый HTTPСервисОтвет(500);
        Ответ.УстановитьТелоИзСтроки("Ошибка при записи: " + ОписаниеОшибки(), КодировкаТекста.UTF8);
    КонецПопытки;
    
    Возврат Ответ;

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

Шаг 4. Работа с параметрами URL

Часто параметры передаются непосредственно в строке запроса, например: /hs/v1/items?category=electronics&limit=10. Проанализируем, как получить эти значения. Платформа 1С предоставляет доступ к ним через свойство Запрос.ПараметрыЗапроса, которое является объектом Соответствие.

Рассмотрим пример получения фильтра:


Категория = Запрос.ПараметрыЗапроса.Получить("category");
Если Категория <> Неопределено Тогда
    // Используем переменную для фильтрации в запросе к БД
КонецЕсли;

Если же вы используете параметры внутри шаблона (например, /items/{id}), то значение id будет доступно через Запрос.ПараметрыURL.Получить("id"). Это критически важно для реализации RESTful-дизайна вашего API.

Шаг 5. Обеспечение безопасности и авторизация

HTTP-сервисы в 1С по умолчанию требуют авторизации. Выясним, какие варианты доступны программисту:

Basic Authentication: Самый простой способ. Логин и пароль пользователя 1С передаются в заголовке запроса в зашифрованном Base64 виде. Важно: для работы этого метода необходимо, чтобы у пользователя были права "Удаленный доступ (HTTP)".
Анонимный доступ: Можно настроить публикацию так, чтобы запросы выполнялись от имени фиксированного пользователя. Это настраивается в файле default.vrd на веб-сервере.
OAuth/Токены: Можно реализовать проверку кастомного заголовка Authorization внутри кода метода. Если токен невалиден, возвращаем Новый HTTPСервисОтвет(401).

Шаг 6. Публикация сервиса

Чтобы ваш сервис стал доступен внешнему миру, его нужно опубликовать на веб-сервере (IIS или Apache). Разберем этот процесс:

В конфигураторе перейдите в Администрирование — Публикация на веб-сервере.
На вкладке HTTP-сервисы установите флажок напротив вашего сервиса.
Убедитесь, что установлен флаг "Публиковать HTTP-сервисы по умолчанию" (или выберите конкретный).
Нажмите "Опубликовать". Платформа обновит файл default.vrd.

После публикации адрес сервиса будет иметь формат: http://[server]/[base_name]/hs/[RootURL]/[Template]. Проанализируем это на примере: http://myserver/base/hs/v1/items.