Интеграция 1С с внешними сервисами через API (Application Programming Interface) — одна из самых частых и востребованных задач для современного разработчика. Внешними системами могут выступать интернет-магазины, службы доставки, CRM-системы, государственные порталы, мессенджеры или сервисы проверки контрагентов. Для начинающего программиста обилие терминов (REST, SOAP, JSON, HTTP-сервисы, POST/GET запросы) может показаться пугающим.
В этой статье мы подробно и по шагам разберем, как устроена интеграция в 1С, изучим примеры кода из практики разработчиков, а также рассмотрим современные стандарты взаимодействия с внешними API.
Простыми словами, API — это набор правил и способов, с помощью которых одна программа может общаться с другой. В контексте 1С это означает, что наша база данных может либо сама отправлять запросы к стороннему сайту (выступать в роли HTTP-клиента), либо принимать запросы от внешних систем (выступать в роли HTTP-сервера).
В платформе «1С:Предприятие 8» для реализации интеграций используются следующие ключевые механизмы:
HTTPСоединение, HTTPЗапрос, HTTPОтвет) — основной инструмент для отправки данных во внешние REST API.Прежде чем перейти к написанию кода, важно разобрать типичные ошибки и устаревшие подходы, которые часто встречаются на форумах прошлых лет. Проанализируем ключевые изменения в технологиях интеграции:
ПрочитатьJSON() и ЗаписатьJSON().WinHttp.WinHttpRequest.5.1 (пример из сообщения 30). Этот код категорически не подходит для современных реалий: если сервер 1С запущен на операционной системе Linux, вызов COM-объекта приведет к критической ошибке. Наш выбор — использовать исключительно встроенные объекты 1С: HTTPСоединение и HTTPЗапрос.Рассмотрим классический пример отправки GET-запроса к внешнему веб-сервису. Предположим, нам необходимо отправить запрос к геокодеру или сервису подсказок и получить ответ.
Разберем современный кроссплатформенный шаблон отправки GET-запроса:
// Определяем параметры подключения
Сервер = "api.service.com";
Порт = 443; // Используем стандартный порт для защищенного соединения HTTPS
// Создаем защищенное соединение (SSL)
ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
// Инициализируем HTTP-соединение. Если требуется авторизация,
// логин и пароль можно передать 3-м и 4-м параметрами.
Соединение = Новый HTTPСоединение(Сервер, Порт, , , , , ЗащищенноеСоединение);
// Формируем адрес ресурса с параметрами запроса
АдресРесурса = "/v1/geocode?address=" + КодироватьСтроку("Москва, Кремль") + "&key=ВАШ_API_КЛЮЧ";
// Создаем HTTP-запрос
Запрос = Новый HTTPЗапрос(АдресРесурса);
Запрос.Заголовки.Вставить("Accept", "application/json");
Попытка
// Отправляем запрос методом GET
Ответ = Соединение.Получить(Запрос);
// Проверяем код состояния ответа (200 OK — успешный запрос)
Если Ответ.КодСостояния = 200 Тогда
СтрокаJSON = Ответ.ПолучитьТелоКакСтроку("UTF-8");
// Разбираем полученный JSON-ответ в структуру 1С
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
ДанныеОтвета = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
// Здесь мы можем работать с ДанныеОтвета как с обычной Структурой или Массивом
ВывестиРезультатВКонсоль(ДанныеОтвета);
Иначе
ВызватьИсключение "Ошибка сервиса. Код ответа: " + Ответ.КодСостояния;
КонецЕсли;
Исключение
ЗаписатьВЖурналРегистрации("Интеграция.Ошибка", УровеньЖурналаРегистрации.Ошибка, , , ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()));
ВызватьИсключение "Не удалось связаться с внешним сервисом API.";
КонецПопытки;
В этом примере мы использовали метод КодироватьСтроку(). Это критически важно, поскольку любые параметры запроса, передаваемые через строку URL (например, кириллица или спецсимволы в адресе), должны быть приведены к правильному интернет-формату (URL-encoded).
Когда нам нужно не просто получить информацию, а передать сложные данные во внешнюю систему (например, выгрузить заказ или контрагента), используется метод POST. В этом случае данные передаются не в строке адреса, а в теле самого запроса.
Давайте разберем, как упаковать структуру 1С в JSON-строку и отправить ее на сервер:
// Подготавливаем данные для отправки в виде структуры 1С
ДанныеКонтрагента = Новый Структура;
ДанныеКонтрагента.Вставить("Inn", "7700000000");
ДанныеКонтрагента.Вставить("Kpp", "770101001");
ДанныеКонтрагента.Вставить("Name", "ООО Ромашка");
// Сериализуем структуру в формат JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеКонтрагента);
ТелоЗапросаСтрокой = ЗаписьJSON.Закрыть();
// Создаем соединение и запрос
Соединение = Новый HTTPСоединение("api.service.com", 443, , , , , Новый ЗащищенноеСоединениеOpenSSL());
Запрос = Новый HTTPЗапрос("/v1/contragents/add");
// Настраиваем заголовки запроса. Это сообщает серверу, что мы передаем JSON в кодировке UTF-8
Запрос.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
// Устанавливаем тело запроса из подготовленной JSON-строки
Запрос.УстановитьТелоИзСтроки(ТелоЗапросаСтрокой, КодировкаТекста.UTF8, ИспользованиеМаркераПоследовательностиБайтов.НеИспользовать);
Попытка
// Отправляем POST-запрос
Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Если Ответ.КодСостояния = 201 Или Ответ.КодСостояния = 200 Тогда
Сообщить("Данные успешно отправлены в API!");
Иначе
Сообщить("Ошибка отправки. Код ответа сервера: " + Ответ.КодСостояния);
КонецЕсли;
Исключение
Сообщить("Произошла сетевая ошибка: " + КраткоеПредставлениеОшибки(ИнформацияОбОшибке()));
КонецПопытки;
Иногда задача стоит противоположным образом: сторонний сервис должен постучаться в 1С и передать какие-то данные (например, статус заказа из интернет-магазина или платеж из банка). Начиная с версии 8.3, в платформе для этого появились удобные HTTP-сервисы.
Разберем по шагам, как настроить и запустить свой простейший веб-сервис в 1С:
УправлениеЗаказами).orders_api./get_status/{IDЗаказа}. Параметр в фигурных скобках означает, что эта часть пути будет динамической (переменной).GET. Укажите имя обработчика в модуле HTTP-сервиса (платформа может сгенерировать его автоматически).Теперь напишем программный код в модуле нашего HTTP-сервиса, который будет принимать ID заказа из URL, находить его в базе и возвращать статус обратно в формате JSON:
Функция ПолучитьСтатусGET(Запрос)
// Получаем динамический параметр из URL запроса
ИдентификаторЗаказа = Запрос.ПараметрыШаблона["IDЗаказа"];
// Подготовим структуру для будущего JSON-ответа
СтруктураОтвета = Новый Структура;
// Попытаемся найти документ в базе 1С
СсылкаНаЗаказ = Документы.ЗаказПокупателя.НайтиПоРеквизиту("НомерНа Сайте", ИдентификаторЗаказа);
Если ЗначениеЗаполнено(СсылкаНаЗаказ) Тогда
// Если нашли — возвращаем успешный статус
СтруктураОтвета.Вставить("status", "success");
СтруктураОтвета.Вставить("order_number", СсылкаНаЗаказ.Номер);
СтруктураОтвета.Вставить("state", Строка(СсылкаНаЗаказ.СтатусЗаказа));
СтруктураОтвета.Вставить("amount", СсылкаНаЗаказ.СуммаДокумента);
КодОтвета = 200; // ОК
Иначе
// Если не нашли — возвращаем ошибку
СтруктураОтвета.Вставить("status", "error");
СтруктураОтвета.Вставить("message", "Заказ с указанным ID не найден в системе 1С.");
КодОтвета = 404; // Not Found
КонецЕсли;
// Преобразуем структуру ответа в JSON-строку
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, СтруктураОтвета);
СтрокаJSON = ЗаписьJSON.Закрыть();
// Формируем HTTP-ответ
Ответ = Новый HTTPСервисОтвет(КодОтвета);
Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Ответ.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеМаркераПоследовательностиБайтов.НеИспользовать);
Возврат Ответ;
КонецФункции
Чтобы этот HTTP-сервис заработал и стал доступен внешнему миру, базу 1С необходимо опубликовать на веб-сервере (IIS или Apache). После публикации внешние системы смогут обращаться к вашему API по адресу вида: https://имя_сервера/имя_публикации/hs/orders_api/get_status/12345.
Для того чтобы закрепить полученные знания и "набить руку", начинающему разработчику лучше всего использовать простые и хорошо документированные открытые API. Рассмотрим три лучших варианта:
sendMessage). Это очень наглядно: написали код в 1С, нажали кнопку — и тут же получили сообщение на телефоне.Частая ошибка начинающих интеграторов в 1С — пытаться сразу писать код в конфигураторе. Если в коде закралась ошибка, сложно понять, где именно проблема: неверно сформирован запрос в 1С, заблокирован порт брандмауэром, не пройдена авторизация или удаленный сервер ожидает другие параметры.
Золотое правило разработки интеграций: сначала соберите и проверьте ваш запрос во внешней специализированной программе, убедитесь в успешном получении ответа, и только потом переносите логику в код 1С.
Самым популярным инструментом для этих целей является бесплатная утилита Postman. В ней вы можете в визуальном режиме:
После того как запрос успешно отработал в Postman, повторить его структуру на встроенном языке 1С с помощью объектов HTTPСоединение и HTTPЗапрос не составит никакого труда.