Интеграция с внешними системами через REST API — одна из самых частых задач, с которыми мы сталкиваемся при разработке на платформе 1С:Предприятие. Будь то обмен данными с интернет-магазином, отправка сообщений в мессенджеры или интеграция с банковскими сервисами, нам необходимо уметь корректно формировать и отправлять HTTP-запросы.
В этой статье мы подробно разберем, как программно реализовать взаимодействие с веб-сервисами. Мы рассмотрим создание соединения, настройку защищенного канала (HTTPS), формирование заголовков, сериализацию данных в JSON и обработку полученных ответов. Проанализируем примеры кода для методов GET и POST, а также обсудим распространенные ошибки.
Для работы с протоколом HTTP в платформе 1С предусмотрено несколько ключевых объектов. Давайте рассмотрим их назначение перед тем, как переходить к коду:
HTTPСоединение — этот объект отвечает за установку канала связи с сервером. Именно здесь мы указываем адрес хоста, порт, логин/пароль (если используется базовая авторизация) и настройки защищенного соединения.HTTPЗапрос — объект, который содержит информацию о конкретном запросе: адрес ресурса (URI), заголовки и тело запроса (для методов POST/PUT).HTTPОтвет — результат выполнения запроса, содержащий код состояния (например, 200 или 404), заголовки ответа и тело (данные, которые вернул сервер).Теперь разберем процесс по шагам, начиная с настройки соединения.
При создании экземпляра HTTPСоединение нам необходимо определить, с каким именно сервером мы будем работать. Важный момент, который часто упускают новички: если адрес начинается с https://, нам обязательно нужно использовать защищенное соединение OpenSSL.
Давайте посмотрим, как правильно инициализировать соединение. Предположим, нам нужно подключиться к хосту api.example.com.
// Определяем параметры подключения
Сервер = "api.example.com";
Порт = 443; // Стандартный порт для HTTPS
ИспользоватьSSL = Истина; // Флаг использования защищенного соединения
// Создаем описание защищенного соединения
Если ИспользоватьSSL Тогда
ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
Иначе
ЗащищенноеСоединение = Неопределено;
КонецЕсли;
// Инициализируем соединение
Соединение = Новый HTTPСоединение(
Сервер,
Порт,
, // Пользователь (если нужна базовая авторизация на уровне сервера)
, // Пароль
, // Прокси
, // Таймаут
ЗащищенноеСоединение
);
Обратите внимание на параметр ЗащищенноеСоединениеOpenSSL. Без него при попытке обратиться к адресу https 1С выдаст ошибку. Если вы работаете с самоподписанными сертификатами (например, внутри локальной сети), в конструктор ЗащищенноеСоединениеOpenSSL можно передать клиентский сертификат или сертификат удостоверяющего центра.
Большинство современных API требуют указания заголовков, чтобы понимать, в каком формате мы отправляем данные и в каком формате ожидаем ответ. Рассмотрим создание заголовков для работы с JSON.
Заголовки = Новый Соответствие;
// Указываем, что мы отправляем данные в формате JSON
Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
// Указываем, что мы ожидаем ответ также в формате JSON
Заголовки.Вставить("Accept", "application/json");
// Если API требует авторизацию по токену
Токен = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
Заголовки.Вставить("Authorization", "Bearer " + Токен);
Важно всегда указывать кодировку charset=utf-8 в Content-Type, чтобы избежать проблем с кириллицей при передаче данных.
Метод GET используется для получения данных. Давайте рассмотрим, как запросить список заказов по определенному адресу ресурса.
// Адрес ресурса на сервере (например, /v1/orders?status=new)
Ресурс = "/v1/orders?status=new";
// Создаем объект запроса
Запрос = Новый HTTPЗапрос(Ресурс, Заголовки);
Попытка
// Выполняем запрос
Ответ = Соединение.Получить(Запрос);
// Проверяем код состояния
Если Ответ.КодСостояния = 200 Тогда
// Успешно получили данные
СтрокаОтвета = Ответ.ПолучитьТелоКакСтроку("UTF-8");
// Далее здесь будет код разбора ответа (см. Шаг 5)
Иначе
// Обработка ошибки
Сообщить("Ошибка запроса: " + Ответ.КодСостояния);
Сообщить(Ответ.ПолучитьТелоКакСтроку());
КонецЕсли;
Исключение
// Обработка технических ошибок соединения (нет интернета, таймаут и т.д.)
Сообщить("Не удалось выполнить запрос: " + ОписаниеОшибки());
КонецПопытки;
В методе ПолучитьТелоКакСтроку мы также явно указываем кодировку "UTF-8", чтобы платформа корректно интерпретировала байты ответа.
Метод POST используется для отправки данных (например, создание нового документа). Для этого нам нужно сначала сериализовать данные 1С (структуру или массив) в строку JSON, а затем поместить эту строку в тело запроса.
Разберем этот процесс подробно. Сначала подготовим данные.
// Подготовка данных для отправки
ДанныеЗаказа = Новый Структура;
ДанныеЗаказа.Вставить("number", "00001");
ДанныеЗаказа.Вставить("date", "2023-10-27");
ДанныеЗаказа.Вставить("amount", 5000);
ДанныеЗаказа.Вставить("client", "ООО Ромашка");
МассивТоваров = Новый Массив;
Товар1 = Новый Структура("product, quantity, price", "Товар А", 2, 1000);
Товар2 = Новый Структура("product, quantity, price", "Товар Б", 1, 3000);
МассивТоваров.Добавить(Товар1);
МассивТоваров.Добавить(Товар2);
ДанныеЗаказа.Вставить("items", МассивТоваров);
Теперь выполним сериализацию в JSON. Для этого используем объект ЗаписьJSON.
// Настройка параметров записи JSON
ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Нет, " ", Истина);
// "Истина" в конце экранирует слеши, что иногда важно для API
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку(ПараметрыЗаписи);
// Записываем структуру в JSON
ЗаписатьJSON(ЗаписьJSON, ДанныеЗаказа);
СтрокаJSON = ЗаписьJSON.Закрыть();
Когда строка JSON готова, создадим POST-запрос и отправим его.
Ресурс = "/v1/orders";
ЗапросPOST = Новый HTTPЗапрос(Ресурс, Заголовки);
// Устанавливаем тело запроса
ЗапросPOST.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Попытка
// Используем метод ОтправитьДляОбработки для POST запросов
Ответ = Соединение.ОтправитьДляОбработки(ЗапросPOST);
Если Ответ.КодСостояния = 201 Или Ответ.КодСостояния = 200 Тогда
Сообщить("Заказ успешно создан!");
// Читаем ответ сервера (там может быть ID созданного заказа)
ОтветСервера = Ответ.ПолучитьТелоКакСтроку("UTF-8");
Иначе
Сообщить("Ошибка создания заказа. Код: " + Ответ.КодСостояния);
Сообщить("Тело ошибки: " + Ответ.ПолучитьТелоКакСтроку());
КонецЕсли;
Исключение
Сообщить("Критическая ошибка: " + ОписаниеОшибки());
КонецПопытки;
Обратите внимание на использование КодировкаТекста.UTF8 при установке тела. Это гарантирует, что сервер на другой стороне корректно прочитает кириллические символы в вашем JSON.
Получив ответ от сервера в виде строки, нам часто требуется превратить его обратно в объекты 1С (Структуры и Массивы) для дальнейшей обработки. Рассмотрим, как это сделать правильно.
Функция ПрочитатьОтветJSON(СтрокаОтвета)
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаОтвета);
// Прочитаем JSON в Соответствие (или Структуру)
// Второй параметр Истина позволяет читать поля как Соответствие,
// что полезно, если имена полей не соответствуют правилам именования переменных 1С
Результат = ПрочитатьJSON(ЧтениеJSON, Истина);
ЧтениеJSON.Закрыть();
Возврат Результат;
КонецФункции
Использование флага Истина во втором параметре метода ПрочитатьJSON (или использование параметра ИменаСвойствВСоответствие в более новых версиях) является хорошей практикой. Это защищает от ошибок, если API возвращает поля с именами, содержащими пробелы, начинающимися с цифр или зарезервированными словами.
Давайте резюмируем несколько важных моментов, которые помогут избежать типовых проблем при интеграции:
HTTPСоединение всегда задавайте таймаут (6-й параметр). По умолчанию он может быть слишком большим или маленьким. Рекомендуемое значение для API — 30-60 секунд.ИнтернетПрокси и передайте его в соединение.ЗаписатьJSON дата может записаться в специфичном формате 1С. Для корректной передачи дат используйте преобразование дат в строку формата YYYY-MM-DDThh:mm:ss перед записью, либо используйте НастройкиСериализацииJSON с указанием формата даты.Записать() (для PUT), Изменить() (для PATCH) и Удалить() (для DELETE).Применяя эти методы и подходы, вы сможете построить надежную и быструю интеграцию вашего прикладного решения 1С с любыми внешними веб-сервисами.