Как настроить обмен данными через HTTP-сервисы и JSON в 1С?

← На главную

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

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

Подготовка: Зачем нужны HTTP-сервисы и JSON?

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

Формат JSON (JavaScript Object Notation) мы выбираем как наиболее легкий и понятный стандарт передачи данных, который поддерживается практически всеми современными языками программирования.

Шаг 1: Создание HTTP-сервиса в конфигураторе

Давайте начнем с настройки метаданных. В дереве конфигурации найдем ветку Общие -> HTTP-сервисы и добавим новый объект.

Присвоим имя, например, ExchangeAPI.
Укажем Корневой URL. Это та часть адреса, по которой сервис будет доступен. Назовем его api.
На вкладке Шаблоны URL создадим ресурсы, к которым будут обращаться внешние системы.

Предположим, мы хотим работать с заказами. Создадим шаблон с именем Orders и шаблоном /orders. Внутри этого шаблона добавим методы:

GET — для получения списка заказов.
POST — для создания нового заказа.

Для каждого метода платформа предложит создать функцию-обработчик в модуле сервиса. Согласимся с этим и перейдем к программированию.

Шаг 2: Обработка входящего POST-запроса (Прием JSON)

Рассмотрим подробно, как принять данные. Когда внешняя система отправляет нам заказ, данные приходят в теле запроса (Body) в виде строки JSON. Наша задача — извлечь эту строку и превратить её в объекты 1С (Структуры или Соответствия).

В функции-обработчике POST-запроса мы получаем параметр типа HTTPСервисЗапрос. Разберем код чтения данных:


Функция OrdersPOST(Запрос)
	
	// 1. Получаем тело запроса в виде строки
	Попытка
		СтрокаJSON = Запрос.ПолучитьТелоКакСтроку();
	Исключение
		// Если кодировка не определилась автоматически, можно указать явно
		СтрокаJSON = Запрос.ПолучитьТелоКакСтроку("UTF-8");
	КонецПопытки;
	
	// Если тело пустое, нет смысла продолжать
	Если ПустаяСтрока(СтрокаJSON) Тогда
		Возврат ОтветСОшибкой(400, "Тело запроса пустое");
	КонецЕсли;
	
	// 2. Читаем JSON в структуру 1С
	Чтение = Новый ЧтениеJSON;
	Чтение.УстановитьСтроку(СтрокаJSON);
	
	Попытка
		ДанныеЗаказа = ПрочитатьJSON(Чтение, Истина); // Истина = читать в Соответствие/Структуру
	Исключение
		Возврат ОтветСОшибкой(400, "Некорректный формат JSON");
	КонецПопытки;
	
	Чтение.Закрыть();
	
	// Далее передаем ДанныеЗаказа в процедуру создания документа
	РезультатСоздания = СоздатьЗаказПоДанным(ДанныеЗаказа);
	
	Возврат ОтветУспех(РезультатСоздания);
	
КонецФункции

Обратите внимание на использование объекта ЧтениеJSON. Метод ПрочитатьJSON является универсальным инструментом десериализации. Флаг Истина во втором параметре указывает платформе, что мы ожидаем получить на выходе Соответствие или Структуру, а массивы JSON будут преобразованы в Массив 1С.

Шаг 3: Формирование ответа сервера (Отправка JSON)

После того как мы обработали данные, нам необходимо вернуть ответ клиенту. Хорошим тоном считается возврат HTTP-кода состояния (200 OK, 400 Bad Request, 500 Internal Server Error) и тела ответа в формате JSON.

Посмотрим, как правильно сформировать ответ, используя объект HTTPСервисОтвет. Для удобства выделим это в отдельную вспомогательную функцию, так как отвечать придется часто.


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

Важный момент: всегда явно указывайте заголовок Content-Type. Это позволяет принимающей стороне (сайту или приложению) сразу понять, что мы вернули именно JSON, а не просто текст или HTML.

Шаг 4: Обработка ошибок

Разберем ситуацию, когда что-то пошло не так. Например, в JSON не хватает обязательных полей или формат данных неверен. Мы не должны просто "упасть" с ошибкой 1С, мы должны вернуть понятное описание проблемы клиенту.


Функция ОтветСОшибкой(КодСтатуса, ТекстОшибки)
	
	СтруктураОшибки = Новый Структура;
	СтруктураОшибки.Вставить("error", Истина);
	СтруктураОшибки.Вставить("message", ТекстОшибки);
	
	Запись = Новый ЗаписьJSON;
	Запись.УстановитьСтроку();
	ЗаписатьJSON(Запись, СтруктураОшибки);
	СтрокаОтвета = Запись.Закрыть();
	
	Ответ = Новый HTTPСервисОтвет(КодСтатуса);
	Ответ.УстановитьТелоИзСтроки(СтрокаОтвета, КодировкаТекста.UTF8);
	Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
	
	Возврат Ответ;
	
КонецФункции

Используя эту функцию, мы можем возвращать код 400 при ошибках валидации данных, 401 при ошибках авторизации или 500 при критических сбоях на сервере.

Шаг 5: Работа со сложными данными и датами

При обмене через JSON часто возникают вопросы с передачей дат. Стандарт JSON не имеет встроенного типа Date. В 1С метод ЗаписатьJSON по умолчанию преобразует даты в специальный строковый формат. Однако, общепринятым стандартом в веб-разработке является формат ISO 8601 (например, "2023-10-05T14:30:00").

Давайте настроим параметры записи JSON так, чтобы даты были понятны всем системам. Для этого используем объект НастройкиСериализацииJSON.


Функция СериализоватьСДатамиISO(Данные)
	
	Настройки = Новый НастройкиСериализацииJSON;
	Настройки.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.ISO;
	
	Запись = Новый ЗаписьJSON;
	Запись.УстановитьСтроку();
	
	ЗаписатьJSON(Запись, Данные, Настройки);
	
	Возврат Запись.Закрыть();
	
КонецФункции

Теперь при отправке данных любые поля типа Дата будут автоматически преобразованы в строку формата ISO.

Советы по отладке и публикации

Чтобы ваш HTTP-сервис заработал, недостаточно просто написать код. Пройдемся по чек-листу для запуска:

Публикация на веб-сервере. Сервисы работают только через веб-сервер (IIS или Apache). Необходимо выполнить публикацию базы через меню "Администрирование -> Публикация на веб-сервере" и обязательно установить галочку "Публиковать HTTP-сервисы".
Файл default.vrd. Проверьте, что в файле публикации прописан ваш сервис.
Пользователь и права. Для доступа к сервису лучше создать отдельного пользователя в 1С (например, WebRobot) и назначить ему роль, дающую права на использование этого конкретного HTTP-сервиса.
Тестирование. Для проверки работы используйте инструменты вроде Postman. Адрес вашего сервиса будет выглядеть примерно так: http://server/base_name/hs/api/orders.

Заключение

Мы проанализировали процесс создания REST-интерфейса в 1С. Использование связки HTTPСервис + ЧтениеJSON / ЗаписьJSON позволяет реализовать гибкий и быстрый обмен данными. Главное — следить за корректной установкой заголовков Content-Type и обрабатывать возможные исключения, возвращая клиенту понятные статусы ошибок.