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

← На главную

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

Понятие и назначение HTTP-сервисов в 1С

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

Шаг 1: Создание объекта в конфигураторе

Разберем процесс создания объекта. В дереве конфигурации найдем ветку Общие -> HTTP-сервисы и добавим новый объект. Присвоим ему имя, например, ОбменССайтом. Важным свойством здесь является КорневойURL — это имя будет использоваться во внешнем адресе сервиса. Для нашего примера укажем v1/exchange.

Теперь перейдем к настройке Шаблонов URL. Шаблон определяет структуру адреса, по которому внешняя система будет обращаться к 1С. Создадим шаблон GetBalance с шаблоном /balance/{Artikul}. Здесь {Artikul} — это параметр, который мы сможем прочитать в коде 1С.

Шаг 2: Настройка методов обработки

Внутри каждого шаблона необходимо определить Методы. Рассмотрим основные типы запросов:

GET — используется для получения данных из 1С.
POST — применяется для передачи новых данных в 1С (например, создание документа).
PUT — используется для обновления существующих данных.
DELETE — для удаления записей.

Для нашего шаблона GetBalance добавим метод GET и в поле Обработчик нажмем на лупу, чтобы создать процедуру в модуле HTTP-сервиса.

Шаг 3: Написание кода обработчика запроса

Проанализируем структуру модуля. Система автоматически создает шаблон функции, принимающей параметр Запрос типа HTTPСервисЗапрос. Выясним, как извлечь параметры из URL и вернуть ответ.

Разберем пример кода для получения остатка товара по артикулу:


Функция GetBalanceGetBalance(Запрос)
    // Извлекаем параметр из шаблона URL
    Артикул = Запрос.ПараметрыURL.Получить("Artikul");
    
    // Выполняем поиск товара и расчет остатка
    Остаток = ПолучитьОстатокПоАртикулу(Артикул);
    
    // Формируем структуру ответа
    ОтветДанные = Новый Структура;
    ОтветДанные.Вставить("artikul", Артикул);
    ОтветДанные.Вставить("balance", Остаток);
    ОтветДанные.Вставить("status", "success");
    
    // Сериализуем данные в JSON
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, ОтветДанные);
    СтрокаJSON = ЗаписьJSON.Закрыть();
    
    // Формируем HTTP-ответ
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Ответ.УстановитьТелоИзСтроки(СтрокаJSON);
    
    Возврат Ответ;
КонецФункции

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

Рассмотрим более сложную ситуацию: внешняя система присылает нам JSON с данными нового заказа. Для этого создадим метод POST. Нам необходимо прочитать тело запроса, которое содержится в объекте HTTPСервисЗапрос.

Посмотрим на пример обработки входящего JSON:


Функция CreateOrderPost(Запрос)
    // Читаем тело запроса в формате JSON
    СтрокаТела = Запрос.ПолучитьТелоКакСтроку();
    
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(СтрокаТела);
    ДанныеЗаказа = ПрочитатьJSON(ЧтениеJSON);
    ЧтениеJSON.Закрыть();
    
    Попытка
        // Начинаем транзакцию для создания документа
        НачатьТранзакцию();
        
        НовыйЗаказ = Документы.ЗаказПокупателя.СоздатьДокумент();
        НовыйЗаказ.Дата = ТекущаяДата();
        // Заполнение полей из структуры ДанныеЗаказа...
        НовыйЗаказ.Записать(РежимЗаписиДокумента.Проведение);
        
        ЗафиксироватьТранзакцию();
        
        КодСостояния = 201; // Created
        РезультатТекст = "Заказ успешно создан: " + НовыйЗаказ.Номер;
    Исключение
        ОтменитьТранзакцию();
        КодСостояния = 500;
        РезультатТекст = "Ошибка при создании заказа: " + ОписаниеОшибки();
    КонецПопытки;
    
    Ответ = Новый HTTPСервисОтвет(КодСостояния);
    Ответ.УстановитьТелоИзСтроки(РезультатТекст);
    Возврат Ответ;
КонецФункции

Шаг 5: Работа с заголовками и авторизацией

Важным аспектом безопасности является проверка прав доступа. Выясним причину, по которой сервис может быть недоступен. Чаще всего это связано с тем, что в публикации на веб-сервере не указан пользователь для анонимного доступа или не переданы данные авторизации.

Рассмотрим, как проверить наличие определенных заголовков в запросе. Для этого используется свойство Запрос.Заголовки. Например, мы можем требовать передачи специального API-ключа в заголовке X-API-KEY:


КлючДоступа = Запрос.Заголовки.Получить("X-API-KEY");
Если КлючДоступа <> "МойСекретныйКлюч" Тогда
    Возврат Новый HTTPСервисОтвет(401); // Unauthorized
КонецЕсли;

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

Чтобы наш код заработал и стал доступен из интернета, необходимо выполнить публикацию информационной базы. Пройдем по шагам:

Запустим конфигуратор от имени администратора.
Перейдем в меню Администрирование -> Публикация на веб-сервере.
Выберем веб-сервер (Apache или IIS).
На вкладке HTTP-сервисы обязательно установим флажок напротив нашего сервиса ОбменССайтом.
Нажмем Опубликовать.

Важный момент: после публикации адрес сервиса будет выглядеть следующим образом: http://server_address/base_name/hs/v1/exchange/balance/12345, где hs — стандартный префикс для всех HTTP-сервисов 1С.

Советы по оптимизации и отладке

Проанализируем типичные ошибки начинающих разработчиков. Во-первых, отладка HTTP-сервисов требует включения отладки на сервере 1С. Во-вторых, всегда используйте блоки Попытка...Исключение, чтобы внешняя система получала внятный ответ с кодом ошибки 500 или 400, а не просто "Connection reset".

Разберем, как повысить производительность. Если запросов очень много, рекомендуется использовать разделение данных или выносить обработку в фоновые задания, если клиенту не требуется моментальный ответ. Однако для синхронных методов (получение остатка) старайтесь минимизировать количество обращений к базе данных внутри запроса, используя индексированные поля и временные таблицы.

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