Спецификация клиентских веб-сервисов (стр. 6 )

  <faultcode>s:BusinessUnitCodeIsNotFound</faultcode>

  <faultstring xml:lang="en-US">BusinessUnitCode 1100 Is Not Found</faultstring>

  </s:Fault>Или

<s:Fault> 

  <faultcode xmlns:a="http://schemas. /net/2005/12/windowscommunicationfoundation/dispatcher">a:DeserializationFailed</faultcode>

  <faultstring xml:lang="ru-RU">The formatter threw an exception while trying to deserialize the message: There was an error while trying to deserialize parameter https://api. hermes-dpd. ru/WS/:preadvices. The InnerException message was 'Invalid enum value '?' cannot be deserialized into type 'B2C. API. DTO. CurrencyCode'. Ensure that the necessary enum values are present and are marked with EnumMemberAttribute attribute if the type has DataContractAttribute attribute.'.  Please see InnerException for more details.</faultstring>

</s:Fault>

При возникновении необработанной ошибки сервер вернет внутреннюю ошибку, например

<s:Fault>

  <faultcode xmlns:a="http://schemas. /net/2005/12/windowscommunicationfoundation/dispatcher">a:InternalServiceFault</faultcode>

  <faultstring xml:lang="ru-RU">The server was unable to process the request due to an internal error.  For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the &lt;serviceDebug> configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Framework SDK documentation and inspect the server trace logs.</faultstring>

</s:Fault>

Обработка ошибок REST-сервисом

В зависимости от того, в каком формате передаются данные (xml/json), ошибки будут возвращены в том же формате. В зависимости от типа возвращаемого значения вызываемого метода ошибка может содержаться внутри элемента массива возвращаемого типа, например, при вызове CreatePreadvice сервер вернул результат без ошибки, но в объекте есть информация об ошибке XML

<CreatePreadviceResponse

xmlns="https://api. hermes-dpd. ru/WS/rest"><CreatePreadviceResult xmlns:a="http://schemas. datacontract. org/2004/07/B2C. API. DTO" xmlns:i="http://www. w3.org/2001/XMLSchema-instance"><a:PreadviceResult><a:ErrorCode>BusinessUnitCodeIsNotFound</a:ErrorCode><a:ErrorMessage>BusinessUnitCode 10000 Is Not Found</a:ErrorMessage><a:OperationResult>-1</a:OperationResult><a:ClientParcelNumber>1113</a:ClientParcelNumber><a:ParcelBarcode/></a:PreadviceResult></CreatePreadviceResult></CreatePreadviceResponse>

JSON

{"CreatePreadviceResult":[{"ErrorCode":8,"ErrorMessage":"BusinessUnitCode 10000 Is Not Found","OperationResult":-1,"ClientParcelNumber":"1113","ParcelBarcode":""}]}

При возникновении исключительной ситуации сервер вернет следующие ошибки XML

<Error><Status>500</Status><Name>DeserializationFailed</Name><Code>-1</Code><Message>The formatter threw an exception while trying to deserialize the message: Error in deserializing body of request message for operation 'CreatePreadvice'. Start element 'readvices' does not match end element 'preadvices'. Line 1, position 2128.</Message></Error>

JSON

{"Code":28,"Message":"Deserialization object error, check your request ","Name":"Deserialization","Status":500}

При возникновении необработанной ошибки сервер вернет следующие ошибки XML

<Error><Status>500</Status><Name>CommonFail</Name><Code>-1</Code><Message>Internal Server Error</Message></Error>

JSON

{"Code":-1,"Message":"Internal Server Error","Name":"CommonFail","Status":500}

Контакты

Все вопросы: [email protected]

Технические вопросы: it..

Примеры подключения и вызова

Все актуальные примеры с документацией расположены здесь http://test-api. hermes-dpd. ru/

Запросы для SOAP-сервиса

Консольное приложение на C#

Добавить Service Reference

Исходный код Пример вызова получения ПВЗ по коду бизнес-юнита

class Program

{

static void Main(string[] args)

{

var proxy = new HermesTestAPI. WebServiceClient();

proxy. ClientCredentials. UserName. UserName = "testlogin";

proxy. ClientCredentials. UserName. Password = "testpassword";

var result = proxy. GetParcelShops("1000");

foreach (var parcelShop in result)

{

Console. WriteLine("name {0}, code: {1}", parcelShop. ParcelShopName, parcelShop. ParcelShopCode);

}

Console. ReadLine();

}

}

Пример получения массива байтов PDF-файла с наклейками

internal class Program

