Как добавить и настроить HTTP-сервис в расширении для 1С:Фреш

← На главную

Развитие облачных технологий делает интеграцию систем критически важной задачей. Часто возникает необходимость связать интернет-магазин, CRM-систему или сторонний веб-сервис с базой данных, работающей в облаке 1С:Фреш (1cfresh.com). Самым удобным и современным способом решения этой задачи является создание собственного HTTP-сервиса в расширении конфигурации.

В этой статье мы подробно рассмотрим, как реализовать этот механизм, разберем особенности публикации адресов в облаке, требования безопасности сервиса и правила успешного прохождения аудита 1С.

Возможно ли использовать веб-сервисы в расширениях 1С:Фреш?

Да, это полностью рабочая и официально поддерживаемая технология. Фирма «1С» разрешает добавлять как Web-сервисы (SOAP), так и HTTP-сервисы (REST) в состав расширений для облачных приложений. На практике чаще всего используются именно HTTP-сервисы из-за их легковесности и простоты интеграции со сторонними веб-платформами.

Типичный сценарий использования: интернет-магазин отправляет POST-запрос с данными о новом заказе на URL-адрес вашей базы во Фреше. HTTP-сервис в расширении принимает этот запрос, обрабатывает его и автоматически создает в базе (например, в «1С:Бухгалтерии 3.0» или «1С:УНФ») документ СчетНаОплатуПокупателю или ЗаказПокупателя.

---

Как формируется URL-адрес для внешних запросов к сервису

При локальном развертывании ИТ-специалисту приходится самостоятельно настраивать веб-сервер (Apache или IIS) и прописывать конфигурационный файл default.vrd. В облаке 1С:Фреш этот процесс полностью автоматизирован. Как только ваше расширение проходит аудит и подключается к области данных (базе клиента), HTTP-сервис становится доступен извне.

Поскольку 1С:Фреш работает по технологии разделения данных (мультиарендность), адрес для обращения к вашему HTTP-сервису будет строго регламентирован. Шаблон URL выглядит следующим образом:

https://1cfresh.com/a/<короткое_имя_конфигурации>/<номер_области_данных>/hs/<корневой_URL_сервиса>/<шаблон_пути>

Разберем параметры этого адреса подробнее:

Короткое имя конфигурации: сокращенный идентификатор приложения в облаке. Например, bp — для «1С:Бухгалтерии», sbm — для «1С:УНФ».
Номер области данных: уникальное число, идентифицирующее конкретную информационную базу абонента в облаке (его можно увидеть в личном кабинете или в адресной строке браузера при работе с базой).
hs: обязательный признак того, что обращение идет именно к HTTP-сервису.
Корневой URL сервиса: свойство вашего HTTP-сервиса, заданное в конфигураторе 1С.
Шаблон пути: конкретный метод (относительный путь), который вы описали внутри HTTP-сервиса (например, create_invoice).

Пример реального адреса для отправки запроса:

https://1cfresh.com/a/bp/123456/hs/mysiteintegration/v1/create_invoice

---

Безопасный режим и авторизация запросов

Все расширения в 1С:Фреш работают в строгом безопасном режиме. Это накладывает определенные правила на организацию взаимодействия:

1. Входящие запросы (из интернет-магазина в 1С)

Анонимный доступ к базам данных в облаке закрыт по соображениям безопасности. Чтобы ваш сайт мог постучаться в HTTP-сервис, в информационной базе 1С необходимо создать служебного пользователя (например, с именем Exchange_Robot) и задать ему сложный пароль. Этому пользователю нужно назначить минимальные права для выполнения необходимых операций (например, только роль на работу с HTTP-сервисом и создание счетов).

При отправке запросов со стороны сайта необходимо использовать базовую авторизацию (Basic Auth), передавая логин и пароль в заголовках HTTP-пакета.

2. Исходящие запросы (из 1С на внешний сайт)

Если в процессе обработки запроса вашему HTTP-сервису требуется отправить ответный запрос на сайт (например, подтвердить получение заказа или изменить статус транзакции на веб-ресурсе), безопасный режим по умолчанию заблокирует такое соединение. Для обхода этого ограничения в коде расширения необходимо использовать функции БСП (Библиотеки Стандартных Подсистем) для программного запроса разрешений на доступ к внешним интернет-ресурсам.

Рассмотрим пример функции, которая декларирует необходимость доступа к внешнему серверу API вашего интернет-магазина:


Функция ПолучитьРазрешенияНаРесурсы() Экспорт
    Разрешения = Новый Массив;
    
    // Описываем протокол, адрес и порт внешнего сайта
    Протокол = "https";
    Адрес = "api.my-online-shop.ru";
    Порт = 443;
    
    Разрешение = РаботаВБезопасномРежиме.РазрешениеНаИспользованиеИнтернетРесурса(Протокол, Адрес, Порт, "Интеграция с интернет-магазином для отправки статусов");
    Разрешения.Добавить(Разрешение);
    
    Возврат Разрешения;
КонецФункции

Эти разрешения будут проверены и утверждены во время прохождения расширением аудита безопасности, после чего облачный кластер разрешит исходящие сетевые запросы именно на этот хост.

---

Критически важные требования аудита 1С к коду сервисов

Чтобы ваше расширение было допущено к работе в облаке 1С:Фреш, оно должно пройти обязательный автоматический и ручной аудит со стороны специалистов фирмы «1С». Проанализируем ключевые правила, несоблюдение которых гарантированно приведет к отклонению расширения:

