Реализация API обмена данными 1С и ВЕТИС (Меркурий)

У нас эта обработка - основа для обмена Меркурий и УПП 1.3.

Общие принципы

В модуле объекта обработки необходимо реализовать процедуру УстановитьПараметрыОбмена(), которая должна заполнить параметры подключения к ВЕТИС в реквизитах обработки - логин, пароль, ключ API, тестовый или продуктивный контур. После этого можно вызывать экспортные функции модуля объекта обработки. С помощью этих экспортных функций формируется XML запрос и отправляется в ВЕТИС. Результат выдается в виде объекта XDTO - стандартный объект платформы, где XML ответа уже разобран и можно обращаться к его элементам как с полям объекта 1С “через точку”. Если возникает ошибка, то генерируется исключение с сообщением об ошибке.

В ВЕТИС часть запросов выполняется синхронно: отправили запрос, получили ответ. С ними все просто - вызвали функцию АПИ обработки, сразу получили результат. Это, например, функции чтения различных справочников.

Другая часть запросов (заявки в Меркурий) выполняются асинхронно: отправили запрос - получили его идентификатор. И потом с некоторой периодичностью должны проверять - готов ли ответ. Как только ответ готов - получаете его и обрабатываете.

Подробное описание всех операций есть на сайте https://help.vetrf.ru/ . Для каждой операции есть сравнительно подробное описание входного XML-запроса, XML-ответа, примеры запросов и ответов. Данная обработка покрывает только часть API:

Также реализованы функции получения

• номера ВСД по УИД,
• номера возвратной и исходной ВСД по УИД

через парсинг регулярным выражением веб-страницы, полученной по http. (На момент разработки в API не было возможности получения этих данных).

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

Примеры использования

Поиск хозяйствующего субъекта по ИНН

ОбработкаОбменаВЕТИС = Обработки.ОбменДаннымиВЕТИС.Создать();
РезультатПоиска = ОбработкаОбменаВЕТИС.ПолучитьХС_ПоИНН(ИНН);
			
Если РезультатПоиска = Неопределено Тогда
	Предупреждение("ХС по ИНН " + ИНН + " не найден в ВЕТИС!");
Иначе
	НаименованиеХС = РезультатПоиска.name;
	UUID = РезультатПоиска.uuid;
	GUID = РезультатПоиска.guid;
КонецЕсли;

Загрузка справочника продукции из ВЕТИС по хозяйствующему субъекту

Тут следует отметить, что объекты ВЕТИС идентифицируются с помощью GUID, и можно использовать эту особенность при интеграции с 1С, в частности присваивать внутренние идентификаторы элементам справочников 1С в значения, соответствующие GUID объектов ВЕТИС.

// Загрузка элементов в спр-к Номенклатура из Меркурий по хоз. субъекту
// Параметры:
//
//	ХС_GUID -  тип Строка - УИД хоз. субъекта в Меркурий
//
Процедура ЗагрузитьНоменклатуруПоХС(ХС_GUID) Экспорт
	
	ОбработкаОбменаВЕТИС = Обработки.ОбменДаннымиВЕТИС.Создать();
	НайденнаяНоменклатура = ОбработкаОбменаВЕТИС.ПолучитьСписокНоменклатуры_ПоХС(ХС_GUID);
	Если ЗначениеЗаполнено(НайденнаяНоменклатура) Тогда
		Для каждого Элемент Из НайденнаяНоменклатура Цикл
			
			УИД_Строкой = Элемент.guid;
			НоменклатураМеркурий = ИнтеграцияВЕТИСЗагрузкаОбъектов.ПолучитьСсылкуСправочникаПоУИД(УИД_Строкой, "НоменклатураМеркурий");
			Если ИнтеграцияВЕТИСЗагрузкаОбъектов.СсылкаСуществует(НоменклатураМеркурий, "НоменклатураМеркурий") Тогда
				НоменклатураМеркурий_Объект = НоменклатураМеркурий.ПолучитьОбъект();
			Иначе
				НоменклатураМеркурий_Объект = Справочники.НоменклатураМеркурий.СоздатьЭлемент();
				НоменклатураМеркурий_Объект.УстановитьСсылкуНового(НоменклатураМеркурий);
			КонецЕсли;
			
			ЗаполнитьНоменклатуруПоДаннымXDTO(НоменклатураМеркурий_Объект, Элемент); 
			
			НоменклатураМеркурий_Объект.Записать();
			
		КонецЦикла;
	КонецЕсли;
	
