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

Client API

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

Hermes Russia

Содержание

Содержание        2

Версия документа        4

Краткое описание        4

Описание терминов        5

Расположение        6

Основной модуль API        7

Создание заказов        7

Формирование штрих-кодов посылок        7

Метод CreatePreadvice        8

Метод UpdatePreadvice        9

Метод DeletePreadvice        10

Метод GetPreadvices        11

Метод SendPreadvicesToDelivery        12

Метод SendAllPreadvicesToDelivery        12

Выгрузка списков ПВЗ        13

Метод GetParcelShops        13

Отслеживание статусов посылок        14

Метод GetStatusesByBusinessUnit        14

Метод GetStatusesByParcelBarcodes        15

Получение информации о возвращаемых посылках        16

Метод GetReturnInfoByBusinessUnit        16

Объектная модель        17

Preadvice        17

PreadviceResult        19

ParcelShop        20

PreadviceResult        21

Status        21

ReturnInfo        21

Schedule        22

DayTime        22

ExtraParam        23

CurrencyCode        24

PaymentType        24

ServiceType        24

Получение файла с наклейками        25

Метод GetPdfStickerBytes        25

Объектная модель        25

SheetSize        25

Обработка ошибок        26

Коды ошибок        26

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

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

Контакты        31

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

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

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

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

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

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

Запрос на PHP        40

Тестовая интеграция для 1С        44

Приложение        45

Список статусов посылок        45

Список причин отказа получателя от посылки        48

Формат даты в ответе сервисов        48

Версия документа

Версия	Дата	Автор	Комментарий
1.0	09.07.2014		Документ создан
1.1	28.07.2014		Переработка
1.2	30.07.2014		Доработка
1.3	26.09.2014		Доработка, причина отказа посылки
1.4	07.10.2014		Доработка
2.0	28.10.2014		Доработка и переработка, REST-сервис
2.4	13.11.2014		Обработка ошибок для REST-сервиса, Полные примеры вызова методов REST-сервиса, Добавлены типы предоставляемых услуг для пункта выдачи (ParcelShop) Исправлены ошибки, оптимизация
2.5	17.11.2014		Доработки и улучшения
2.63	26.10.2015		Исключена документация по курьерской доставке, т. к. пока эта функция недоступна Добавлены новые услуги при получении списка ПВЗ

Краткое описание

В данном документе описаны спецификации веб-сервисов компании Hermes Russia. Веб-сервисы компании Hermes Russia позволяют клиентам осуществить интеграцию для выполнения основных операций.

Для клиентов доступны два типа взаимодействия с веб-сервисами: REST и классический SOAP.

Описание терминов

ПВЗ – Пункт выдачи заказов Штрих-код посылки – уникальный номер посылки, используемый для графического отображения на наклейке на посылке и для всех взаимодействий по посылке между клиентом, получателем и Hermes Russia Бизнес-юнит – структурное подразделение клиента. Если у клиента есть несколько каталогов, сайтов или брендов, для которых на всех стадиях жизненного цикла доставки посылки должно быть явно известно, к которому из них она относится, то такие структуры клиента необходимо выделить в самостоятельные бизнес-юниты «Экспресс-возврат» - услуга возврата уже выкупленных сколько угодно давно получателем товаров в любом состоянии. Товары могут быть из разных посылок. В одном возврате могут быть не все товары из первоначальной посылки. Первоначальная посылка могла быть доставлена другой службой доставки. Предзаказ - Информация о еще не переданных на доставку посылках.

Расположение

Веб-сервисы Hermes Russia расположены по адресу

Описание всех сервисов с примерами и документацией – https://api.hermesrussia. ru

Тестовая версия:
Основной модуль API SOAP https://test-api.hermes-dpd.ru/ws/webservice.svc? wsdl

https://test-api.hermes-dpd.ru/ws/webservice.svc? singlewsdl

REST https://test-api.hermes-dpd. ru/ws/restservice. svc? wsdl

https://test-api. hermes-dpd. ru/ws/restservice. svc? singlewsdl

