Интеграции 1С с внешними сервисами: REST, SOAP, JSON и API — полное руководство для начинающих
Узнайте, как подключить любой сервис через API! Разбираем REST, SOAP, JSON на реальных примерах с кодом — от первого запроса до полноценной интеграции. После этой статьи вы сможете получать курсы валют, загружать заказы и синхронизировать данные между системами.
Современные бизнес-процессы редко работают в изоляции. Система учёта 1С должна обмениваться данными с сайтами, CRM-системами, службами доставки, банками и десятками других сервисов. Для этого используются API — программные интерфейсы, позволяющие системам общаться друг с другом. Разберёмся, как это работает и как начать создавать интеграции в 1С.
Что такое API и зачем они нужны?
API (Application Programming Interface) — это набор правил, по которым одна программа может запросить данные или функции у другой. Представьте, что вы заходите в ресторан. Вы не идёте на кухню готовить сами — вы говорите официанту, что хотите заказать, он передаёт заказ на кухню, а потом приносит готовое блюдо. API работает как этот официант: он принимает запросы, обрабатывает их и возвращает результат.
Типичные задачи интеграции 1С:
Загрузка заказов с интернет-магазина
Отправка документов в банк
Получение курсов валют
Синхронизация с CRM-системами
Отправка данных в службы доставки
Получение информации о контрагентах из внешних баз
REST и SOAP: два подхода к созданию API
SOAP — классический подход
SOAP (Simple Object Access Protocol) — это протокол обмена данными, который появился в конце 90-х. Он использует XML для передачи сообщений и имеет строгую структуру.
Пример SOAP-запроса:
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetClientInfo xmlns="http://example.com/">
<ClientID>12345</ClientID>
</GetClientInfo>
</soap:Body>
</soap:Envelope>SOAP-сервисы описываются с помощью WSDL (Web Services Description Language) — специального файла, который содержит всю информацию о доступных методах, параметрах и типах данных. Это как подробная инструкция по использованию API.
Плюсы SOAP:
Строгая типизация и проверка данных
Встроенная поддержка безопасности
Поддержка сложных операций и транзакций
Стандартизированная обработка ошибок
Минусы SOAP:
Громоздкий XML увеличивает размер передаваемых данных
Сложнее в освоении и настройке
Медленнее работает из-за обработки XML
REST — современный стандарт
REST (Representational State Transfer) — это архитектурный стиль, который использует стандартные HTTP-методы. REST проще, легче и работает быстрее SOAP.
Основные HTTP-методы в REST:
GET — получить данные
POST — создать новую запись
PUT — обновить существующую запись
DELETE — удалить запись
Пример REST-запроса (получение информации о клиенте):
GET https://api.example.com/clients/12345Плюсы REST:
Простота использования
Быстрая работа
Компактные данные (обычно JSON)
Легко тестировать через браузер или Postman
Минусы REST:
Меньше стандартизации (каждый API может быть устроен по-своему)
Нет встроенной поддержки сложных операций
JSON — язык обмена данными
JSON (JavaScript Object Notation) — это текстовый формат для передачи структурированных данных. Он стал стандартом для REST API благодаря простоте и читаемости.
Пример JSON-данных:
{
"clientId": "12345",
"name": "ООО Ромашка",
"inn": "7701234567",
"contacts": {
"phone": "+7 495 123-45-67",
"email": "info@romashka.ru"
},
"orders": [
{
"id": "ORD-001",
"date": "2024-12-01",
"amount": 45000
}
]
}JSON легко читается человеком и просто обрабатывается программно. В 1С для работы с JSON есть встроенные инструменты.
Работа с HTTP-запросами в 1С
Для отправки и получения данных через API в 1С используется объект HTTPСоединение и HTTPЗапрос.
Простой GET-запрос
// Создаём соединение с сервером
Соединение = Новый HTTPСоединение(
"api.example.com", // адрес сервера
443, // порт (443 для HTTPS)
, // логин
, // пароль
, // прокси
30, // таймаут в секундах
Новый ЗащищенноеСоединениеOpenSSL() // для HTTPS
);
// Создаём запрос
Запрос = Новый HTTPЗапрос("/clients/12345");
// Отправляем запрос и получаем ответ
Ответ = Соединение.Получить(Запрос);
// Проверяем код ответа
Если Ответ.КодСостояния = 200 Тогда
ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
Сообщить(ТелоОтвета);
Иначе
Сообщить("Ошибка: " + Ответ.КодСостояния);
КонецЕсли;POST-запрос с JSON-данными
// Подготавливаем данные
ДанныеJSON = Новый Структура;
ДанныеJSON.Вставить("name", "ООО Василёк");
ДанныеJSON.Вставить("inn", "7702345678");
// Преобразуем в JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеJSON);
СтрокаJSON = ЗаписьJSON.Закрыть();
// Создаём запрос
Запрос = Новый HTTPЗапрос("/clients");
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.УстановитьТелоИзСтроки(СтрокаJSON);
// Отправляем
Соединение = Новый HTTPСоединение("api.example.com", 443, , , , 30,
Новый ЗащищенноеСоединениеOpenSSL());
Ответ = Соединение.ОтправитьДляОбработки(Запрос);
// Обрабатываем ответ
Если Ответ.КодСостояния = 201 Тогда
Сообщить("Клиент успешно создан");
КонецЕсли;Парсинг JSON в 1С
Для чтения JSON используется ЧтениеJSON:
СтрокаJSON = Ответ.ПолучитьТелоКакСтроку();
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
Данные = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
// Теперь можем обращаться к данным
Имя = Данные["name"];
ИНН = Данные["inn"];
Телефон = Данные["contacts"]["phone"];Если структура JSON известна заранее, можно использовать десериализацию в структуру:
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
Данные = ПрочитатьJSON(ЧтениеJSON, Истина); // Истина = читать в структуру
ЧтениеJSON.Закрыть();
Аутентификация в API
Большинство API требуют аутентификации. Основные методы:
Basic Authentication
Логин и пароль передаются в заголовке:
Запрос = Новый HTTPЗапрос("/api/data");
Логин = "user";
Пароль = "password";
СтрокаАвторизации = Base64Строка(Логин + ":" + Пароль);
Запрос.Заголовки.Вставить("Authorization", "Basic " + СтрокаАвторизации);API Key
Специальный ключ передаётся в заголовке или параметре:
Запрос = Новый HTTPЗапрос("/api/data");
Запрос.Заголовки.Вставить("X-API-Key", "ваш_секретный_ключ");Bearer Token (OAuth)
Токен доступа получается отдельным запросом:
Запрос = Новый HTTPЗапрос("/api/data");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);Обработка ошибок
Всегда нужно предусматривать обработку ошибок:
Попытка
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
// Успешный запрос
Данные = ПолучитьДанныеИзОтвета(Ответ);
ИначеЕсли Ответ.КодСостояния = 404 Тогда
ВызватьИсключение("Ресурс не найден");
ИначеЕсли Ответ.КодСостояния = 401 Тогда
ВызватьИсключение("Ошибка авторизации");
Иначе
ВызватьИсключение("Ошибка сервера: " + Ответ.КодСостояния);
КонецЕсли;
Исключение
Сообщить("Ошибка при работе с API: " + ОписаниеОшибки());
ЗаписьЖурналаРегистрации("Интеграция.API",
УровеньЖурналаРегистрации.Ошибка,
,
,
ПодробноеПредставлениеОшибки(ИнформацияОбОшибке())
);
КонецПопытки;Работа с SOAP в 1С
Для работы с SOAP-сервисами 1С может автоматически создать объект на основе WSDL:
// Определяем SOAP-сервис по WSDL
Попытка
WSОпределения = Новый WSОпределения(
"http://example.com/service?wsdl",
"Логин",
"Пароль"
);
// Создаём прокси для работы с сервисом
WSПрокси = Новый WSПрокси(WSОпределения,
"ServiceNamespace",
"ServiceName");
// Вызываем метод сервиса
Результат = WSПрокси.GetClientInfo("12345");
Исключение
Сообщить("Ошибка при работе с SOAP: " + ОписаниеОшибки());
КонецПопытки;Практические советы
Используйте константы для адресов и ключей. Не храните URL и API-ключи прямо в коде — выносите их в константы или настройки. Это упростит изменение параметров подключения.
Логируйте все операции. Записывайте в журнал регистрации все обращения к внешним API: запросы, ответы, ошибки. Это поможет при отладке.
Обрабатывайте таймауты. Внешние сервисы могут быть недоступны или медленно отвечать. Устанавливайте разумные таймауты и корректно обрабатывайте ситуации, когда сервис не отвечает.
Тестируйте с помощью Postman. Перед написанием кода в 1С протестируйте API через Postman или аналогичный инструмент. Это поможет понять структуру запросов и ответов.
Учитывайте лимиты API. Многие сервисы ограничивают количество запросов в единицу времени. Предусмотрите механизмы ограничения частоты обращений.
Используйте асинхронную обработку. Для массовых операций лучше использовать фоновые задания, чтобы не блокировать работу пользователя.
Пример реальной интеграции
Создадим простую интеграцию для получения курса валют с сайта ЦБ РФ:
Функция ПолучитьКурсВалюты(КодВалюты, Дата)
СтрокаДаты = Формат(Дата, "ДФ=dd.MM.yyyy");
Соединение = Новый HTTPСоединение("www.cbr.ru", 443, , , , 30,
Новый ЗащищенноеСоединениеOpenSSL());
Запрос = Новый HTTPЗапрос("/scripts/XML_daily.asp?date_req=" + СтрокаДаты);
Попытка
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
// Парсим XML
Чтение = Новый ЧтениеXML;
Чтение.УстановитьСтроку(ТелоОтвета);
Пока Чтение.Прочитать() Цикл
Если Чтение.ТипУзла = ТипУзлаXML.НачалоЭлемента
И Чтение.Имя = "Valute" Тогда
ТекКод = "";
ТекКурс = 0;
Пока Чтение.ПрочитатьАтрибут() Цикл
Если Чтение.Имя = "ID" И Чтение.Значение = КодВалюты Тогда
// Нашли нужную валюту, читаем курс
Пока Чтение.Прочитать() Цикл
Если Чтение.Имя = "Value" Тогда
Чтение.Прочитать();
СтрокаКурса = СтрЗаменить(Чтение.Значение, ",", ".");
Возврат Число(СтрокаКурса);
КонецЕсли;
КонецЦикла;
КонецЕсли;
КонецЦикла;
КонецЕсли;
КонецЦикла;
Чтение.Закрыть();
КонецЕсли;
Исключение
Сообщить("Ошибка получения курса: " + ОписаниеОшибки());
Возврат 0;
КонецПопытки;
Возврат 0;
КонецФункции
// Использование
Курс = ПолучитьКурсВалюты("R01235", ТекущаяДата()); // USD
Сообщить("Курс доллара: " + Курс);Заключение
Интеграции с внешними сервисами — важная часть современной разработки в 1С. REST API с JSON стали стандартом благодаря простоте и эффективности, хотя SOAP всё ещё используется в корпоративных системах. Начинать лучше с простых GET-запросов, постепенно переходя к более сложным сценариям с POST, PUT, аутентификацией и обработкой ошибок.
Освоив базовые принципы работы с HTTP, JSON и API, вы сможете подключить 1С практически к любому современному сервису — от интернет-магазинов до банковских систем.
Продолжайте обучение!
Изучить эту тему и многое другое можно в Кодике — платформе для изучения программирования с практическими примерами и реальными задачами.
А ещё у нас есть крутой Telegram-канал с дружеским комьюнити разработчиков, где можно задать вопросы, поделиться опытом и быть в курсе новых материалов!