Nr SPECYFIKACJA WYMIANY DANYCH POMIĘDZY PROGRAMEM KS-APTEKA WINDOWS 1.INFORMACJE PODSTAWOWE Wymiana danych pomiędzy programem KS-APTEKA Windows odbywa się z wykorzystaniem technologii Web Services (protokół SOAP Simple Object Access Protocol). Po stronie programu aptecznego zaimplementowany jest klient usług, zaś po stronie sklepu internetowego konieczne jest zaimplementowanie serwera usług. Rozwiązanie takie jest podyktowane faktem, że wiele aptek jako medium dostępu do Internetu wykorzystuje Neostradę, która nie gwarantuje stałego adresu IP. Klient usług jest wbudowany do modułu APW45 Apteka internetowa wchodzącego w skład programu KS-APTEKA Windows. Działanie modułu jest możliwe po wykupieniu dodatkowej licencji w firmie KAMSOFT. Raporty z wymiany danych (pliki XML przekazywane w obu kierunkach) zapisywane są do katalogu C:\KS\APW\Raporty\iApEwd (przy założeniu, że program apteczny został zainstalowany do domyślnego katalogu). Strona 1 z 11
2.USŁUGI WYMIANY DANYCH 2.1.Wymiana danych o ofercie apteki internetowej SetOffer Argumenty AUserName string Nazwa użytkownika APassword string hasło użytkownika AOffer string informacje o ofercie apteki internetowej Wynikiem wywołania usługi jest wartość logiczna True lub False. Usługa przesyła do serwisu internetowego ofertę apteki. Na ofertę składają się następujące elementy: Wizytówka apteki (dane właściciela apteki internetowej) znacznik <card>; Definicje form transportu element <transports>. Poszczególne formy transportu reprezentują elementy <transport>; Definicje form płatności element <payments>. Poszczególne formy płatności reprezentują elementy <payment>; Towary element <items>. Poszczególne towary reprezentują elementy <item>. Znaczenie wybranych elementów opisujących towar: o <id> - identyfikator towaru w ofercie apteki internetowej po stronie KS-AOW; o <intname> nazwa międzynarodowa, o <form> - postać, o <dose> - dawka, o <package> - opakowanie, o <unit> - jednostka miary, o <originalprice> - cena pierwotna, o <deleted> - wskaźnik czy towar został ukryty w ofercie. Jeżeli towar został ukryty to nie jest przesyłany jego opis i zdjęcie (przesyłane są puste elementy - <desc /> i <photo />). Kategorie towarów element <groups>. Każdą grupę reprezentuje znacznik <group> zaś pozycje grupy element <items> będący elementem podrzędnym w stosunku do elementu <group>. Pozycje grupy są reprezentowane elementem <item>. Znaczenie elementów opisujących pozycję grupy: o <idiatw> - numer towaru w ofercie apteki internetowej po stronie KS-AOW, o <itemno> - numer kolejny pozycji w grupie; o <deleted> - wskaźnik czy pozycja grupy została usunięta. Użytkownik programu w momencie wywołania funkcji aktualizacji oferty ma możliwość wyboru elementów oferty, które mają być wysłane na serwer. Jeśli do aktualizacji wybrane zostaną opisy i/lub zdjęcia towarów, oferta jest dzielona na części. W takiej sytuacji pierwsza część oferty zawiera informacje o wizytówce firmy, definicjach form transportu i płatności oraz pierwszą część informacji o towarach. Ostatnia część zawiera, oprócz informacji o towarach, dane dotyczące kategorii. Opis towaru oraz zdjęcie są zapisane jako dane znakowe CDATA. Zdjęcie jest dodatkowo zakodowane algorytmem BASE64. Informacja przekazywana argumentem AOrders powinna mieć strukturę zgodną z przykładem przedstawionym na następnej stronie. Strona 2 z 11
<?xml version="1.0" encoding="windows-1250"?> <offer> <card> <id>000001</id> <name1>apteka "Słoneczna"</name1> <name2>mgr.farm. Jan Kowalski</name2> <name3></name3> <name4></name4> <postcode>40-235</postcode> <city>katowice</city> <street>ul. 1-go Maja</street> <houseno>133</houseno> <placeno></placeno> <nip>634-013-21-17</nip> <regon>271034150</regon> <phoneno>(032) 209-07-05</phoneno> <faxno>(032) 209-07-15</faxno> <bank>pko BP</bank> <account>12 1234 5678 1234 3456 5678 7890</account> </card> <transports> <transport> <id>1</id> <name>poczta Polska</name> <symbol>pp</symbol> <price>6.5</price> <codprice>1.5</codprice> <active>1</active> </transport> </transports> <payments> <payment> <id>1</id> <name>przelew</name> <symbol>pr</symbol> <active>1</active> </payment> </payments> <items> <item> <id>1</id> <name>elmex Płyn d/pł.ust Sensitive 400ml</name> <intname>-</intname> <form>-</form> <dose>-</dose> <package>400 ml</package> <producer>gaba INTERNATION.AG</producer> <country>szwajcaria</country> <bloz07>7028143</bloz07> <bloz12>721310212518</bloz12> <unit>op.</unit> <pkwiu></pkwiu> <vat>22</vat> <price>18.53</price> <originalprice></originalprice> <deleted>0</deleted> <desc><![cdata[opis towaru]]></desc> <photo><![cdata[zdjęcie towaru zakodowane algorytmem BASE64]]></photo> </item> </items> <groups> <group> <id>1</id> <parentid>0</parentid> <name>nowości</name> <symbol>nw</symbol> <deleted>0</deleted> <items> <item> <idiatw>6263</idiatw> <itemno>1</itemno> <deleted>0</deleted> </item> </items> </group> </groups> </offer> Strona 3 z 11
2.2.Wymiana danych o zamówieniach GetOrders Argumenty: AUserName string nazwa użytkownika APassword string hasło użytkownika ALastOrderId integer numer ostatniego poprawnie odebranego zamówienia Usługa zwraca informacje w postaci ciągu znaków (string) o zamówieniach złożonych przez klientów. Odpowiedź powinna zawierać zamówienia o identyfikatorach wyższych od podanego argumentem ALastOrderId. Pola name1 do placeno w nagłówku zamówienia służą do przekazania alternatywnego odbiorcy oraz adresu dostawy jeśli mają być inne niż te zapisane przy kliencie (pole customer ). W przypadku, gdy pola te będą puste, program wypełnia te pola danymi odczytanymi z opisu klienta. Działanie takie związane jest z faktem, że do dalszej obsługi zamówień, np. drukowanie listów przewozowych, wykorzystywane są dane odbiorcy i adres dostawy z nagłówka zamówienia. Informacje o klientach zapisywane są do aptecznej bazy pacjentów. Klient jest identyfikowany na podstawie pola login odpowiadającego nazwie konta klienta w sklepie internetowym. Jeśli w aptecznej bazie pacjentów zostanie odnaleziony klient o podanym loginie to jego dane są aktualizowane na podstawie danych dostarczonych z zamówieniem, w przeciwnym wypadku zakładana jest nowa karta pacjenta. Formy płatności (pole payment ) i transportu (pole transport ) identyfikowane są za pomocą pola symbol. Pole name jest przekazywane w celach informacyjnych W celu poprawnego powiązania konieczne jest w programie aptecznym stworzenie odpowiadających definicji dokumentów pieniężnych oraz definicji form transportu. Zamawiane towary mogą być identyfikowane na trzy sposoby: Pole idtowr klient usług spodziewa się w tym miejscu identyfikatora towaru z aptecznej bazy towarów. Rozwiązanie takie może być stosowane przez apteki, które ofertę apteki internetowej budują za pomocą panelu administracyjnego sklepu internetowego; Pole idiatw klient usług spodziewa się w tym miejscu identyfikatora towaru pochodzącego ze zbudowanej w programie APW45 oferty apteki internetowej; Pola bloz07 i bloz12 siedmio i dwunastocyfrowy identyfikator towaru pochodzący z bazy BLOZ. W przypadku, gdy żaden z wymienionych wyżej identyfikatorów nie zostanie określony lub klient nie odnajdzie w bazie towarów odpowiadającej pozycji, użytkownik programu KS-AOW ma możliwość ręcznego powiązania pozycji zamówienia z pozycją aptecznej bazy towarów. Strona 4 z 11
Informacja zwrotna powinna mieć strukturę zgodną z poniższym przykładem: <?xml version="1.0" encoding="windows-1250"?> <orders> <order> <id>4478</id> <number>4478</number> <date>2006-07-28t08:12:22</date> <status>0</status> <name1>kowalski</name1> <name2>jan</name2> <country></country> <city>katowice</city> <postcode>40-235</postcode> <street>ul. 1-go Maja</street> <houseno>133</houseno> <placeno></placeno> <remarks>uwagi dotyczące zamówienia</remarks> <customer> <id>2274</id> <name1>przedsiębiorstwo Informatyczne</name1> <name2>kamsoft</name2> <country></country> <city>katowice</city> <postcode>40-235</postcode> <street>ul. 1-go Maja</street> <houseno>133</houseno> <placeno></placeno> <nip></nip> <regon></regon> <phoneno>(032) 209 07 05</phoneno> <mobileno></mobileno> <faxno>(032) 209 07 15</faxno> <email>2123@kamsoft.pl</email> <login>ksadmin</login> </customer> <payment> <id>2</id> <symbol>zp</symbol> <name>za pobraniem</name> </payment> <transport> <id>4</id> <symbol>pp</symbol> <name>poczta Polska</name> </transport> <items> <orderitem> <itemno>1</itemno> <idtowr>4321</idtowr> <idiatw></idiatw> <quantity>2</quantity> <price>12.09</price> <bloz07>8052711</bloz07> <bloz12>224780211395</bloz12> <name>2 KC Xtreme 12 tabl.</name> <producer>zakłady farmaceutyczne Colfarm, Polska</producer> </orderitem> </items> </order> </orders> Strona 5 z 11
SetOrders Argumenty: AUserName string nazwa użytkownika APassword string hasło użytkownika AOrders string informacje o zamówieniach, w których zaszły zmiany w aptece Wynikiem wywołania usługi jest wartość logiczna True lub False. Argument AOrders zawiera informacje o zamówieniach, w których zaszły zmiany w aptece. Zmianą taką może być: Przypisanie towaru do pozycji zamówienia; Zmiana statusu zamówienia; Wystawienie listu przewozowego do zamówienia. Struktura informacji przekazywanych do serwera usług jest podobna do struktury informacji zwracanych przez usługę GetOrders. Zestaw informacji opisujących zamówienie jest rozszerzony o pole deleted informujące o usunięciu zamówienia (przyjmuje wtedy wartość 1 ). Ponadto, przy każdym zamówieniu, przekazywana jest informacja o numerze wystawionego listu przewozowego oraz dacie jego wystawienia (pole letter ). Po każdym poprawnym wysłaniu zamówień do serwera, w programie KS-AOW zapisywana jest data ostatniego przesłania danych. Przy następnej próbie komunikacji zostaną wysłane zamówienia, dla których data modyfikacji będzie nowsza od daty zapisanej. Strona 6 z 11
Informacja przekazywana argumentem AOrders ma następującą postać: <?xml version="1.0" encoding="windows-1250"?> <orders> <order> <id>190</id> <number>4478</number> <date>2006.07.28 08:12:22</date> <status>4</status> <name1>kowalski</name1> <name2>jan</name2> <country></country> <city>katowice</city> <postcode>40-235</postcode> <street>ul. 1-go Maja</street> <houseno>133</houseno> <placeno></placeno> <remarks>uwagi dotyczące zamówienia</remarks> <deleted>0</deleted> <customer> <id>780</id> <name1>przedsiębiorstwo Informatyczne</name1> <name2>kamsoft</name2> <country></country> <city>katowice</city> <postcode>40-235</postcode> <street>ul. 1-go Maja</street> <houseno>133</houseno> <placeno></placeno> <nip></nip> <regon></regon> <phoneno>(032) 209 07 05</phoneno> <mobileno></mobileno> <faxno>(032) 209 07 15</faxno> <email>2123@kamsoft.pl</email> <login>ksadmin</login> </customer> <payment> <id>102</id> <symbol>zp</symbol> <name>za pobraniem</name> </payment> <transport> <id>4</id> <symbol>pp</symbol> <name>poczta polska</name> </transport> <items> <orderitem> <itemno>1</itemno> <idtowr>4321</idtowr> <idiatw></idiatw> <quantity>2</quantity> <price>12.09</price> <bloz07>8052711</bloz07> <bloz12>224780211395</bloz12> <name>2 KC Xtreme 12 tabl.</name> <producer>zakłady farmaceutyczne Colfarm, Polska</producer> </orderitem> </items> <letter> <number>159007733334347449</number> <date>2006.07.29</date> </letter> </order> </orders> Strona 7 z 11
2.3.WSDL Interfejs serwera wymiany danych powinien być zgodny z dokumentem WSDL (Web Service Definition Language) przedstawionym poniżej: <?xml version="1.0"?> <definitions name="ishopservice" targetnamespace="urn:ishopservice" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="urn:ishopservice" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <types xmlns="http://schemas.xmlsoap.org/wsdl/" /> <message name="getordersrequest"> <part name="ausername" type="xsd:string" /> <part name="apassword" type="xsd:string" /> <part name="alastorderid" type="xsd:int" /> <message name="getordersresponse"> <part name="return" type="xsd:string" /> <message name="setordersrequest"> <part name="ausername" type="xsd:string" /> <part name="apassword" type="xsd:string" /> <part name="orders" type="xsd:string" /> <message name="setordersresponse"> <part name="return" type="xsd:boolean" /> <message name="setofferrequest"> <part name="ausername" type="xsd:string" /> <part name="apassword" type="xsd:string" /> <part name="offer" type="xsd:string" /> <message name="setofferresponse"> <part name="return" type="xsd:boolean" /> <porttype name="ishopserviceport"> <operation name="getorders"> <input message="tns:getordersrequest" /> <output message="tns:getordersresponse" /> <operation name="setorders"> <input message="tns:setordersrequest" /> <output message="tns:setordersresponse" /> <operation name="setoffer"> <input message="tns:setofferrequest" /> <output message="tns:setofferresponse" /> </porttype> <binding name="ishopservicebinding" type="tns:ishopserviceport"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" /> <operation name="getorders"> <soap:operation soapaction="urn:soap_ishop#soap_ishop_server#getorders" /> <input> </input> <output> </output> <operation name="setorders"> <soap:operation soapaction="urn:soap_ishop#soap_ishop_server#setorders" /> <input> </input> <output> </output> <operation name="setoffer"> <soap:operation soapaction="urn:soap_ishop#soap_ishop_server#setoffer" /> Strona 8 z 11
<input> </input> <output> </output> </binding> <service name="ishopserviceservice"> <documentation /> <port name="ishopserviceport" binding="tns:ishopservicebinding"> <soap:address location="https://www.apteka.pl/connect/ishopservice.php" /> </port> </service> </definitions> Strona 9 z 11
3.APW45 APTEKA INTERNETOWA 3.1.Konfiguracja parametrów połączenia Parametry związane z połączeniem klienta usług z serwerem należy określić w module APW45. Odpowiednia funkcja dostępna jest pod pozycją Ustawienia w menu Komunikacja (rys. 1). Rys. 1. Okno ustawień komunikacji. Należy określić wartości pól: Apteka internetowa w polu tym należy wskazać wartość Inna ; Adres serwera wymiany danych w to pole należy wpisać adres dokumentu WSDL opisującego usługę; Hasło hasło przekazywane jako argument funkcji wymiany danych. Oprócz hasła, funkcje wymiany danych wymagają także podania nazwy użytkownika. Jako nazwę użytkownika program przekazuje do usługi sześciocyfrowy numer apteki nadany przez firmę KAMSOFT. Numer ten można znaleźć na zakładce Licencja wizytówki apteki (rys. 2) dostępnej w module APW41 Administrator. Rys. 2. Informacja o identyfikatorze apteki w wizytówce. Strona 10 z 11
3.2.Funkcje wymiany danych Funkcje związane z wymianą danych zgrupowane zostały w menu Komunikacja modułu APW45 (rys. 3). Rys. 3. Funkcje wymiany danych w APW45. Do dyspozycji są następujące funkcje: Pobierz zamówienia wywołanie funkcji powoduje w pierwszym kroku przesłanie na serwer informacji o zamówieniach, które uległy zmianie w aptece, a następnie pobranie z serwera nowych zamówień. Pobierz opinie o towarach funkcja umożliwia pobranie wpisanych przez klientów apteki internetowej opinii dotyczących poszczególnych towarów. Po zatwierdzeniu przez operatora opinie są prezentowane pozostałym klientom wraz z opisem towaru, którego dotyczą. Pobierz bazę adresów funkcji Newsletter funkcja pobiera z serwisu internetowego adresy e-mail klientów, którzy wyrazili chęć otrzymywania nowinek dotyczących apteki. Aktualizuj ofertę wywołanie funkcji powoduje wysłanie na serwer informacji o ofercie apteki internetowej utworzonej w APW45. Po wywołaniu funkcji wyświetlane jest okno (rys. 4), w którym użytkownik decyduje jakie elementy oferty mają zostać zaktualizowane. Rys. 4. Wybór elementów do aktualizacji. Strona 11 z 11