Каталог решений - Реализация обмена с ФГИС «Зерно»

Скоро для многих участников рынка зерна в России станет обязательным внесение данных в ФГИС "Зерно". В связи с чем стоит вопрос о программном взаимодействии с системой через API.

В статье с нуля напишем код, который позволит связаться с ФГИС "Зерно". Для примера получим какой-нибудь справочник и создадим пробную партию зерна. Предметная область, интеграция с рабочей конфигурацией и прочие связанные вещи рассматриваться не будут. Также отмечу, что все ниженаписанное, это результат моего личного опыта, поэтому где-то возможны неоптимальные решения. Примеры кода я постарался сократить для экономии места.

Итак, у нас есть официальный сайт https://specagro.ru/fgis, на котором можно скачать файл с документацией по API, попасть в личный кабинет (в т. ч. тестовый), ну и вообще посмотреть на картинки. Внутри файла лежат непосредственно документация, XSD-схемы, которые нам очень понадобятся, а также могут лежать (а могут и не лежать:) примеры запросов. Перед началом рекомендую ознакомиться с документацией, многие подробности можно найти в ней. На момент написания статьи актуальная версия API — 1.0.2.

Для обмена с "Зерном" необходимы сертификат безопасности, с помощью которого мы будем подписывать наши сообщения, и установленный криптопровайдер. Предварительно сертификат (открытый ключ) необходимо загрузить в личный кабинет (через меню "Моя организация" -> "Информационная безопасность").

Также нужна будет компонента XMLDSig или ExtraCryptoAPI (входят в состав БСП).

Для формирования и обработки запроса на XML будем использовать фабрику XDTO.

Приступим. Для начала попробуем получить из системы справочник, например, классификатор "ОКПД 2". Для этого нам нужно:

1. Создать фабрику XDTO
2. Сформировать запрос
3. Подписать сообщение с запросом ЭЦП
4. Отправить запрос и получить ответ

1. Создание фабрики XDTO

Для создания фабрики нам будут нужны XSD-схемы, которые можно взять из архива с документацией:

Как видно, в основном схемы представлены попарно: с префиксом "api" и без него. В первом случае в файле описаны схемы запросов для работы с объектами, во втором случае — структуры самих объектов.

Для начального примера будут нужны только два файла: "fgis-zerno-api-dictionaries-1.0.2.xsd", "fgis-zerno-api-types-1.0.2.xsd". Первый необходим для работы справочников, второй описывает служебные объекты и требуется для работы первого. Описания самих справочников ("fgis-zerno-dictionary-1.0.2.xsd") нам в данном примере не нужны.

Загрузим файлы в макет и создадим нашу фабрику:

	МассивПутей = Новый Массив;
	КаталогВременныхФайлов = КаталогВременныхФайлов();
		
	ИмяФайла = КаталогВременныхФайлов + "fgis-zerno-api-types-1.0.2.xsd";
	Макет = ПолучитьМакет("fgis_zerno_api_types"); // Макет с файлом "fgis-zerno-api-types-1.0.2.xsd"
	Макет.Записать(ИмяФайла);
	МассивПутей.Добавить(ИмяФайла);
		
	ИмяФайла = КаталогВременныхФайлов + "fgis-zerno-api-dictionaries-1.0.2.xsd";
	Макет = ПолучитьМакет("fgis_zerno_api_dictionaries"); // Макет с файлом "fgis-zerno-api-dictionaries-1.0.2.xsd"
	Макет.Записать(ИмяФайла);
	МассивПутей.Добавить(ИмяФайла);
		
	Фабрика = СоздатьФабрикуXDTO(МассивПутей);

2. Формирование запроса

Ниже код формирования запроса XML на получение справочника "ОКПД 2":

	// Создаем объект XDTO, в параметрах указываем пространство имен и имя типа
	// Оба значения можно найти в файле XSD-схемы, либо посмотреть отладкой в объекте Фабрика
	ОбъектRequest = Фабрика.Создать(Фабрика.Тип("urn://x-artefacts-mcx-gov-ru/fgiz-zerno/api/ws/dictionaries/1.0.2",
		"DictionaryRequestType"));

	// Указываем название справочника - "OKPD2". Список справочников можно найти в файле "fgis-zerno-dictionary-1.0.2.xsd"
	ОбъектRequest.Dictionary = "OKPD2";
		
	МойXML = Новый ЗаписьXML;
	МойXML.УстановитьСтроку(Новый ПараметрыЗаписиXML("UTF-8", "1.0", Истина));

	// Записываем наш объект в виде XML. Имя элемента "Request" можно узнать из документации или отладкой
	Фабрика.ЗаписатьXML(МойXML, ОбъектRequest, "Request");
	Request = МойXML.Закрыть();

В переменной Request после выполнения кода будет содержаться следующий текст:

<Request xmlns="urn://x-artefacts-mcx-gov-ru/fgiz-zerno/api/ws/dictionaries/1.0.2" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<Dictionary>OKPD2</Dictionary>
</Request>

Это и есть наш запрос, который мы отправим в систему. Теперь его необходимо "обернуть" и подписать с помощью сертификата.

3. Подписание сообщения

Получившийся запрос поместим в еще один XML, "конверт", соответствующий формату протокола SOAP.