Техническая информация

В данном разделе описана техническая сторона интеграции c сервисами MONT Webstore.

Cистема представляет из себя несколько веб-сервисов, доступ к которомым осуществляется с помощью прикладного протокола HTTPS. Для каждого сервиса существует 2 протокола, с помощью которых можно взаимодействовать с сервисом - XML over HTTP и SOAP.

XML over HTTP подразумевает 2 типа запроса к серверу:

• GET. В таком случае, все параметры запроса передаются в адресной строке, например, таким методом является GetActivationForm
• POST. В таком случае все параметры запроса передаются с помощью XML, в качестве POST-данных. Пример такого метода: StartSubscription.

В обоих случаях ответом сервиса является XML, содержащий десериализованный объект ответа. Для каждого метода в его описании приводятся примеры запросов и ответов сервера, что можно использовать при реализации своего программного обеспечения для формирования нужных запросов. Необходимый ContentType: «application/xml»

Для работы некоторых методов веб-сервисов необходима авторизация. В случае XML over HTTP для этого используется Basic Authentication Scheme, стандартизированная W3C.

Рассмотрим пример использования веб-сервиса на языке PHP. Все общение с веб-сервисом можно описать одной функцией:

<?php
function CallMethod($serviceUrl, $login, $password, $methodName, $postXml=false)
	{
		$ch = curl_init($serviceUrl.$methodName); //инициализируем curl для запроса на нужный адрес
		curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
		curl_setopt($ch, CURLOPT_USERPWD, $login . ':' . $password); // указываем авторизационный заголовок
		curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); // Этот параметр нужен для успешного выполнения запросов на тестовой площадке
		curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); // Этот параметр нужен для успешного выполнения запросов на тестовой площадке
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
		if ($postXml) //Если метод GET - то этот параметр просто не нужно передавать
		{
			curl_setopt($ch, CURLOPT_POST, 1);
			curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-Type:application/xml; charset=utf-8",
				"Content-Length:" . strlen($postXml)));
			curl_setopt($ch, CURLOPT_POSTFIELDS, $postXml);
		}
		$xmlString =curl_exec($ch);
		$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // Проверяем результат выполнения запроса
 
		if ($resultCode == 200)
                {
                    $xml = new SimpleXMLElement($xmlString);
                }
		else
		{	
		     throw new Exception("Необработанная ошибка при выполнении веб-запроса. Код ошибки:".$resultCode, $resultCode);
		}
		return $xml;	
	}
?>

Приведем примеры вызова этой функции в WebStore:

Для метода GetMyDetails (GET):

<?php
$result = CallMethod("https://sandbox.mont.ru/Version2/Service/B2BServiceV2Xml.svc/", "login", "password", "GetMyDetails");
	Echo "объект: ";
        var_dump($result);
?>

Для метода AddReserve (POST):

<?php 
$result = CallMethod("https://sandbox.mont.ru/Version2/Service/B2BServiceV2Xml.svc/", "login", "password", "AddReserve", "<?xml version=\"1.0\" encoding=\"utf-8\"?><OrderReserveContract><OrderPrefix>Pipe0805</OrderPrefix><Phone>89267777777</Phone><ReseveLines><OrderReserveLineContract><EndUserInfo /><PartNum>ABC-11111</PartNum><Quantity>1</Quantity><EndUserPrice>1500</EndUserPrice><CurrencyCode>RUR</CurrencyCode></OrderReserveLineContract></ReseveLines></OrderReserveContract>");
    Echo "объект: ";
    var_dump($result);
?>

Приведем примеры вызова этой функции в Content:

Для метода GetDefaultMenu (GET):

<?php
$result = CallMethod("https://sandbox.mont.ru/contentApi/version3/service/ContentServiceV3Xml.svc/", "login", "password", "GetDefaultMenu?langcode=RU");
    Echo "объект: ";
    var_dump($result);
?>

SOAP - стандартизированный протокол обмена структурированными сообщениями. В случае использования этого протокола подключения все запросы должны иметь тип «POST», и отправляться на один адрес(для каждого сервиса свой, например, https://sandbox.mont.ru/Version2/Service/B2BServiceV2.svc)

Отправляемое в POST-данных сообщение имеет общую структуру. Рассмотрим её на примере метода StartSubscription:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://tempuri.org/IB2BServiceV2/StartSubscription</a:Action>
    <a:ReplyTo>
      <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
    </a:ReplyTo>
    <a:To s:mustUnderstand="1">https://sandbox.mont.ru/Version2/Service/B2BServiceV2.svc</a:To>
    <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <o:UsernameToken>
        <o:Username>username</o:Username>
        <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</o:Password>
      </o:UsernameToken>
    </o:Security>
  </s:Header>
  <s:Body>
    <StartSubscription xmlns="http://tempuri.org/">
      <montSubscriptionId>123</montSubscriptionId>
      <byEndUser>true</byEndUser>
    </StartSubscription>
  </s:Body>
</s:Envelope>

Структура блока Header для всех методов одинакова:

• Элемент Action содержит название вызываемого метода
• Элемент To содержит адрес сервиса, к которому совершается вызов.
• Элемент Security содержит авторизационные данные - логин и пароль.

Структура блока Body для всех методов различна, и зависит от его входных параметров. Для каждого метода сервиса приводятся примеры SOAP-запросов и ответов.

В большинстве современных языков программирования есть средства для автоматизированной интеграции с SOAP-сервисами, на основе wsdl-файла. Для каждого сервиса wsdl-файл доступен по адресу *serviceAddress*?wsdl, например https://sandbox.mont.ru/Version2/Service/B2BServiceV2.svc?wsdl

Необходимый ContentType: «application/soap+xml»

На данной странице приводится описание всех типов, которые используются при взаимодействии с сервисами MONT.

Ниже приведены некоторые комментарии по описанным выше типам данных и их методах описания в API.

Значение NULL и в XML over HTTP, и в SOAP кодируется следующим образом(на примере поля ParentId):

<ParentId i:nil="true" />

Соответственно, если значение этого поля будет отлично от NULL, то это должно описываться таким образом:

<ParentId>25</ParentId>

T? - это специальный тип для описания поля, которое может иметь как значение типа T, так и значение NULL. Необходимо это учитывать при вызове методов и при обработке их результатов.

Если рассматривать случай с SOAP при использовании WSDL, то возможны несколько вариантов распознавания такого типа используемым языком программирования:

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

Следует обратить внимание на то, каким образом будут заполняться поля типа “Массив” при использовании протокола XML over HTTP. Рассмотрим 2 примера для этого типа данных:

• Массив элементов “простых” типов, описанных выше. В XML этот массив строк будет отображен следующим образом:

...
<SomeField>...</SomeField>
<RelatedPartNums xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <a:string>KL1030RDAFS</a:string>
  <a:string>ABC-11111</a:string>
</RelatedPartNums>
<SomeField2>...</SomeField>
...

• Массив элементов “сложных” типов, где каждый элемент массива является объектом и содержит в себе несколько полей. В XML этот массив строк будет отображен следующим образом:

...
<SomeField>...</SomeField>
<MenuDescriptionsField>
  <MenuDescriptionContract>
    <Id>3</Id>
    <MenuName>Legacy tree</MenuName>
  </MenuDescriptionContract>
  <MenuDescriptionContract>
    <Id>1</Id>
    <MenuName>Legacy tree 2</MenuName>
  </MenuDescriptionContract>
</RelatedPartNums>
<SomeField2>...</SomeField>
...

Рекомендации по обращению в службу поддержки