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

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

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

===== XML over HTTP =====
==== Запросы и ответы ====
XML over HTTP подразумевает 2 типа запроса к серверу:
  * GET. В таком случае, все параметры запроса передаются в адресной строке, например, таким методом является [[ru:b2bv2:methods:getactivationform#пример_для_xmloverhttp|GetActivationForm]]
  * POST. В таком случае все параметры запроса передаются с помощью XML, в качестве POST-данных. Пример такого метода: [[ru:b2bv2:methods:startsubscription#пример_для_xmloverhttp|StartSubscription]].

В обоих случаях ответом сервиса является XML, содержащий десериализованный объект ответа.
Для каждого метода в его описании приводятся примеры запросов и ответов сервера, что можно использовать при реализации своего программного обеспечения для формирования нужных запросов.
Необходимый ContentType: "application/xml"
==== Авторизация ====
Для работы некоторых методов веб-сервисов необходима авторизация. В случае XML over HTTP для этого используется [[http://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA|Basic Authentication Scheme]], стандартизированная W3C.
==== Примеры использования (PHP) ====
Рассмотрим пример использования веб-сервиса на языке PHP. Все общение с веб-сервисом можно описать одной функцией:
<code php>
<?php
function CallMethod($serviceUrl, $login, $pass, $methodName, $postXml)
	{
		$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);
		}
		$xml = simplexml_load_string($xmlString); // Выполняем запрос
		$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // Проверяем результат выполнения запроса
		if ($xml->IsError==="true")
		{
			throw new Exception($xml->ErrorDetails,intval($xml->ErrorCode));
		}
		if ($xml->IsError==="false")
		{
			return json_decode(json_encode($xml)); //хитро преобразуем в объект
		}
		throw new Exception("Необработанная ошибка при выполнении веб-запроса. Код ошибки:".$resultCode, $resultCode);
	}
?>
</code>

Приведем примеры вызова этой функции. Для метода [[ru:b2bv2:methods:getactivationform|GetActivationForm]] (GET):

<code php>
<?php
CallMethod("https://sandbox.mont.ru/Version2/Service/B2BService.svc/", "login", "pass", 
"GetActivationForm?partNum=cloud-6p-365&montSubscriberId=55173afd-3227-4b09-8c2a-8ef38c490708&langCode=RU");
?>
</code>

Для метода [[ru:b2bv2:methods:startsubscription|StartSubscription]] (POST):
<code php>
<?php 
CallMethod("https://sandbox.mont.ru/Version2/Service/B2BService.svc/", "login", "pass", 
	"<?xml version=\"1.0\" encoding=\"utf-8\" ?><StartSubscription><montSubscriptionId>SUB-12345</montSubscriptionId><byEndUser>true</byEndUser></StartSubscription>");
?>
</code>

===== SOAP =====
[[http://www.w3.org/TR/soap/|SOAP]] - стандартизированный протокол обмена структурированными сообщениями. В случае использования этого протокола подключения все запросы должны иметь тип "POST", и отправляться на один адрес(для каждого сервиса свой, например, https://sandbox.mont.ru/Version2/Service/B2BServiceV2.svc)

Отправляемое в POST-данных сообщение имеет общую структуру. Рассмотрим её на примере метода [[ru:b2bv2:methods:startsubscription|StartSubscription]]:
<code xml>
<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>
</code>

Структура блока 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.

==== Список "примитивных" типов ====
^Название^Пример значения в тегах XML^Описание содержания^
|string|"lorem ipsum"|Простая строка, в кодировке UTF-8|
|int|"42"|Целое число|
|decimal|"42.15"|Дробное число, в качестве разделителя используется символ "." (точка). В сервисе обычно применяется для финансовых величин, потому не рекомендуется хранить его в переменных с типом с “плавающей запятой”.|
|bool|"true"|Логическая переменная. Допустимые значения при общении с сервисом - “true” или “false”|
|DateTime|"2015-05-20T12:49:33.6052875"|Дата-время в формате "yyyy-MM-ddTHH:mm:ss.fffffff" в соответствии со стандартом ISO 8601|
|array of T|см. ниже|Массив элементов типа T(где T - любой тип)|
|T?|см. ниже|Поле имеет значение либо типа T(где T - любой тип), либо NULL|
|[[https://tools.ietf.org/html/rfc4122|UUID]]|86F40D0B-AB83-4E42-87B6-3A5F0220AC74|Статистически уникальный 128-битный идентификатор. Существует несколько реализаций стандарта UUID, например реализация от Microsoft - [[https://ru.wikipedia.org/wiki/GUID|GUID]]|

Ниже приведены некоторые комментарии по описанным выше типам данных и их методах описания в API.
==== Значение NULL ====
Значение NULL и в XML over HTTP, и в SOAP кодируется следующим образом(на примере поля ParentId):
  <ParentId i:nil="true" />
Соответственно, если значение этого поля будет отлично от NULL, то это должно описываться таким образом:
  <ParentId>25</ParentId>
==== Nullable-типы ====

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

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

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

==== Массивы ====

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

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

<code 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>
...
</code>

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

<code 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>
...
</code>