Как работает HTTP-сервис в 1С: устройство, публикация и отладка

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

Механизм работает только в клиент-серверном или файловом варианте, опубликованном на веб-сервере. Запрос от внешней системы приходит на веб-сервер (Apache или IIS), тот передаёт его модулю расширения 1С, платформа находит подходящий HTTP-сервис и шаблон URL, вызывает обработчик на встроенном языке и возвращает сформированный ответ. Вся бизнес-логика — чтение данных, проверки прав, запись в базу — выполняется внутри обработчика обычным кодом 1С.

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

Из чего состоит HTTP-сервис и как проходит запрос

HTTP-сервис создаётся в конфигураторе в ветке «Общие — HTTP-сервисы». У объекта есть три ключевых элемента: корневой URL (префикс, с которого начинаются все адреса сервиса), шаблоны URL (описывают структуру адресов и параметры) и методы (GET, POST, PUT, DELETE и другие), для каждого из которых назначается обработчик — функция на встроенном языке.

Когда внешняя система отправляет запрос, платформа ищет сервис по корневому URL, затем подбирает первый подходящий шаблон. Если ни один шаблон не совпал с адресом, возвращается ошибка 404. Если шаблон найден, но метод не описан — ошибка 405. Параметры из адресной строки попадают в свойства запроса: параметры шаблона — в ПараметрыURL, строка запроса после знака вопроса — в ПараметрыЗапроса.

Обработчик получает объект HTTPСервисЗапрос и должен вернуть объект HTTPСервисОтвет. В запросе доступны тело, заголовки и параметры; в ответе разработчик задаёт код состояния, тело и заголовки, например Content-Type для JSON.

Создание сервиса и написание обработчика

Минимальный сценарий: создайте HTTP-сервис с корневым URL, например api. Добавьте шаблон URL /ping, у шаблона создайте метод GET и назначьте ему обработчик. Платформа сформирует заготовку функции в модуле сервиса.

В обработчике сформируйте ответ: создайте объект HTTPСервисОтвет с кодом 200, заполните тело и верните его. Ниже пример обработчика, который отдаёт JSON с текущей датой сервера.

Функция pingGET(Запрос)
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Данные = Новый Структура("status, serverTime", "ok", ТекущаяДатаСеанса());
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, Данные);
    Ответ.УстановитьТелоИзСтроки(ЗаписьJSON.Закрыть());
    Возврат Ответ;
КонецФункции

Для методов POST и PUT тело запроса читается через Запрос.ПолучитьТелоКакСтроку() и разбирается через ПрочитатьJSON. Всегда оборачивайте разбор тела в попытку/исключение: внешняя система может прислать некорректный JSON, и без обработки ошибки вы получите ответ 500 без внятного описания.

1. 1
   В конфигураторе добавьте объект «HTTP-сервис» и задайте корневой URL
2. 2
   Создайте шаблон URL с нужными параметрами в фигурных скобках
3. 3
   Добавьте метод (GET, POST) и назначьте обработчик
4. 4
   Напишите код обработчика: чтение параметров, логика, формирование ответа
5. 5
   Опубликуйте сервис на веб-сервере и проверьте запрос из браузера или curl

Публикация на веб-сервере

Сам по себе объект конфигурации запросы не принимает — требуется публикация. В конфигураторе откройте «Администрирование — Публикация на веб-сервере», отметьте флаг «Публиковать HTTP-сервисы» и выполните публикацию. На веб-сервере должны быть установлены компоненты расширения веб-сервера 1С.

После публикации адрес сервиса складывается из адреса публикации базы, корневого URL сервиса и шаблона: https://server/base/hs/api/ping. Сегмент hs — стандартный признак обращения к HTTP-сервисам, в отличие от веб-сервисов, которые доступны по сегменту ws.

Если публикация выполнена, но запрос возвращает ошибку веб-сервера, а не платформы, проверьте, что в файле публикации (default.vrd) присутствует описание сервиса и что приложение на веб-сервере перезапущено после изменений. Изменения в default.vrd подхватываются не всегда автоматически.

Аутентификация и безопасность

По умолчанию при обращении к HTTP-сервису платформа требует аутентификацию пользователя информационной базы. Логин и пароль можно передать в строке подключения, в заголовке Authorization (Basic) или задать в настройках публикации. Заведите отдельного пользователя с минимально необходимыми правами — только на те объекты, которые читает или изменяет сервис.

Критично: публикация HTTP-сервиса открывает доступ к базе из сети, поэтому используйте HTTPS, ограничивайте доступ по IP на уровне веб-сервера, если потребитель известен, и никогда не публикуйте сервисы с пользователем, имеющим полные права. Утечка таких учётных данных означает полный доступ к базе.

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

Форматы данных и типичные сценарии

Чаще всего HTTP-сервисы 1С обмениваются данными в JSON — это удобно для сайтов и мобильных приложений. Для интеграции с системами на других стеках используют XML. Тело ответа формируется строкой через ЗаписьJSON/ЗаписьXML, а для двоичных данных (файлы, картинки) есть метод УстановитьТелоИзДвоичныхДанных.

Получение данных наружу (GET)

Типовой сценарий — выгрузка остатков, цен, статусов заказов. В обработчике выполняется запрос к базе, результат сериализуется в JSON и возвращается с кодом 200. При больших объёмах добавляйте параметры постраничной выборки, иначе один запрос может надолго занять рабочий процесс сервера.

Приём данных внутрь (POST)

Внешняя система передаёт заказы, заявки или результаты оплаты. В обработчике разберите тело, проверьте обязательные поля, запишите данные в транзакции и верните идентификатор созданного объекта. Идемпотентность желательна: если внешняя система повторит запрос из-за таймаута, не должен создаваться дубль документа — проверяйте уникальный номер из запроса.

Диагностика: сервис не отвечает или возвращает ошибку

Начинайте проверку с кода ответа. Ошибка 404 означает, что не найден сервис или шаблон URL: сверьте корневой URL, шаблон и фактический адрес запроса посимвольно. Ошибка 405 — метод не описан у шаблона. Ошибка 401 — проблема аутентификации: проверьте пользователя, пароль и способ передачи учётных данных. Ошибка 500 — исключение в обработчике: смотрите технологический журнал или журнал регистрации.

Для отладки используйте отладку на сервере 1С: включите отладку по HTTP в свойствах информационной базы и подключитесь конфигуратором к серверному процессу — точки останова в обработчике сработают при реальном запросе. Параллельно полезно проверять запросы через curl или Postman, чтобы отделить проблемы клиента от проблем сервиса.

Ограничения и альтернативы

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

Альтернативы: веб-сервисы (SOAP) — когда внешняя система требует WSDL-описание; OData-интерфейс — когда нужен стандартный доступ к данным без написания кода, но с меньшим контролем логики; планы обмена — для регулярной интеграции между базами 1С без веб-сервера. Выбор зависит от требований внешней системы и допустимой задержки.

FAQ