ElOrder — проект задавшийся целью внедрить на фармацевтическом рынке Украины общие принципы, методы и стандарты прямого безбумажного документооборота между поставщиками лекарственных средств и их клиентами.
При участии в проекте, поставщик поэтапно реализует стандартный интернет-сервис позволяющий выполнять клиентскому приложению следующие операций:
° получение специализированных адресных прайс-листов
° отправка заказа
° получение дефектуры(отказа) поставщика
° получение накладных
° получение изображений сертификатов
Одним из важнейших преимуществ и новаций этого проекта является то, что взаимодействие происходит путем вызова клиентским приложением, в online режиме, методов на web-сервере поставщика, без полу-ручного обмена файлами через email и т.п. технологии.
Поставщику необходимо лишь создать у себя web-сервис, работающий по протоколу SOAP 1.1, который будет выполнять перечисленные операции путем отсылки, приема и обработки xml-документов заданного формата
Описание типового веб-сервиса
WSDL схемы вариантов реализаций веб-сервиса проекта ElOrder можно получить по адресам:
http://www.alba.kiev.ua/elorder/soap/ElOrderService.svc?wsdl
Обобщенная схема работы
В начале работы с сервисом клиент инициализирует сессию (авторизуется) на сервере посредством вызова метода Init, передавая ему информацию идентифицирующую клиента ─ код ОКПО и уникальный идентификатор компьютера.
Отдельно нужно отметить, что в данной схеме клиенту не требуется какой-либо специальной
регистрации, получения логинов-паролей у поставщика ─ по умолчанию клиенту доступно
только получение общего (публичного) прайс — листа. Полный функционал становится
доступным, когда менеджеры поставщика активируют данного клиента, убедившись в его
аутентичности.
Сервер проверяет «активированность» данного ОКПО и компьютера и возвращает идентификатор сессии.
В качестве результата авторизации, помимо сессии, возвращается еще перечень текстовых сообщений пользователю о статусе ОКПО, причине отказа в авторизации, контактных данных менеджера данного клиента и т.п.
Сразу после авторизации клиент автоматически отправляет на сервер (UpdateDeliveryAddressesList) список своих новых и изменившихся точек доставки, отсылая пары
<уникальный идентификатор> — <полный почтовый адрес>. Эта информация используется поставщиком для более оперативного сопоставления точек доставки, имеющихся у него в базе с теми, которые клиент будет указывать при создании заказов.
Этап сопоставления необходим, так как гарантировать то, что клиент правильно и однозначно
укажет адрес, нельзя, а полная и проверенная информация о точках доставки уже есть в
базе поставщика.
Однозначность сопоставления гарантируется тем, что идентификаторы уникальны (используется GUID) и генерируются заново при любом изменении адреса пользователем.
Далее клиент продолжает работу, запрашивая прайс-лист, путем вызова метода GetPriceList.
Обычно прайс-лист генерируется сразу после запроса пользователя, что позволяет предоставлять клиентам наиболее свежую информацию, но может требовать значительных вычислительных затрат с пиками в начале дня. В прайс — лист, помимо перечня лекарственных средств, цен и т.п. информации входит секция с перечнем типов цен, специфичных для данного поставщика, и их кодами.
После получения прайса клиент подготавливает заказ, отдельный для каждой точки доставки, и отправлят его на сервер посредством вызова метода MakeOrder. В заказе указывается точка доставки с ее уникальным идентификатором. Для идентификации типа цены используются коды поставщика.
После получения заказа, поставщик может сгенерировать сообщение, информирующее пользователя о том, что его заказ успешно получен и поступил в обработку.
После обработки (автоматической или ручной) заказа сервер может сгенерировать документ дефектуры с перечнем товаров, которые он поставить не может, и причиной отказа. Сообщение о наличии данного документа отправляет в очередь клиента и будет им получено при ее обработке.
Опрос очереди сообщений выполняется посредством регулярных вызовов клиентом метода
GetNewNotifications в течение u1072 активности сессии.
При обработке очереди сообщений могут выполняться следующие операции:
• показ простого информационного сообщения пользователю
• изменение статуса заказа с показом соответствующего сообщения пользователю
• получение нового документа дефектуры с предложением вернуть его в потребность
Документ дефектуры получает путем отдельного вызова метода GetDocumentByUID с использованием идентификатора из соответствующего сообщения.
Типы данных
• UUID — строка длиной 36 символов без концевых фигурных скобок. Пример — 3605A06ED4E2-
4C14-B814-392540E3CE17. См. UUID
• DataContainer — объект-контейнер для данных со следующими атрибутами:
◦ IsCompressed — boolean
Булевый признак, показывающий, сжаты ли данные. Алгоритм сжатия — zip.
◦ Content — byte array
Массив бинарных данных, содержащий соответствующий документ в сжатом или распакованном виде. В типах WSDL — Base64Binary.
Описание методов
Init
Функция логина/подключения/авторизации клиента к сервису. Выполняется в начале работы. Инициирует сессию работы.
Параметры
• okpo — string.
Код ОКПО организации. При незаданном ОКПО отдается прайс на общих основаниях
• hardKey — string(32).
Уникальный идентификатор компьютера, генерируется на основе кода установки Windows и
CPU ID. Используется для ограничение количества клиентских мест для одного ОКПО.
• clientVersion — string.
Версия клиентского приложения.
Результат
Возвращает объект с атрибутами:
• SessionTicket — UUID.
Идентификатор сессии, в пределах которой выполняется вся работа с сервером. При возврате пустой строки (или строки 00000000-0000-0000-0000-000000000000 — особенность одной из реализаций) считается, что авторизация не выполнена.
• Content — string.
Дополнительные данные. Обычно представляет собой xml-документ с текстовыми сообщениями пользователю.
GetPriceList
Функция для получения специализированного прайс-листа. Ввиду большого объема прайс- листа данные обычно передаются в упакованном виде.
Параметры
• sessionTicket — см. SessionTicket
Идентификатор сессии, полученный на этапе авторизации.
• protocol — Integer
Версия протокола, которую поддерживает данный клиент. Пока существует лишь версия 1.
Результат
Возвращает DataContainer со сжатым xml-файлом прайс-листа.
GetNewNotifications
Функция для получения списка сообщений для u1076 данного ОКПО (не решено — только для ОКПО или еще и для HardKey) из очереди сервера. Вызывается клиентом с некоторой регулярностью (обычно раз в 2 мин.).
Параметры
• sessionTicket — см. SessionTicket
• protocol — см. protocol
• lastNotificationID — Int64
Идентификатор последнего полученного сообщения от этого клиента. Позволяет ограничить список получаемых в запросе сообщений только теми, которые еще не были обработаны данным клиентом.
Результат
Возвращает DataContainer с xml-документом со списком разнотипных сообщений.
GetDocumentByUID
Функция для получения документа, произвольного типа по его идентификатору. На текущий момент используется лишь для получения дефектуры.
Параметры
• sessionTicket — см. SessionTicket
• protocol — см. protocol
• documentUID — UUID
Уникальный идентификатор документа, о существовании которого на сервере известно. Обычно этот идентификатор берется из сообщений о новом документе.
Результат
Возвращает DataContainer с соответствующим документом.
UpdateDeliveryAddressesList
Функция для отсылки списка точек доставки на сервер. Играет дублирующую роль, так как сервер должен принять заказ даже для точки, которая не была отправлена в этом методе.
Параметры
• sessionTicket — см. SessionTicket
• protocol — см. protocol
• addresses — DataContainer
Список адресов точек доставки в виде xml-файла заданного формата.
Результат
Boolean
MakeOrder
Функция для отправки документа заказа на сервер.
Параметры
• sessionTicket — см. SessionTicket
• protocol — см. protocol
• order — DataContainer
Документ заказа в виде xml-файла.
Результат
Boolean
Форматы файлов
Кодировка — UTF-8 или win1251, но с обязательным ее указанием в заголовке xml.
Идентификаторы документов — типа UUID.
Формат дат и дробных фиксирован и описан в файле elorder_types.xsd в виде регулярных выражений. Примеры
DateTime — 10.01.2009 14:15:[12]
Date — 10.01.2009
Float — 145.45
Результат авторизации
Список сообщений
Пример — elorder_notify.xml
Схема — elorder_notify.xsd
Содержит очередь разнотипных сообщений для клиента. Список типов сообщений:
• TextNews
Текстовое сообщение, которое показывается пользователю.
• ChangesInOrderStatus
Сообщение с изменением статуса документа заказа и текстовым сообщением пользователю.
• DeficiencyInOrder
Сообщение о том, что для документа заказа, отосланного ранее, сформирован документ дефектуры.
Документ прайса
Пример — elorder_price.xml
Схема —
На текущий момент содержит минимум необходимой информации для уменьшения его размера.
Включает список типов цен с их кодами, названиями и длительностью отсрочки.
Как расширение от компании «Оптима» может идти перечень акций (на данный момент не используется).
Документ заказа
Пример — elorder_order.xml
Схема — elorder_order.xsd
Для каждой точки доставки создается раздельный.
В одном заказе могут быть позиции с разными типами цен. Для идентификации типов цен по возможности используются коды поставщика (приходят с прайсом).
Документ дефектуры (отказа) поставщика
Пример — elorder_deficiency.xml
Схема — elorder_deficiency.xsd
Документ, содержащий перечень позиций из конкретного заказа, которые не могут быть поставлены.
Документ накладной
Пример — elorder_consignment.xml
Схема — elorder_consignment.xsd
Формат документа накладной находится в процессе согласования и окончательно не утвержден.
За основу при его разработке брали формат mmo.