API 1С: интеграция через HTTP-сервисы, OData и веб-сервисы

Какие API есть у 1С:Предприятия

Под «API 1С» обычно понимают любой способ, которым внешняя программа читает или меняет данные информационной базы. Платформа 8.3 даёт несколько таких механизмов, и выбор зависит от того, кто инициирует обмен, какой нужен формат и готовы ли вы писать код на стороне 1С.

Механизм	Протокол и формат	Когда выбирать
HTTP-сервисы	HTTP, любой формат (обычно JSON)	Свой REST API с нужной структурой ответов, интеграция с сайтом, мобильным приложением, маркетплейсом
Стандартный интерфейс OData	HTTP, OData версии 3, JSON или Atom XML	Быстрый доступ к справочникам, документам и регистрам без программирования в 1С, выгрузка в BI и хранилища
Веб-сервисы	SOAP, WSDL, XML	Корпоративные системы, которые работают только с SOAP, строгий контракт операций
COM-соединение	COM, только Windows	Внешние скрипты и программы на той же машине или в локальной сети, обмен между базами 1С
Файловый обмен	XML, JSON, CSV через каталог или FTP	Нет прямой связи между системами, пакетная передача по расписанию

HTTP-сервисы, OData и веб-сервисы работают через веб-сервер, поэтому сначала базу нужно опубликовать. COM-соединение описано в отдельной статье, файловый обмен — в материале про XML в 1С и обмены через план обмена.

Публикация базы на веб-сервере

Без публикации ни HTTP-сервисы, ни OData снаружи не видны. Публикация делается в конфигураторе («Администрирование → Публикация на веб-сервере») или утилитой webinst для Apache и IIS — подробно процесс разобран в статье про сервер 1С и веб-публикацию. В диалоге публикации важны флажки:

• Публиковать HTTP-сервисы по умолчанию — включает все HTTP-сервисы конфигурации; на вкладке HTTP-сервисов можно отметить только нужные.
• Публиковать стандартный интерфейс OData — без него адрес /odata/standard.odata вернёт ошибку.
• Веб-сервисы — список SOAP-сервисов с их адресами публикации.

Результат сохраняется в файле default.vrd в каталоге публикации. После изменения состава сервисов в конфигурации публикацию нужно обновить, иначе новые адреса вернут 404.

HTTP-сервисы 1С: свой REST API

HTTP-сервис — объект метаданных в ветке «Общие → HTTP-сервисы». Его структура трёхуровневая:

1. Сервис со свойством «Корневой URL», например api.
2. Шаблоны URL — группы ресурсов, например /goods/{code}. Части в фигурных скобках становятся параметрами.
3. Методы шаблона — GET, POST, PUT, DELETE и другие. Для каждого метода указывается обработчик в модуле сервиса.

Итоговый адрес имеет вид http://сервер/имя_публикации/hs/корневой_URL/шаблон. Для сервиса выше это https://srv.example.ru/trade/hs/api/goods/00-0001. Сегмент hs обязателен: по нему веб-расширение понимает, что запрос адресован HTTP-сервису.

Обработчик GET: отдать товар по коду

Обработчик — функция модуля HTTP-сервиса, которая принимает объект HTTPСервисЗапрос и возвращает HTTPСервисОтвет. Параметры шаблона берутся из ПараметрыURL, параметры строки запроса (после ?) — из ПараметрыЗапроса.

Функция GoodsGET(Запрос)

	Код = Запрос.ПараметрыURL.Получить("code");
	Ссылка = Справочники.Номенклатура.НайтиПоКоду(Код);

	Если Ссылка.Пустая() Тогда
		Возврат ОтветJSON(404, Новый Структура("error", "Товар не найден"));
	КонецЕсли;

	Данные = Новый Структура;
	Данные.Вставить("code", СокрЛП(Ссылка.Код));
	Данные.Вставить("name", Ссылка.Наименование);
	Данные.Вставить("id", Строка(Ссылка.УникальныйИдентификатор()));

	Возврат ОтветJSON(200, Данные);

КонецФункции

Функция ОтветJSON(КодСостояния, Данные)

	Запись = Новый ЗаписьJSON;
	Запись.УстановитьСтроку();
	ЗаписатьJSON(Запись, Данные);

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

КонецФункции

Явный отказ от BOM важен: многие клиенты на JavaScript и Python не ожидают маркера в начале JSON и падают на разборе. Подробности сериализации — в статье про JSON в 1С.

Обработчик POST: принять JSON

