Как создать собственный неавтоматический REST API в 1С и обрабатывать входящие запросы?

← На главную

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

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

Разница между автоматическим REST (OData) и собственными HTTP-сервисами

В платформе 1С существует два основных способа предоставить доступ к данным по протоколу HTTP:

Автоматический REST-интерфейс (OData). Формируется платформой автоматически на основе метаданных при публикации базы. Позволяет читать и изменять объекты (справочники, документы, регистры) стандартными OData-запросами с использованием параметров $select, $filter, $top, $skip. Главный недостаток — жесткая привязка к структуре метаданных 1С. В нем нельзя за один запрос собрать кастомную иерархическую структуру данных или выполнить сложный произвольный алгоритм без изменения объектов.
HTTP-сервисы 1С. Специальный объект конфигурации, позволяющий разработчику самостоятельно описать URL-шаблоны, методы (GET, POST, PUT, DELETE, PATCH) и полностью контролировать формат входящих и исходящих данных, а также логику их обработки на сервере 1С.

Таким образом, концепция REST в 1С для нестандартных задач реализуется именно через механизм HTTP-сервисов.

Пошаговое создание собственного HTTP-сервиса в конфигураторе

Разберем по шагам процесс создания и настройки кастомного REST-интерфейса в конфигураторе 1С.

В дереве метаданных найдем ветку Общие → HTTP-сервисы и добавим новый объект.
Зададим Имя и Корневой URL сервиса (например, api/v1).
Внутри сервиса создадим Шаблон URL. В шаблоне указывается путь и переменные части URL в фигурных скобках, например, /orders/{Идентификатор} или /products.
Для шаблона определим поддерживаемые HTTP-методы: например, метод GET для получения данных и метод POST для приема запросов на изменение или выполнение операций.
Для каждого метода назначим функцию-обработчик в модуле HTTP-сервиса.

Реализация логики получения данных (GET-запрос)

Посмотрим на пример функции-обработчика, которая принимает запрос, извлекает параметры, выполняет произвольный запрос к базе 1С и возвращает клиенту данные в формате JSON:


Функция ОбработатьЗапросGET(Запрос)
    
    // Получаем параметры из URL или строки запроса
    Идентификатор = Запрос.ПараметрыURL.Получить("Идентификатор");
    
    // Выполняем произвольную выборку данных
    ЗапросКБД = Новый Запрос;
    ЗапросКБД.Текст = 
        "ВЫБРАТЬ
        |   Товары.Ссылка КАК Идентификатор,
        |   Товары.Наименование КАК Наименование,
        |   Товары.Артикул КАК Артикул,
        |   Товары.Цена КАК Цена
        |ИЗ
        |   Справочник.Номенклатура КАК Товары
        |ГДЕ
        |   НЕ Товары.ЭтоГруппа";
        
    РезультатЗапроса = ЗапросКБД.Выполнить().Выгрузить();
    
    // Формируем структуру ответа
    СписокТоваров = Новый Массив;
    Для Каждого Стр Из РезультатЗапроса Цикл
        ТоварСтруктура = Новый Структура("id,name,sku,price", 
            Строка(Стр.Идентификатор.УникальныйИдентификатор()), 
            Стр.Наименование, 
            Стр.Артикул, 
            Стр.Цена);
        СписокТоваров.Добавить(ТоварСтруктура);
    КонецЦикла;
    
    // Сериализуем данные в JSON
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, СписокТоваров);
    СтрокаJSON = ЗаписьJSON.Закрыть();
    
    // Формируем ответ HTTP-сервиса
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Ответ.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
    
    Возврат Ответ;
    
КонецФункции

Регистрация входящих запросов и выполнение действий (POST-запрос)

Если стороннему сервису нужно передать данные в 1С (создать документ, зафиксировать факт обращения или запустить обработку), используем метод POST. Внутри функции-обработчика мы можем прочитать тело запроса, разобрать входящий JSON и записать данные в регистр или документ:


Функция ОбработатьЗапросPOST(Запрос)
    
    ТелоСтрокой = Запрос.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
    
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(ТелоСтрокой);
    ДанныеЗапроса = ПрочитатьJSON(ЧтениеJSON);
    ЧтениеJSON.Закрыть();
    
    // Регистрируем вызов или создаем объект в 1С
    Попытка
        НовыйДокумент = Документы.ЗаказПокупателя.СоздатьДокумент();
        НовыйДокумент.Дата = ТекущаяДатаСеанса();
        НовыйДокумент.Комментарий = "Заказ создан через REST API сторонней системы";
        // Заполнение реквизитов из структуры ДанныеЗапроса
        НовыйДокумент.Записать(РежимЗаписиДокумента.Запись);
        
        ОтветСтруктура = Новый Структура("status,orderId", "success", Строка(НовыйДокумент.Ссылка.УникальныйИдентификатор()));
        КодСтатуса = 201;
    Исключение
        ОтветСтруктура = Новый Структура("status,error", "error", ОписаниеОшибки());
        КодСтатуса = 400;
    КонецПопытки;
    
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, ОтветСтруктура);
    СтрокаОтвета = ЗаписьJSON.Закрыть();
    
    Ответ = Новый HTTPСервисОтвет(КодСтатуса);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Ответ.УстановитьТелоИзСтроки(СтрокаОтвета, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
    
    Возврат Ответ;
    
КонецФункции

Важные нюансы настройки и публикации

Проанализируем ключевые моменты, которые необходимо учитывать при развертывании REST API на базе 1С:

Публикация на веб-сервере. Чтобы сервис стал доступен снаружи, конфигурацию необходимо опубликовать на веб-сервере (IIS или Apache) через меню Администрирование → Публикация на веб-сервере. В диалоге публикации обязательно отметьте созданный HTTP-сервис. Настройки сохраняются в конфигурационном файле default.vrd.
Авторизация. Платформа 1С штатно ожидает Basic-аутентификацию (пользователь и пароль 1С). Если стороннему сервису требуется Bearer-токен (JWT), проверку можно выполнить вручную внутри обработчика, прочитав заголовок Authorization из коллекции Запрос.Заголовки.
Управление сеансами и лицензиями. Каждый вызов сервиса инициирует сеанс и требует клиентскую лицензию 1С. Для оптимизации нагрузки на веб-сервере настраивается пул соединений и время жизни сеанса.
Асинхронная обработка тяжелых задач. Если операция формирования данных занимает длительное время, не держите HTTP-соединение открытым. Запустите фоновое задание через ФоновыеЗадания.Выполнить(), верните статус 202 Accepted с идентификатором задания и предусмотрите отдельный метод для проверки статуса готовности результата.