КонецПроцедуры

Создание ВСД на перевозку со сменой владельца

Данный пример "вырван из контекста" конфигурации, в рамках которой используется модуль обмена. Он демонстрирует более сложные случаи запросов в Меркурий. Некоторые операции в Меркурий требуют подготовки достаточно сложного XML-документа запроса. Для упрощения его подготовки в модуле обмена есть функции, которые принимают в качестве параметров элементы описания тех или иных объектов запроса в Меркурий (ПартияПоЗаписиСкладскогоЖурнала, ТочкаМаршрутаСледования, Отправитель, Получатель, ИнформацияОТранспорте и т.д.), а в качестве результата выдают строку XML-описания (consignment, routePoint, consignor, consignee и т.д.).

// Отправлка в Меркурий заявку на подготовку ВСД на перевозку со сменой владельца. Возвращает ИД заявки.
// Параметры:
//	ОтправительХС -  СправочникСсылка.ХозСубъекты - Хоз. субъект - отправитель
//	ОтправительПлощадка -  СправочникСсылка.ПлощадкиВЕТИС - Площадка отправитель
//	ПолучательХС -  СправочникСсылка.ХозСубъекты - Хоз. субъект - получатель
//	ПолучательПлощадка -  СправочникСсылка.ПлощадкиВЕТИС - Площадка получатель
//	ТаблицаОтгружаемыхПартий -  Таблица значений - Таблица для заполнения получается функцией ПустаяТаблицаОтгружаемыхПартий()
//	Транспорт -  СправочникСсылка.ТранспортВЕТИС -
//	НомерТТН -  Строка - 
//	ДатаТТН -  Дата - 
//	ТипТТН -  Число - тип документа, см. функцию ТТН в модуле обмена
//	ДатаДоставки -  Дата - 
//	ПеревозчикХС -  СправочникСсылка.ХозСубъекты - Хоз. субъект - перевозчик
//	ТаблицаТочекМаршрутаСледования -  тип Таблица значений - Таблица для заполнения точек маршрута следования, получается функцией ПустаяТаблицаТочекМаршрута()
//	ТаблицаСвязанныхДокументов -  тип Таблица значений - Таблица для заполнения связанных документов, получается функцией ПустаяТаблицаСвязанныхДокументов()
//
Функция ОтправитьЗаявкуПодготовитьВСДНаПеревозкуСоСменойВладельца(
	ОтправительХС, 
	ОтправительПлощадка, 
	ПолучательХС, 
	ПолучательПлощадка, 
	ТаблицаОтгружаемыхПартий, 
	Транспорт, 
	НомерТТН, 
	ДатаТТН, 
	ТипТТН, 
	ДатаДоставки = Неопределено, 
	ПеревозчикХС = Неопределено, 
	ТаблицаТочекМаршрутаСледования = Неопределено, 
	ТаблицаСвязанныхДокументов = Неопределено
	) Экспорт
	
	ОбработкаОбменаВЕТИС = Обработки.ОбменДаннымиВЕТИС.Создать();
	
	МассивПартий = Новый Массив;
	МассивДопСведенийВСД = Новый Массив;
	
	НомерСтроки = 1;
	Для каждого ТаблицаОтгружаемыхПартийСтрока ИЗ ТаблицаОтгружаемыхПартий Цикл
		ИдПартии = "id" + Формат(НомерСтроки, "ЧГ=0");
		ТаблицаОтгружаемыхПартийСтрока.ИдПартии = ИдПартии;
		
		Партия = ОбработкаОбменаВЕТИС.ПартияПоЗаписиСкладскогоЖурнала(
			ИдПартии,
			ТаблицаОтгружаемыхПартийСтрока.ЗСЖ.GUID,
			ТаблицаОтгружаемыхПартийСтрока.Количество,
			ТаблицаОтгружаемыхПартийСтрока.ЗСЖ.ЕдиницаИзмеренияВЕТИС.GUID);
			
		МассивПартий.Добавить(Партия);
		
		ДопСведенияВСД = ОбработкаОбменаВЕТИС.ДопСведенияВСД(
			ИдПартии,
			ТаблицаОтгружаемыхПартийСтрока.Цель.GUID,
			?(ТаблицаОтгружаемыхПартийСтрока.КонтрольГосВетВрачем = Неопределено, Истина, ТаблицаОтгружаемыхПартийСтрока.КонтрольГосВетВрачем),
			?(ТаблицаОтгружаемыхПартийСтрока.РезультатПроведенияВСЭ = Неопределено, "VSERAW", ТаблицаОтгружаемыхПартийСтрока.РезультатПроведенияВСЭ),
			?(ТаблицаОтгружаемыхПартийСтрока.БлагополучиеМестности = Неопределено, "Местность благополучна по заразным болезням животных", ТаблицаОтгружаемыхПартийСтрока.БлагополучиеМестности));
			
		МассивДопСведенийВСД.Добавить(ДопСведенияВСД);		
		
		НомерСтроки = НомерСтроки + 1;
	КонецЦикла;
	
	Если ТаблицаТочекМаршрутаСледования = Неопределено Тогда
		МассивТочекМаршрутаСледования = "";
	Иначе
		МассивТочекМаршрутаСледования = Новый Массив;
		
		НомерТочкиМаршрута = 1;
		Для каждого ТаблицаТочекМаршрутаСледованияСтрока Из ТаблицаТочекМаршрутаСледования Цикл
			ТочкаМаршрутаСледования = ОбработкаОбменаВЕТИС.ТочкаМаршрутаСледования(
				НомерТочкиМаршрута,
				ТаблицаТочекМаршрутаСледованияСтрока.ПлощадкаВЕТИС.GUID,
				ТаблицаТочекМаршрутаСледованияСтрока.Перегрузка,
				?(ЗначениеЗаполнено(ТаблицаТочекМаршрутаСледованияСтрока.ТипТранспорта), ТаблицаТочекМаршрутаСледованияСтрока.ТипТранспорта, 1),
				?(ЗначениеЗаполнено(ТаблицаТочекМаршрутаСледованияСтрока.НомерТранспорта), ТаблицаТочекМаршрутаСледованияСтрока.НомерТранспорта, Строка(Символы.НПП)));
				
			НомерТочкиМаршрута = НомерТочкиМаршрута + 1;
			
			МассивТочекМаршрутаСледования.Добавить(ТочкаМаршрутаСледования);
		КонецЦикла;
	КонецЕсли;
	
	Если ТаблицаСвязанныхДокументов = Неопределено Тогда
		МассивСвязанныхДокументов = "";
	Иначе
		МассивСвязанныхДокументов = Новый Массив;
		
		Для каждого ТаблицаСвязанныхДокументовСтрока Из ТаблицаСвязанныхДокументов Цикл
			СвязанныйДокумент = ОбработкаОбменаВЕТИС.СвязанныйДокумент(
				ТаблицаСвязанныхДокументовСтрока.Номер,
				ТаблицаСвязанныхДокументовСтрока.Дата,
				Перечисления.ТипыДокументовВЕТИС.ПолучитьНомер(ТаблицаСвязанныхДокументовСтрока.Тип),
				ТаблицаСвязанныхДокументовСтрока.ТипСвязи);
			
			МассивСвязанныхДокументов.Добавить(СвязанныйДокумент);
		КонецЦикла;
	КонецЕсли;
	
	ИдЗаявки = ОбработкаОбменаВЕТИС.ПодготовитьТранспортнуюПартию(
		ОтправительХС.GUID,
		ДатаДоставки,
		ОбработкаОбменаВЕТИС.Отправитель(
			ОтправительХС.GUID,
			ОтправительПлощадка.GUID),
		ОбработкаОбменаВЕТИС.Получатель(
			ПолучательХС.GUID,
			ПолучательПлощадка.GUID),
		МассивПартий,
		,
		ИнформацияОТранспорте(Транспорт, ОбработкаОбменаВЕТИС),
		"FROZEN",
		ОбработкаОбменаВЕТИС.ТТН(
			НомерТТН,
			ДатаТТН,
			1),
		МассивДопСведенийВСД,
		МассивТочекМаршрутаСледования,
		МассивСвязанныхДокументов);
		
	Возврат ИдЗаявки;
	
	
КонецФункции

В заключение отмечу, что работа с Меркурием на "низком уровне" (отправка XML запросов, обработка ответов) - это сомнительное удовольствие, которое доставит радость разве что любителям приключений. Найти ошибку в сложном запросе бывает не так просто (особенно если у вас еще нет опыта работы с Меркурием). Но если проверенные готовые решения вам не подходят, то данная обработка в любом случае поможет сэкономить много времени.

Проверено на платформе 8.3.13.1644.