Функция OrdersPOST(Запрос)

	Чтение = Новый ЧтениеJSON;
	Чтение.УстановитьСтроку(Запрос.ПолучитьТелоКакСтроку());
	Попытка
		Данные = ПрочитатьJSON(Чтение);
	Исключение
		Возврат ОтветJSON(400, Новый Структура("error", "Некорректный JSON"));
	КонецПопытки;
	Чтение.Закрыть();

	Если ТипЗнч(Данные) <> Тип("Структура") Или Не Данные.Свойство("number") Тогда
		Возврат ОтветJSON(422, Новый Структура("error", "Не передан number"));
	КонецЕсли;

	// Здесь создание документа, запись в регистр и т.п.

	Возврат ОтветJSON(201, Новый Структура("result", "ok"));

КонецФункции

Код обработчика выполняется на сервере от имени пользователя, под которым прошла аутентификация, поэтому права роли действуют как обычно. Если ключи JSON не являются допустимыми идентификаторами 1С (например, содержат дефис), читайте в соответствие: ПрочитатьJSON(Чтение, Истина).

Свойства, которые стоит настроить

Свойство	Где	Зачем
Корневой URL	HTTP-сервис	Первый сегмент адреса после /hs/; латиница без пробелов
Шаблон	Шаблон URL	Путь ресурса с параметрами в фигурных скобках
HTTP-метод	Метод	GET, POST, PUT, PATCH, DELETE или любой
Повторное использование сеансов	HTTP-сервис	Позволяет не создавать сеанс на каждый запрос; заметно снижает нагрузку при частых вызовах
Время жизни сеанса	HTTP-сервис	Сколько секунд простаивающий сеанс остаётся доступным для повторного использования

Вызов такого сервиса из другой базы 1С пишется через HTTPСоединение и HTTPЗапрос — примеры GET и POST есть в статье HTTP-запросы из 1С к REST API.

OData 1С: REST без программирования

Стандартный интерфейс OData — автоматически создаваемый REST-интерфейс ко всем объектам, которые вы ему разрешили. Платформа реализует протокол OData версии 3 с расширениями фирмы 1С. Чтобы им воспользоваться, нужны два шага: включить флажок OData при публикации и задать состав доступных объектов методом глобального контекста УстановитьСоставСтандартногоИнтерфейсаOData.

&НаСервере
Процедура ВключитьODataНаСервере()

	Состав = ПолучитьСоставСтандартногоИнтерфейсаOData();
	Добавить = Новый Массив;
	Добавить.Добавить(Метаданные.Справочники.Номенклатура);
	Добавить.Добавить(Метаданные.Справочники.Контрагенты);
	Добавить.Добавить(Метаданные.Документы.ЗаказКлиента);

	Для Каждого Объект Из Добавить Цикл
		Если Состав.Найти(Объект) = Неопределено Тогда
			Состав.Добавить(Объект);
		КонецЕсли;
	КонецЦикла;

	УстановитьСоставСтандартногоИнтерфейсаOData(Состав);

КонецПроцедуры

Метод заменяет весь состав целиком, поэтому сначала читаем текущий список и дополняем его. Выполнять код нужно под пользователем с административными правами. В типовых конфигурациях на БСП обычно есть готовая форма настройки состава OData в разделе администрирования (как правило, рядом с настройками синхронизации данных) — там же создаётся отдельный пользователь для доступа.

Как выглядит запрос OData

Адрес собирается из префикса публикации, признака /odata/standard.odata/, имени ресурса и параметров:

GET https://srv.example.ru/trade/odata/standard.odata/$metadata
GET https://srv.example.ru/trade/odata/standard.odata/Catalog_Номенклатура?$format=json&$top=20
GET .../Catalog_Номенклатура?$format=json&$select=Ref_Key,Code,Description
GET .../Catalog_Контрагенты(guid'c3fbdcaf-b8e1-11e4-8271-001e101f0864')?$format=json
GET .../Document_ЗаказКлиента?$format=json&$filter=Posted eq false&$orderby=Date desc
POST .../Document_ЗаказКлиента(guid'...')/Post()

Параметр	Назначение
$format=json	Ответ в JSON; без него возвращается Atom XML. Альтернатива — заголовок Accept: application/json
$filter	Отбор: eq, ne, gt, lt, and, or, функции вроде substringof
$select	Только перечисленные поля — сильно уменьшает объём ответа
$top, $skip	Постраничная выборка
$orderby	Сортировка, asc или desc
$metadata	Описание всех доступных сущностей и полей

