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

По умолчанию используется формирование штрих-кодов системой клиента. Для перехода на формирование штрих-кодов системой Hermes Russia необходимо обратиться к вашему менеджеру Hermes Russia для настройки этого параметра. При попытке оставить поле ParcelBarcode пустым без этой настройки будет выдаваться исключение об обязательности поля.

Управление посылками

Метод CreatePreadvice

Описание

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

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
preadvices	Массив записей с информацией о посылках	Preadvice[]	Да

Выходные параметры

Параметр	Описание	Тип	Пример
PreadviceResults	Массив результатов. Один результат по каждой посылке.	PreadviceResult[]	См. описание используемых типов данных

Метод UpdatePreadvice

Описание

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

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
preadvices	Массив записей с обновленной информацией о посылках	Preadvice[]	Да	См. описание используемых типов данных

Выходные параметры

Параметр	Описание	Тип	Пример
PreadviceResults	Массив результатов. Один результат по каждой посылке.	PreadviceResult[]	См. описание используемых типов данных

Метод DeletePreadvice

Описание

Данный метод позволяет удалять еще не переданные на доставку посылки, если необходимость в их доставке отпала или данные были ошибочными. Удаление информации о посылках происходит по совпадению штрих-кодов.

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
parcelBarcodes	Массив штрих-кодов посылок на удаление	String[]	Да	12345678901234, 12345678901235

Выходные параметры

Параметр	Описание	Тип	Пример
PreadviceResults	Массив результатов. Один результат по каждой посылке.	PreadviceResult[]	См. описание используемых типов данных

Метод GetPreadvices

Описание

Данный метод позволяет получить список всех еще не переданных на доставку посылок заданного бизнес-юнита.

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
businessUnitCode	Номер бизнес-юнита	String	Да	1234

Выходные параметры

Параметр	Описание	Тип	Пример
Preadvices	Массив записей с информацией о еще не переданных на доставку посылках	Preadvice[]	См. описание используемых типов данных

Передача посылок на доставку

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

В случае ошибки на стороне Hermes Russia при вызове этих методов: таймаут, внутренняя ошибка, недоступность сервера и т. д., - необходимо повторно вызвать этот метод и проанализировать код ответа ErrorCode в каждом результате. Если код будет PreaviceExists или PreadviceWasSentToDelivery, то можно считать, что первая итерация вызова метода успешно отправила посылку или посылки на доставку.

Метод SendPreadvicesToDelivery

Описание

Данный метод предназначен для передачи указанного списка посылок на доставку. Список посылок представлен в виде их штрих-кодов.

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
parcelBarcodes	Массив штрих-кодов посылок для передачи на доставку	String[]	Да	12345678901234, 12345678901235

Выходные параметры

Параметр	Описание	Тип	Пример
PreadviceResults	Массив результатов. Один результат по каждой посылке.	PreadviceResult[]	См. описание используемых типов данных

Метод SendAllPreadvicesToDelivery

Описание

Данный метод позволяет передать на доставку все посылки заданного бизнес-юнита, которые еще не были переданы на доставку.

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
businessUnitCode	Номер бизнес-юнита	String	Да	1234

Выходные параметры

Параметр	Описание	Тип	Пример
PreadviceResults	Массив результатов. Один результат по каждой посылке.	PreadviceResult[]	См. описание используемых типов данных

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

Метод GetParcelShops

Описание

Данный метод предназначен для получения списка доступных для заданного бизнес-юнита ПВЗ. Метод возвращает сразу все доступные ПВЗ. Для обновления данных в системе клиента необходимо анализировать поле UpdateTimestamp, чтобы выявить записи, которые были обновлены с прошлой обработки списка.

Необходимо обновлять список не реже одного раза в сутки. Закрытые, закрывающиеся и другие неактуальные ПВЗ не передаются, поэтому стоит позаботиться об актуализации списка на стороне клиента.

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

Для получения стоимости доставки используйте этот метод совместно с другим сервисом – Calculator API. Документация прилагается к текущей.

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
businessUnitCode	Номер бизнес-юнита	String	Да	1234

Выходные параметры

Параметр	Описание	Тип	Пример
ParcelShops	Массив записей с информацией о ПВЗ	ParcelShop[]	См. описание используемых типов данных

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

Отслеживание статусов посылок возможно следующими методами:

Метод GetStatusesByBusinessUnit – непрерывное получение статусов посылок по бизнес-юниту Метод GetStatusesByParcelBarcode – получение статусов по штрих-коду посылки

Рекомендуется выбирать небольшие периоды времени для запроса статусов, поскольку иногда их количество за месяц может достигать нескольких десятков тысяч. Рекомендуется использовать не большие периоды, либо запрашивать по частям.

Метод получения статусов по посылкам рекомендуется использовать только в технических или в единичных запросах.

Метод GetStatusesByBusinessUnit

Описание

Данный метод предназначен для решения задачи получения всех статусов всех посылок заданного бизнес-юнита в режиме, приближенном к реальному времени и сохранении статусов в системе клиента. Метод позволяет получить все статусы, которые появились в системе Hermes Russia с заданной даты.

Данный метод не возвращает статусы посылок по услуге «Экспресс-возврат».

Рекомендуется использовать только этот метод для автоматического получения статусов в систему клиента.

Алгоритм работы с методом

При первом вызове необходимо передать в параметре dateFrom текущую дату Далее гарантируется передача всех статусов без потерь или повторов, при условии, что параметр dateFrom будет содержать значение, возвращенное в параметре NextRequestDateFrom из предыдущего вызова метода, а параметр dateTo необходимо оставлять пустым При удалении статуса, он передается еще раз, но уже с заполненным полем StatusDeleteTimestamp

Входные параметры

Параметр	Описание	Тип	Обязательный	Пример
businessUnitCode	Код бизнес-юнита	String	Да	1234
dateFrom	Дата и время начала периода, за который необходимо вернуть статусы	DateTime	Да	2014-03-17T20:49:19.000
dateTo	Дата и время окончания периода, за который необходимо вернуть статусы. Обычно должно быть пустым. Необходимо заполнять, только если нужны статусы за старые периоды из-за сбоя на стороне клиента.	Nullable DateTime	Нет	null

Выходные параметры

Параметр	Описание	Тип	Пример
NextRequestDateFrom	Дата окончания периода, за который переданы статусы. Необходимо сохранять эту дату в системе клиента и передавать в следующем запросе статусов в параметре DateFrom	DateTime	2014-03-17T21:49:19.000 Возможны варианты передачи даты в формате /Date(1449672181000+0300)/, как ее распознать, см. здесь
Statuses	Массив записей с информацией о статусе посылки	Status[]