Краткое описание - Hermes
реклама
API
Спецификация веб-сервисов
Hermes-DPD
2
Содержание
Содержание ................................................................................................................................................................ 2
Версия документа ...................................................................................................................................................... 3
Краткое описание....................................................................................................................................................... 3
Описание терминов ................................................................................................................................................... 4
Расположение ............................................................................................................................................................ 5
Модуль Parcel Content API ......................................................................................................................................... 6
Изменение содержимого посылки ...................................................................................................................... 6
Метод SetParcelContent ..................................................................................................................................... 6
Объектная модель ................................................................................................................................................. 8
ParcelContentRequest ......................................................................................................................................... 8
Item ...................................................................................................................................................................... 8
ParcelContentResult ............................................................................................................................................ 9
Обработка ошибок ................................................................................................................................................... 10
Коды ошибок ........................................................................................................................................................ 10
Обработка ошибок SOAP-сервисом.................................................................................................................... 10
Обработка ошибок REST-сервисом..................................................................................................................... 11
Контакты ................................................................................................................................................................... 13
Примеры подключения и вызова ........................................................................................................................... 14
Запросы для SOAP-сервиса.................................................................................................................................. 14
Консольное приложение на C# ....................................................................................................................... 14
Выполнение запросов через SoapUI............................................................................................................... 16
«Чистый» XML-запрос ...................................................................................................................................... 18
Запросы для REST-сервиса .................................................................................................................................. 20
Запросы (XML/JSON) на JavaScript (JQuery) .................................................................................................... 21
3
Версия документа
Версия
1.0
Дата
30.03.2015
Автор
Корзинин А.
Комментарий
Документ создан
Краткое описание
В данном документе описаны спецификации веб-сервисов компании Hermes-DPD. Веб-сервисы компании
Hermes-DPD позволяют клиентам осуществить интеграцию для выполнения основных операций.
Для клиентов доступны два типа взаимодействия с веб-сервисами: REST и классический SOAP.
4
Описание терминов
ПВЗ – Пункт выдачи заказов
Штрих-код посылки – уникальный номер посылки, используемый для графического отображения на
наклейке на посылке и для всех взаимодействий по посылке между клиентом, получателем и HermesDPD
Бизнес-юнит – структурное подразделение клиента. Если у клиента есть несколько каталогов, сайтов
или брендов, для которых на всех стадиях жизненного цикла доставки посылки должно быть явно
известно, к которому из них она относится, то такие структуры клиента необходимо выделить в
самостоятельные бизнес-юниты
«Экспресс-возврат» - услуга возврата уже выкупленных сколько угодно давно получателем товаров в
любом состоянии. Товары могут быть из разных посылок. В одном возврате могут быть не все товары
из первоначальной посылки. Первоначальная посылка могла быть доставлена другой службой
доставки.
Предзаказ - Информация о еще не переданных на доставку посылках.
5
Расположение
Веб-сервисы Hermes-DPD расположены по адресу:
Тестовая версия:
o Описание всех сервисов – https://test-api.hermes-dpd.ru
o модуль ParcelContent API
o SOAP https://test-api.hermes-dpd.ru/pc/soapservice.svc?wsdl
https://test-api.hermes-dpd.ru/pc/soapservice.svc?singlewsdl
o REST https://test-api.hermes-dpd.ru/pc/restservice.svc?wsdl
https://test-api.hermes-dpd.ru/pc/restservice.svc?singlewsdl
o Тестовая учетная запись
пользователь – testlogin, пароль – testpassword,
Перед использованием сервиса необходимо создать посылку и отправить ее на
доставку через основной модуль API. Документацию можно получить у отдела
продаж
Производственная версия:
o Описание всех сервисов – https://api.hermes-dpd.ru
o Основной модуль API
o SOAP https://api.hermes-dpd.ru/pc/soapservice.svc?wsdl
https://api.hermes-dpd.ru/pc/soapservice.svc?singlewsdl
o REST https://api.hermes-dpd.ru/pc/restservice.svc?wsdl
https://api.hermes-dpd.ru/pc/restservice.svc?singlewsdl
В качестве транспортного протокола используется https протокол. Авторизация пользователей
производится по паре логин-пароль. Для получения логина и пароля необходимо обратиться в отдел продаж
компании Hermes-DPD. Авторизация для всех сервисов идентична. Авторизация идентична основному
модулю API.
6
Модуль Parcel Content API
Изменение содержимого посылки
Метод SetParcelContent
Описание
Данный метод предназначен для изменения содержимого посылки. Прежде чем менять содержимое
посылки, необходимо учесть следующие условия
1. Посылка должна быть создана;
2. Каждый вызов метода обновляет содержимое посылки полностью, затирая предыдущие данные
a. Для обновления нужно передать все товары, которые должны быть в посылке
b. Для удаления всех товаров необходимо передать пустую коллекцию товаров
Входные параметры
Параметр
Описание
Тип
parcelContents
Массив записей по ParcelContent[]
каждой посылке со
своими товарами
Выходные параметры
Параметр
ParcelContentResult
Описание
Массив результатов
Обязательный
Да
Тип
ParcelContentResult[]
Пример
См.
описание
используемых
типов данных
Пример
См.
используемых
данных
описание
типов
Получение содержимого посылки
Метод GetParcelContent
Описание
Данный метод предназначен для получения содержимого посылки. Предварительно посылка должна быть
создана.
Входные параметры
Параметр
Описание
Тип
parcelBarcode
Штрих-код
для String(1..40)
наклейки (нужно
сохранять
в
системе клиента,
т.к. все дальнейшее
взаимодействие
идет
по
этому
номеру)
Выходные параметры
Параметр
ParcelContent
Описание
Массив результатов
Тип
ParcelContent[]
Обязательный
Да
Пример
12345678901234
Пример
См.
используемых
данных
описание
типов
7
8
Объектная модель
ParcelContent
Параметр
ParcelBarcode
Items
ExtraParams
Описание
Тип
Штрих-код
для String(1..40)
наклейки
(нужно
сохранять в системе
клиента, т.к. все
дальнейшее
взаимодействие
идет
по
этому
номеру)
Массив товаров
Item[]
Обязательный
Да
Пример
12345678901234
Да
См.
описание
используемых
типов данных
Зарезервированные ExtraParam[]
дополнительные
параметры
для
поддержки
различных версий
текущего API
Нет
Item
Параметр
ItemCode
ItemArticle
ItemName
Тип
String(1..50)
String(0.50)
String(1..50)
Обязательный
Да
Нет
Да
Пример
XC785-09
142234
Мультиварка
ItemDescription
Описание
Номер товара
Артикул товара
Наименование
товара
Описание товара
String(0.50)
Нет
ItemPrice
Цена товара
Double
Да
ItemQuantity
ExtraParams
Количество товара
int
Зарезервированные ExtraParam[]
дополнительные
параметры
для
поддержки
различных версий
текущего API
Купон на скидку
5% вложен в товар
15.45
(разделитель
точка)
3
Да
Нет
9
ParcelContentResult
Параметр
ErrorMessage
ErrorCode
OperationResult
Описание
Текст ошибки
Код ошибки
Результат операции
Тип
String (0..1024)
Обязательный Пример
Нет
См. список ошибок
Integer
Да
ParcelBarcode
Штрих-код
для String(1..40)
наклейки
(нужно
сохранять в системе
клиента, т.к. все
дальнейшее
взаимодействие
идет
по
этому
номеру)
Да
0 - Success
-1..n - ErrorCode
12345678901234
ExtraParam
Параметр
Name
Value
Описание
Наименование параметра
Значение параметра
Тип
String
String
Пример
SomeExtraParam
9ABC000
10
Обработка ошибок
В процессе работы с веб-сервисами возможно возникновение ошибок, по техническим причинам или
причинам, продиктованных бизнес правилами. Коды ошибок, а также причины и действия по их устранению,
описаны в следующем разделе.
Коды ошибок
Код
ошибки
Системное наименование
Описание
Причина
InternalServiceFault
Внутренняя ошибка сервера
-
DeserializationFailed
Внутренняя
ошибка
десериализации на сервере
-1
CommonFail
Ошибочный результат
0
Success
Успешный результат
14
ParcelBarcodeIsNotFound
20
StringLength
21
Required
28
Deserialization
Штрих-код
посылки
[{ParcelBarcode}] не найден
Поле {[StringField]} должно
быть строкой с длиной от
{[MinLength]} до {[MaxLength]}
символов
Поле [{RequiredField}] должно
быть
обязательно
для
заполнения
Ошибка
десериализации
объекта
Возникает при неизвестных
или неверных действиях
процессов SOAP - сервиса
Возникает при попытке
передать запрос неверного
формата, сервер не может
десериализовать объект.
Возникает при неизвестных
ошибках, ошибках общего
характера или внутренних
ошибок сервера
Данный код возвращается в
параметре ErrorCode в
случае
успешного
результата
обработки
запроса. Код не является
ошибкой.
Штрих-код посылки не
найден в системе
Возникает, если строковое
значения
поле
не
соответствует
указанной
длине
Возникает, если не было
заполнено
обязательное
для заполнения поле
Проверьте ваш запрос на
наличие
ошибок,
прочитайте рекомендации
к запросам
Обработка ошибок SOAP-сервисом
1) При возникновении обычной ошибки в результате ответа будет отображаться ее причина, код,
описание и данные, по которым можно сопоставить ее к запросу
<SetParcelContentResponse xmlns="https://api.hermes-dpd.ru/WS/">
<SetParcelContentResult xmlns:a="http://schemas.datacontract.org/2004/07/B2C.ParcelContentAPI.DTO"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ParcelContentResult>
<a:ErrorCode>ParcelBarcodeIsNotFound</a:ErrorCode>
<a:ErrorMessage>Штрих-код посылки 273105873c83071 не найден</a:ErrorMessage>
<a:OperationResult>-1</a:OperationResult>
<a:ParcelBarcode>273105873c83071</a:ParcelBarcode>
</a:ParcelContentResult>
<a:ParcelContentResult>
11
<a:ErrorCode>CommonFail</a:ErrorCode>
<a:ErrorMessage>ItemCode 12 : Operation failed due to validation errors:
Article: Поле должно быть строкой с длиной от 0 до 50 символов
ItemCode 1 : Operation failed due to validation errors:
Description: Поле должно быть строкой с длиной от 0 до 50 символов</a:ErrorMessage>
<a:OperationResult>-1</a:OperationResult>
<a:ParcelBarcode>27310587383071</a:ParcelBarcode>
</a:ParcelContentResult>
</SetParcelContentResult>
</SetParcelContentResponse>
2) При возникновении исключительной ситуации сервер вернет стандартную ошибку с системным
наименованием ошибки и описанием, например
<s:Fault>
<faultcode
xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">a:De
serializationFailed</faultcode>
<faultstring xml:lang="ru-RU">Форматтер сгенерировал исключение при попытке десериализовать
сообщение: Ошибка десериализации параметра https://api.hermes-dpd.ru/WS/:parcelContents.
Сообщение
InnerException
было
"Ошибка
десериализации
объекта
типа
B2C.ParcelContentAPI.DTO.ParcelContent[]. Значение "u" не может интерпретироваться как тип
"double".". Подробнее см. InnerException.</faultstring>
</s:Fault>
3) При возникновении необработанной ошибки сервер вернет внутреннюю ошибку, например
<s:Fault>
<faultcode
xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">a:Int
ernalServiceFault</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 Microsoft .NET Framework
SDK documentation and inspect the server trace logs.</faultstring>
</s:Fault>
Обработка ошибок REST-сервисом
1) В зависимости от того, в каком формате передаются данные (xml/json), ошибки будут возвращены в
том же формате.
2) В зависимости от типа возвращаемого значения вызываемого метода ошибка может содержаться
внутри элемента массива возвращаемого типа, например, при вызове CreatePreadvice сервер вернул
результат без ошибки, но в объекте есть информация об ошибке
a. 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/XMLSchemainstance"><a:PreadviceResult><a:ErrorCode>BusinessUnitCodeIsNotFound</a:ErrorCode><a:ErrorM
12
essage>BusinessUnitCode
10000
Is
Not
Found</a:ErrorMessage><a:OperationResult>1</a:OperationResult><a:ClientParcelNumber>1113</a:ClientParcelNumber><a:ParcelBarcode/></a
:PreadviceResult></CreatePreadviceResult></CreatePreadviceResponse>
b. JSON
{"CreatePreadviceResult":[{"ErrorCode":8,"ErrorMessage":"BusinessUnitCode
10000
Is
Not
Found","OperationResult":-1,"ClientParcelNumber":"1113","ParcelBarcode":""}]}
3) При возникновении исключительной ситуации сервер вернет следующие ошибки
a. XML
<Error><Status>500</Status><Name>DeserializationFailed</Name><Code>1</Code><Message>Форматтер сгенерировал исключение при попытке десериализовать
сообщение: Ошибка десериализации тела сообщения запроса для операции
"SetParcelContent". Префикс "b2c" не определен. Строка 1, позиция 237.</Message></Error>
b. JSON
{"Code":28,"Message":"Deserialization
object
error,
check
your
request
","Name":"Deserialization","Status":500}
4) При возникновении необработанной ошибки сервер вернет следующие ошибки
a. XML
<Error><Status>500</Status><Name>CommonFail</Name><Code>-1</Code><Message>Internal
Server Error</Message></Error>
b. JSON
{"Code":-1,"Message":"Internal Server Error","Name":"CommonFail","Status":500}
13
Контакты
Все вопросы: sales.B2C@hermes-dpd.ru
Технические вопросы: it.integration@hermes-dpd.ru.
14
Примеры подключения и вызова
Запросы для SOAP-сервиса
Консольное приложение на C#
1.1. Добавить Service Reference
1.2. Исходный код
1.2.1. Пример вызова методов
using System;
using ContentAPISample.Hermes.ContentAPI.SoapService;
namespace ContentAPISample
{
class Program
{
static void Main(string[] args)
{
Console.WriteLine("Set parcel contents...");
SetParcelContent();
Console.WriteLine("{0}Get parcel contents...", Environment.NewLine);
GetParcelContent();
15
Console.ReadLine();
}
private static void GetParcelContent()
{
var proxy = new Hermes.ContentAPI.SoapService.SoapServiceClient();
proxy.ClientCredentials.UserName.UserName = "testlogin";
proxy.ClientCredentials.UserName.Password = "testpassword";
var result = proxy.GetParcelContent(new[] {"10009900000318", "1000990000
0317"});
foreach (var r in result)
{
Console.WriteLine("CONTENT BARCODE {0}", r.ParcelBarcode);
foreach (var i in r.Items)
{
Console.WriteLine("Article {0}", i.Article);
Console.WriteLine("Code {0}", i.Code);
Console.WriteLine("Description {0}", i.Description);
Console.WriteLine("Name {0}", i.Name);
Console.WriteLine("Price {0}", i.Price);
Console.WriteLine("Quantity {0}", i.Quantity);
Console.WriteLine(Environment.NewLine);
}
}
proxy.Close();
}
private static void SetParcelContent()
{
var proxy = new Hermes.ContentAPI.SoapService.SoapServiceClient();
proxy.ClientCredentials.UserName.UserName = "testlogin";
proxy.ClientCredentials.UserName.Password = "testpassword";
var result = proxy.SetParcelContent(
new[]
{
new ParcelContent
{
ParcelBarcode = "10009900000318",
Items = new[]
{
new Item
{
Article = "ART1",
Code = "CODE13",
Description = "unknown item",
Name = "knife",
Price = 1450.45d,
Quantity = 2
},
}
},
new ParcelContent
{
ParcelBarcode = "10009900000317",
Items = new[]
{
new Item
{
Article = "ART2",
Code = "CODE14",
Description = "smartphone",
Name = "iphone 10s",
16
Price = 45000,
Quantity = 3
},
new Item
{
Article = "ART4",
Code = "CODE11",
Description = "telephone",
Name = "nokia 3310",
Price = 3000,
Quantity = 10
}
}
}
}
);
foreach (var r in result)
{
Console.WriteLine("RESULT: {0}; MESSAGE: {1}", r.OperationResult, r.
ErrorMessage);
}
proxy.Close();
}
}
}
Выполнение запросов через SoapUI
1.1. Добавить SOAP проект
17
1.2. Чтобы выполнить запрос, нужно сделать следующее
1.2.1. указать входные параметра для метода запроса,
1.2.2. учетную запись в параметрах запроса (Username, Password)
1.2.3. Authentication Type = Preemtive
1.2.4. WSS-Password Type = PasswordText
18
«Чистый» XML-запрос
1. К xml-запросу нужно добавить заголовок с авторизацией, и актуализировать дату создания, текст
запроса выглядит так
a. Обратите внимание на 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="http://schemas.datacontract.org/2004/07/B2C.ParcelContentAPI.DTO"
xmlns:ns2="https://api.hermes-dpd.ru/WS/">
<SOAP-ENV:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.0.xsd" SOAP-ENV:mustUnderstand="1">
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
<wsse:Username>testlogin</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wssusername-token-profile-1.0#PasswordText">testpassword</wsse:Password>
<wsu:Created>2015-08-04T17:19:00.000Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns2:SetParcelContent>
<ns2:parcelContents>
<ns1:ParcelContent>
<ns1:Items>
<ns1:Item>
<ns1:Article>ART1</ns1:Article>
<ns1:Code>CDOE44</ns1:Code>
<ns1:Description>headphones</ns1:Description>
<ns1:Name>SNX DD-56 II</ns1:Name>
<ns1:Price>10589.20</ns1:Price>
<ns1:Quantity>2</ns1:Quantity>
</ns1:Item>
</ns1:Items>
<ns1:ParcelBarcode>10009900000338</ns1:ParcelBarcode>
</ns1:ParcelContent>
</ns2:parcelContents>
</ns2:SetParcelContent>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Ответ:
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<ActivityId xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics"
CorrelationId="38dc2b48-622e-437b-af00-0ef713365c14">7c958eee-7741-4e48-a265c34abb2c05f7</ActivityId>
<o:Security xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuritysecext-1.0.xsd" s:mustUnderstand="1">
<u:Timestamp u:Id="_0">
19
<u:Created>2015-08-04T14:22:27.346Z</u:Created>
<u:Expires>2015-08-04T14:27:27.346Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<SetParcelContentResponse xmlns="https://api.hermes-dpd.ru/WS/">
<SetParcelContentResult
xmlns:a="http://schemas.datacontract.org/2004/07/B2C.ParcelContentAPI.DTO"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ParcelContentResult>
<a:ErrorCode>Success</a:ErrorCode>
<a:ErrorMessage i:nil="true" />
<a:OperationResult>0</a:OperationResult>
<a:ParcelBarcode>10009900000338</a:ParcelBarcode>
</a:ParcelContentResult>
</SetParcelContentResult>
</SetParcelContentResponse>
</s:Body>
</s:Envelope>
2. Запрос можно выполнить на любых онлайн-сервисах soap-клиентов, например, на
http://wsdlbrowser.com
20
Запросы для REST-сервиса
Пример всех запросов XML/JSON для основных типовых методов сервиса вы найдете в этом разделе.
Основная рекомендация – используйте JSON, с POST запросом в XML слишком много ограничений и
условий.
Основные замечания при составлении и отправки JSON-запросов сервису
1. Запрос должен содержать все свойства объекта в алфавитном порядке (см пример запроса),
иначе при десериализации часть значений будет утеряна, за информацией обращайтесь к
описанию сервиса по WSDL.
Основные замечания при составлении и отправки XML-запросов сервису
1. Все имена вызываемых методов должны быть указаны с учетом регистра, как они описаны в WSDL.
2. Запрос должен содержать все свойства объекта в алфавитном порядке (см пример запроса), иначе
при десериализации часть значений будет утеряна, за информацией обращайтесь к описанию
сервиса по WSDL
3. При формировании любого запроса нужно указывать неймспейс xmlns="https://api.hermesdpd.ru/WS/rest" в качестве атрибута элемента с именем = наименованию вызываемого метода
4. Дополнительный неймспейс xmlns:i="http://www.w3.org/2001/XMLSchema-instance" необходим
для отметки пустых значений, особенно для дат, в элементе нужно добавить атрибут i:nil="true".
5.
Дополнительный
неймспейс
xmlns:a="
http://schemas.microsoft.com/2003/10/Serialization/Arrays" в качестве атрибута нужен для
передачи массива значений в качестве параметра
6. Для комплексных объектов, такие как PaymentManagement, необходимо указать неймспейс B2C
xmlns:b2c="http://schemas.datacontract.org/2004/07/B2C.ParcelContentAPI.DTO"
21
Запросы (XML/JSON) на JavaScript (JQuery)
Откройте файл, вложенный в документ. В нем описаны примеры вызовов REST-сервиса через JSON и через
XML
rest_parcelcontent.html
Этот же пример развернут на сервере тестовой интеграции – http://test-api.hermes-dpd.ru
