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.
(044) 585-97-12