Тестовая учетная запись
пользователь – testlogin, пароль – testpassword, код бизнес-юнита BusinessUnitCode – 1000 код склада DirectDistributionCenterCode/ReturnDistributionCenterCode – 437, при создании заказа CreatePreadvice можно не указывать, т. к. система сама попытается найти и подставить нужный номер. для тестовой версии при создании заказа CreatePreadvice поле ParcelBarcode нужно оставить пустым, т. к. код посылки будет сгенерирован автоматически. При вызове метода получения статусов по посылкам GetStatusesByParcelBarcodes используйте следующие номера посылок для примера: 99000176079743,33332000009663,99000176131090,99000176157939,99000176207399.
Модуль API генерации наклеек SOAP https://test-api.hermes-dpd. ru/ss/soapservice. svc? wsdl

https://test-api.hermes-dpd. ru/ss/soapservice. svc? singlewsdl 

REST https://test-api.hermes-dpd. ru/ss/restservice. svc? wsdl

https://test-api. hermes-dpd. ru/ss/restservice. svc? singlewsdl

Производственная версия:
Основной модуль API SOAP https://api.hermes-dpd. ru/ws/webservice. svc? wsdl

https://api.hermes-dpd. ru/ws/webservice. svc? singlewsdl

REST https://api.hermes-dpd. ru/ws/restservice. svc? wsdl

https://api. hermes-dpd. ru/WS/restservice. svc? singlewsdl

Модуль API генерации наклеек SOAP https://api.hermes-dpd. ru/ss/soapservice. svc? wsdl 

https://api.hermes-dpd. ru/ss/soapservice. svc? singlewsdl 

REST https://api.hermes-dpd. ru/ss/restservice. svc? wsdl

https://api. hermes-dpd. ru/ss/restservice. svc? singlewsdl

В качестве транспортного протокола используется https протокол. Авторизация пользователей производится по паре логин-пароль. Для получения логина и пароля необходимо обратиться в отдел продаж компании Hermes Russia. Авторизация для всех сервисов идентична.

Основной модуль API

Создание заказов

Создание заказов на доставку посылок состоит из следующих этапов:

Получение и актуализация списка доступных пунктов выдачи Загрузка информации о посылках Анализ и/или корректировка информации о посылках Анализ и/или корректировка информации о контенте посылок (описано в отдельной документации ParcelContent API) Отправка посылок на доставку

За создание заказов отвечают следующие методы веб-сервисов:

Метод GetParcelShops – получение списка доступных ПВЗ на текущий момент Метод CreatePreadvice – первоначальная передача информации о посылках Метод UpdatePreadvice – обновление информации о еще не переданных на доставку посылках Метод DeletePreadvice – удаление еще не переданных на доставку посылок Метод GetPreadvice – получение списка всех еще не переданных на доставку посылок Метод SendPreadvicesToDelivery – отправка на доставку выбранных посылок Метод SendAllPreadvicesToDelivery – отправка на доставку всех еще не переданных на доставку посылок

Формирование штрих-кодов посылок

Доступны два варианта формирования штрих-кодов посылок:

Системой клиента Системой Hermes Russia

При формировании штрих-кодов посылок системой клиента необходимо при первоначальной передаче информации о посылках методом CreatePreadvice указывать предварительно сформированный штрих-код в поле ParcelBarcode. Если нет необходимости в дополнительном идентификаторе посылки, то в поле ClientParcelNumber нужно указать значение из поля ParcelBarcode, т. е. значение в этом поле должно оставаться уникальным в системе клиента, даже если в нем нет необходимости.

При формировании штрих-кодов посылок системой Hermes Russia необходимо при первоначальной передаче информации о посылках методом CreatePreadvice не заполнять поле ParcelBarcode. Поле же ClientParcelNumber должно быть обязательно заполнено уникальным идентификатором посылки в системе клиента. В ответном сообщении метода CreatePreadvice будет возвращен сформированный системой Hermes Russia штрих-код посылки, который нужно сопоставить по полю ClientParcelNumber с посылками и сохранить в системе клиента, т. к. все дальнейшие взаимодействия по посылкам осуществляются по штрих-коду посылки.