Имена ресурсов строятся по типу объекта: Catalog_, Document_, InformationRegister_, AccumulationRegister_ и так далее, а стандартные реквизиты называются по-английски: Ref_Key, Code, Description, DeletionMark, Posted. Точный список полей всегда берите из $metadata своей базы.

Запрос к OData из другой 1С

Ресурс = "/trade/odata/standard.odata/"
	+ КодироватьСтроку("Catalog_Номенклатура", СпособКодированияСтроки.URLВКодировкеURL)
	+ "?$format=json&$top=10&$select=Ref_Key,Code,Description";

Соединение = Новый HTTPСоединение("srv.example.ru", 443, "odata_user", "пароль", ,
	30, Новый ЗащищенноеСоединениеOpenSSL);
Ответ = Соединение.Получить(Новый HTTPЗапрос(Ресурс));

Если Ответ.КодСостояния = 200 Тогда
	Чтение = Новый ЧтениеJSON;
	Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
	Результат = ПрочитатьJSON(Чтение, Истина);
	Для Каждого Строка Из Результат["value"] Цикл
		Сообщить(Строка["Code"] + " " + Строка["Description"]);
	КонецЦикла;
КонецЕсли;

Кириллицу в адресе лучше кодировать явно, как в примере: часть клиентов и прокси-серверов не пропускает её в «сыром» виде.

Веб-сервисы 1С (SOAP)

Веб-сервис создаётся в ветке «Общие → Веб-сервисы». У него задаются пространство имён, XDTO-пакеты с типами, операции с параметрами и типом возвращаемого значения, а для каждой операции — процедура в модуле. После публикации описание доступно по адресу вида http://сервер/имя_публикации/ws/имя_сервиса?wsdl; точное имя (иногда с суффиксом .1cws) видно в диалоге публикации.

Обращение к стороннему веб-сервису из 1С выполняется через динамическую WS-ссылку:

Определения = Новый WSОпределения("https://srv.example.ru/erp/ws/Stock?wsdl",
	"ws_user", "пароль");
Прокси = Новый WSПрокси(Определения, "http://example.ru/stock", "Stock", "StockSoap");
Прокси.Пользователь = "ws_user";
Прокси.Пароль = "пароль";

Остаток = Прокси.GetStock("00-0001");

Аргументы WSПрокси — URI пространства имён, имя сервиса и имя точки подключения; их берут из WSDL. Если контракт стабилен, удобнее статическая WS-ссылка (объект конфигурации «WS-ссылки»): типы и операции будут видны в конфигураторе.

Аутентификация и безопасность

• По умолчанию HTTP-сервисы и OData используют аутентификацию 1С через заголовок Authorization: Basic (логин и пароль в base64). Заведите для интеграции отдельного пользователя с минимальной ролью.
• Basic без шифрования передаёт пароль открыто — снаружи публикуйте только по HTTPS.
• Если сервис должен работать без формы входа, пользователя можно задать в публикации; как это сделать, описано в статье про авторизацию опубликованной базы. Тогда ограничивайте доступ на уровне веб-сервера.
• Для публичных API добавьте свою проверку токена в заголовке запроса внутри обработчика.

Типичные ошибки при подключении по API

Симптом	Причина и решение
404 на адрес /hs/...	Сервис не отмечен в публикации, опечатка в корневом URL или шаблоне, публикация не обновлена после изменения конфигурации
401	Нет заголовка авторизации, неверный пароль или у пользователя нет права на вход
500	Исключение в обработчике. Текст ошибки смотрите в журнале регистрации; оберните опасные места в Попытка и возвращайте понятный код
OData отдаёт пустой список сущностей	Не вызван УстановитьСоставСтандартногоИнтерфейсаOData или флажок OData не включён в публикации
Клиент не разбирает JSON	В ответе BOM или неверный Content-Type
Медленные ответы при частых вызовах	На каждый запрос создаётся сеанс: включите повторное использование сеансов, сократите объём выборки через $select и $top

Что выбрать для интеграции 1С

Если нужно быстро отдать данные во внешнюю систему и она умеет OData — начните со стандартного интерфейса: это ноль кода в конфигурации. Когда нужен свой контракт, проверка бизнес-логики, агрегированные ответы или приём заказов с сайта — пишите HTTP-сервис. Веб-сервисы оставьте для партнёров, которые требуют SOAP и WSDL. Изменения в типовой конфигурации, включая новые HTTP-сервисы, удобнее держать в расширении — так они переживут обновления.