В современной разработке на платформе 1С:Предприятие 8.3 интеграция с внешними веб-сервисами через REST API стала повседневной задачей. Часто возникают вопросы: как правильно сформировать структуру JSON, как передать токен авторизации и как обработать ответ от сервера, если он возвращает ошибку. В данной статье мы подробно разберем процесс настройки обмена данными, основываясь на практических примерах и механизмах платформы.
Прежде чем отправлять данные, нам необходимо создать объект HTTPСоединение. Этот объект является фундаментом для взаимодействия с внешним сервером. Проанализируем, какие параметры критически важны при его создании. Нам потребуется адрес сервера, порт (обычно 443 для защищенного соединения) и, при необходимости, настройки прокси-сервера или защищенного соединения ЗащищенноеСоединениеOpenSSL.
Рассмотрим пример создания базового соединения:
Сервер = "api.service.com";
Порт = 443;
ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
Попытка
Соединение = Новый HTTPСоединение(Сервер, Порт, , , , 30, ЗащищенноеСоединение);
Исключение
Сообщить("Не удалось установить соединение с сервером: " + ОписаниеОшибки());
Возврат;
КонецПопытки;
Обратим внимание, что использование ЗащищенноеСоединениеOpenSSL без параметров позволяет системе использовать стандартные сертификаты ОС. Если ваш сервер использует самоподписанный сертификат, может потребоваться дополнительная настройка валидации. Также мы установили таймаут в 30 секунд, что является оптимальным для большинства синхронных запросов.
Большинство современных API требуют передачи данных в формате JSON. В 1С для этого удобнее всего использовать связку Структура, Массив и объект ЗаписьJSON. Давайте разберем по шагам, как преобразовать данные 1С в строку, понятную внешнему сервису.
Предположим, нам нужно отправить информацию о заказе клиента. Для этого мы создадим структуру, наполним её данными и сериализуем:
ДанныеДляОтправки = Новый Структура;
ДанныеДляОтправки.Вставить("order_id", "INV-2023-001");
ДанныеДляОтправки.Вставить("amount", 15500.50);
ДанныеДляОтправки.Вставить("currency", "RUB");
МассивТоваров = Новый Массив;
Товар1 = Новый Структура("sku, quantity", "ITEM-01", 2);
Товар2 = Новый Структура("sku, quantity", "ITEM-02", 1);
МассивТоваров.Добавить(Товар1);
МассивТоваров.Добавить(Товар2);
ДанныеДляОтправки.Вставить("items", МассивТоваров);
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеДляОтправки);
СтрокаJSON = ЗаписьJSON.Закрыть();
Использование метода ЗаписатьJSON позволяет автоматически обрабатывать типы данных. Однако стоит помнить, что даты в 1С и стандарты ISO 8601 могут различаться, поэтому для дат иногда требуется предварительное преобразование в строку или настройка параметров записи.
Теперь, когда у нас есть тело запроса, перейдем к созданию объекта HTTPЗапрос. Важнейшим этапом здесь является установка заголовков (headers). Если сервис требует авторизацию по токену (например, Bearer token), мы должны добавить соответствующий заголовок Authorization. Также обязательно указываем Content-Type, чтобы сервер понимал, что мы прислали именно JSON.
Разберем процесс настройки заголовков подробнее:
АдресРесурса = "/v1/orders/create";
Запрос = Новый HTTPЗапрос(АдресРесурса);
// Устанавливаем стандартные заголовки
Запрос.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
// Добавляем авторизацию (замените ВашТокен на реальный ключ)
Токен = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
// Помещаем тело запроса
Запрос.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Важный нюанс: при использовании УстановитьТелоИзСтроки рекомендуется явно указывать ИспользованиеByteOrderMark.НеИспользовать. Некоторые веб-серверы некорректно обрабатывают BOM-символы в начале строки, что приводит к ошибке парсинга JSON на стороне получателя.
После подготовки запроса мы выполняем его методом ОтправитьДляОбъекта (или ВызватьHTTPМетод, если это не стандартные GET/POST). Результатом выполнения будет объект HTTPОтвет. Нам необходимо проанализировать код состояния (Status Code), чтобы понять, успешно ли прошла операция.
Выясним причину возможных ошибок, анализируя код ответа:
Попытка
Ответ = Соединение.ВызватьHTTPМетод("POST", Запрос);
КодСостояния = Ответ.КодСостояния;
Если КодСостояния = 200 Или КодСостояния = 201 Тогда
// Успешно создано
ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
Сообщить("Данные успешно отправлены. Ответ сервера: " + ТелоОтвета);
ИначеЕсли КодСостояния = 401 Тогда
Сообщить("Ошибка авторизации! Проверьте валидность токена.");
Иначе
Сообщить("Сервер вернул ошибку с кодом: " + КодСостояния);
Сообщить("Текст ошибки: " + Ответ.ПолучитьТелоКакСтроку());
КонецЕсли;
Исключение
Сообщить("Ошибка при выполнении запроса: " + ОписаниеОшибки());
КонецПопытки;
Проанализируем типичные коды ответов. 200 (OK) и 201 (Created) означают успех. 400 (Bad Request) обычно указывает на ошибку в структуре JSON. 403 (Forbidden) говорит об отсутствии прав доступа, даже если токен верен. 500 (Internal Server Error) свидетельствует о проблемах на стороне сервера.
Если сервер вернул данные, нам нужно преобразовать их обратно в объекты 1С для дальнейшей работы. Для этого мы используем ЧтениеJSON. Рассмотрим, как извлечь идентификатор созданной записи из ответа сервера:
Если КодСостояния = 200 Тогда
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
Результат = ПрочитатьJSON(Чтение);
Чтение.Закрыть();
// Допустим, сервер возвращает структуру {"status": "success", "id": "12345"}
Если ТипЗнч(Результат) = Тип("Структура") И Результат.Свойство("id") Тогда
НовыйID = Результат.id;
Сообщить("Создан объект с ID: " + НовыйID);
КонецЕсли;
КонецЕсли;
Метод ПрочитатьJSON по умолчанию превращает объекты JSON в Структуры, а массивы — в Массивы 1С. Это позволяет легко обращаться к полям через точку или по индексу.
Работа с внешними системами требует особого внимания к деталям. Рассмотрим несколько рекомендаций, которые помогут сделать ваш код более надежным:
JSON и полученный ответ в журнал регистрации или отдельный справочник логов. Это незаменимо при поиске причин ошибок на этапе эксплуатации.JSON (что крайне не рекомендуется) можно забыть про экранирование кавычек. Всегда используйте ЗаписатьJSON.Подводя итог, мы проанализировали полный цикл взаимодействия 1С с внешним REST-сервисом. Мы научились создавать соединение, формировать структуру данных, настраивать специфические заголовки авторизации и обрабатывать результат. Эти знания позволят вам успешно интегрировать 1С с любыми современными облачными сервисами, маркетплейсами или государственными информационными системами.