Отсутствие обфускации кода: Весь исходный код модулей расширения должен быть полностью открытым. Запрещено устанавливать пароли на модули или использовать сторонние утилиты для запутывания логики.
Кроссплатформенность серверного кода: Серверная часть облака 1С:Фреш функционирует под управлением ОС Linux. Использование Windows-специфичных COM-объектов (таких как Excel.Application или Word.Application) категорически запрещено. Используйте только штатные кроссплатформенные механизмы 1С.
Минимизация транзакций: Все обработчики HTTP-запросов должны выполняться максимально быстро. Длинные блокировки таблиц базы данных в общем облачном кластере недопустимы. Стремитесь записывать документы в кратчайшие сроки и избегайте тяжелых запросов внутри транзакций.
Флаг загрузки данных: При создании или изменении объектов из внешних источников обязательно проверяйте режим загрузки, чтобы избежать зацикливания бизнес-логики:


Если ОбменДанными.Загрузка Тогда
    Возврат;
КонецЕсли;

---

Пример реализации HTTP-сервиса в расширении

Разберем практический пример реализации метода создания счета на оплату при поступлении данных от интернет-магазина в формате JSON. Мы создаем HTTP-сервис с корневым URL siteintegration, шаблоном пути /v1/create_invoice и методом POST.

В модуле HTTP-сервиса опишем следующий обработчик:


Функция СоздатьСчетНаОплатуPOST(Запрос) Экспорт
    
    УстановитьПривилегированныйРежим(Истина);
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    
    // Получаем тело POST-запроса в виде строки
    СтрокаТелаЗапроса = Запрос.ПолучитьТелоКакСтроку("UTF-8");
    
    Если ПустаяСтрока(СтрокаТелаЗапроса) Тогда
        Ответ.КодСостояния = 400; // Bad Request
        Ответ.УстановитьТелоИзСтроки("{""error"": ""Тело запроса пустое""}");
        Возврат Ответ;
    КонецЕсли;
    
    // Десериализуем JSON из запроса
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(СтрокаТелаЗапроса);
    ДанныеЗаказа = ПрочитатьJSON(ЧтениеJSON);
    ЧтениеJSON.Закрыть();
    
    // Начинаем создание документа в информационной базе
    СчетДок = Документы.СчетНаОплатуПокупателю.СоздатьДокумент();
    СчетДок.Дата = ТекущаяДатаСеанса();
    
    // Заполняем реквизиты документа на основе полученной структуры
    СчетДок.Контрагент = Справочники.Контрагенты.НайтиПоРеквизиту("ИНН", ДанныеЗаказа.ИННКонтрагента);
    СчетДок.Организация = Справочники.Организации.НайтиПоРеквизиту("ИНН", ДанныеЗаказа.ИННОрганизации);
    СчетДок.ДоговорКонтрагента = Справочники.ДоговорыКонтрагентов.ПолучитьОсновнойДоговор(СчетДок.Контрагент, СчетДок.Организация);
    
    // Пример заполнения табличной части Товары
    Для Каждого СтрокаТовара Из ДанныеЗаказа.Товары Цикл
        НоваяСтрока = СчетДок.Товары.Добавить();
        НоваяСтрока.Номенклатура = Справочники.Номенклатура.НайтиПоРеквизиту("Артикул", СтрокаТовара.Артикул);
        НоваяСтрока.Количество = СтрокаТовара.Количество;
        НоваяСтрока.Цена = СтрокаТовара.Цена;
        НоваяСтрока.Сумма = СтрокаТовара.Количество * СтрокаТовара.Цена;
    КонецЦикла;
    
    // Записываем документ
    Попытка
        СчетДок.Записать(РежимЗаписиДокумента.Запись);
        
        // Формируем успешный ответ в формате JSON
        ЗаписьJSON = Новый ЗаписьJSON;
        ЗаписьJSON.УстановитьСтроку();
        
        РезультатСтруктура = Новый Структура;
        РезультатСтруктура.Вставить("success", Истина);
        РезультатСтруктура.Вставить("document_number", СчетДок.Номер);
        РезультатСтруктура.Вставить("document_id", Строка(СчетДок.Ссылка.УникальныйИдентификатор()));
        
        ЗаписатьJSON(ЗаписьJSON, РезультатСтруктура);
        СтрокаJSON = ЗаписьJSON.Закрыть();
        
        Ответ.УстановитьТелоИзСтроки(СтрокаJSON, "UTF-8", ИспользованиеByteOrderMark.НеИспользовать);
        
    Исключение
        // В случае ошибки возвращаем внутреннюю ошибку сервера 500
        Ответ.КодСостояния = 500;
        
        ЗаписьJSON = Новый ЗаписьJSON;
        ЗаписьJSON.УстановитьСтроку();
        
        ОшибкаСтруктура = Новый Структура;
        ОшибкаСтруктура.Вставить("success", Ложь);
        ОшибкаСтруктура.Вставить("error", ОписаниеОшибки());
        
        ЗаписатьJSON(ЗаписьJSON, ОшибкаСтруктура);
        СтрокаJSON = ЗаписьJSON.Закрыть();
        
        Ответ.УстановитьТелоИзСтроки(СтрокаJSON, "UTF-8", ИспользованиеByteOrderMark.НеИспользовать);
    КонецПопытки;
    
    Возврат Ответ;
    
КонецФункции

Таким образом, мы спроектировали надежный обработчик запросов, который принимает внешние транзакции, безопасно парсит данные и генерирует новые документы в информационной базе, возвращая корректные HTTP-статусы и сообщения об ошибках.