{

private static void Main(string[] args)

{

GetBytesAndSaveFile();

}

private static void GetBytesAndSaveFile()

{

var client = new SoapServiceClient();

if (client. ClientCredentials!= null)

{

client. ClientCredentials. UserName. UserName = "testlogin";

client. ClientCredentials. UserName. Password = "testpassword";

}

var arr = new[]

{

"10009900001135",

"009900001137", //ошибочная посылка

"10009900001138"

};

var bytes = client. GetPdfStickerBytes(arr, SheetSize. A4Default);

File. WriteAllBytes("c:\\stikers_" + DateTime. Now. ToString("yyyy-MM-dd-HH-mm-ss") + ".pdf", bytes);

client. Close();

}

}

Выполнение запросов через SoapUI

Добавить SOAP проект

Чтобы выполнить запрос, нужно сделать следующее указать входные параметра для метода запроса, учетную запись в параметрах запроса (Username, Password) и WSS-Password Type = PasswordText

«Чистый» XML-запрос

К xml-запросу нужно добавить заголовок с авторизацией, и актуализировать дату создания, текст запроса выглядит так Обратите внимание на namespace https://api. hermes-dpd. ru/WS/

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas. xmlsoap. org/soap/envelope/" xmlns:ns1="https://api. hermes-dpd. ru/WS/">

<SOAP-ENV:Header>

<wsse:Security SOAP-ENV:mustUnderstand='1'

xmlns:wsse='http://docs. oasis-open. org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'>

<wsse:UsernameToken wsu:Id='UsernameToken-1'

xmlns:wsu='http://docs. oasis-open. org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'>

<wsse:Username>testlogin</wsse:Username>

<wsse:Password

Type='http://docs. oasis-open. org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'>testpassword</wsse:Password>

<wsu:Created>2014-10-07T15:27:00.000Z</wsu:Created>

</wsse:UsernameToken>

</wsse:Security>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

<ns1:GetParcelShops>

<ns1:businessUnitCode>1000</ns1:businessUnitCode>

</ns1:GetParcelShops>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Запрос можно выполнить на любых онлайн-сервисах soap-клиентов, например, на http:// (ссылка на запрос)

Запросы для REST-сервиса

Пример всех запросов XML/JSON для основных типовых методов сервиса вы найдете в этом разделе. Основная рекомендация – используйте JSON, с POST запросом в XML слишком много ограничений и условий.

Основные замечания при составлении и отправки JSON-запросов сервису

Запрос должен содержать все свойства объекта в алфавитном порядке (см пример запроса), иначе при десериализации часть значений будет утеряна, за информацией обращайтесь к описанию сервиса по WSDL.
Если вы используете передачу данных в JSON, даты должны передаваться следующим образом

В некоторых случаях при вызове методов формат даты может быть в формате /Date(1449672181000+0300)/. В текущей версии API используется майкрософтовский сериализатор, он так выполняет сериализацию дат https://msdn. /ru-ru/library/bb412170(v=vs.110).aspx 

Это число миллисекунд в часовом поясе GMT по-обычному (не летнему) времени, прошедшее с 1 января 1970 г. Это число может быть отрицательным для представления более раннего времени. Часть строки "+0500" является необязательной и показывает, что это время в формате Local, т. е. при десериализации оно должно быть преобразовано в местный часовой пояс. Если эта часть строки отсутствует, время десериализуется как UTC. Собственно, число (в данном случае "0500") и его знак (+ или -) игнорируются."

Убедитесь, что в заголовках HTTP запроса отсутствует элемент cache-control: no-cache

На сайте есть функция перевода даты для указанного формата (см. метод CreatePreadvice)

http://test-api. hermesrussia. ru/rest_main. html

function getMSJSONDate(iso8601Date) {

  var date = new Date(iso8601Date);

  var utcPart = '';

  //utc

  if (iso8601Date. length > 23) {

  utcPart = bstring(23);

  }

  var offset = date. getTimezoneOffset() * 60 * 1000;

  var withOffset = date. getTime();

  var withoutOffset = withOffset - offset;

  return "/Date(" + withOffset + utcPart + ")/";

}

В следующей версии API будет использоваться сериализатор Newtonsoft. Json и формат дат ISO 8601

Основные замечания при составлении и отправки XML-запросов сервису

Все имена вызываемых методов должны быть указаны с учетом регистра, как они описаны в WSDL. Запрос должен содержать все свойства объекта в алфавитном порядке (см пример запроса), иначе при десериализации часть значений будет утеряна, за информацией обращайтесь к описанию сервиса по WSDL При формировании любого запроса нужно указывать неймспейс xmlns="https://api. hermes-dpd. ru/WS/rest" в качестве атрибута элемента с именем = наименованию вызываемого метода Дополнительный неймспейс xmlns:i="http://www. w3.org/2001/XMLSchema-instance" необходим для отметки пустых значений, особенно для дат, в элементе нужно добавить атрибут i:nil="true". Дополнительный неймспейс xmlns:a=" http://schemas. /2003/10/Serialization/Arrays" в качестве атрибута нужен для передачи массива значений в качестве параметра, например, SendPreadvicesToDelivery - для отправки предзаказов на доставку

<?xml version="1.0" encoding="UTF-8"?>