apaczka websrevice api integration

Apaczka – the fastest developing logistics operator in Poland

 

Apaczka


In 2015 Apaczka was awarded with Ekomersy 2015 award for "The service supportingg e-shop logistics". Apaczka offers logistics services from leading companies in the courier industry. This enables programmers to offer clients the best courier services at very attractive prices, and also relieves them of their personal contact with a courier company deploying new e-commerce systems.

Dostarczane materiały


Apaczka udostępnia bogatą liczbę materiałów pozwalającą na integracje serwisu ze sklepem internetowym użytkownika. Co pozwala oszczędzić czas na logowanie się do serwisu i wpisywanie w nim danych, ponieważ po integracji można tego dokonać bezpośrednio z panelu własnej stron sklepu.


Materiały udostępnione można znaleźć na stronie serwisu, a mowa tu o:

  • Dokumentacja, ułatwiająca zrozumienie i przeprowadzenie integracji API z zewnętrznym serwisem. Można ją znaleźć pod adresem: https://www.apaczka.pl/dokumentacja_api.php
  • Gotowy skrypt PHP, dzięki któremu możemy komunikować się z serwisem przesyłając przez niego niezbędne dane do złożenia zamówienia, który znajduje się pod adresem: https://www.apaczka.pl/integracje.html
  • Załącznik w formacie WSDL opisujący Webservice API, który można odnaleźć pod adresem: https://www.apaczka.pl/webservice/order/?wsdl

Dodatkowo serwis Apaczka ma przeprowadzoną już gotową integrację dla wielu popularnych domen zajmujących się sklepami internetowymi. Dzięki czemu wystarczy pobrać odpowiednią wtyczkę, która jest umieszczona w panelu administracyjnym danego serwisu. Do sklepów internetowych z gotową integracją należą między innymi:

 

 

Integracja


Aby użytkownik mógł korzystać z Apaczka Webservices API musi być zarejestrowany w serwisie i mieć podpisaną umowę z Apaczka. Po czym, gdy umowa zostanie zatwierdzona, użytkownik powinien ubiegać się o otrzymanie klucz API, który jest niezbędny do prawidłowego działania zintegrowanego serwisu. W celu uzyskania klucza API należy po potwierdzeniu umowy skontaktować się z Biurem Obsługi Klienta Apaczki.

1 Przygotowanie katalogów


Przed przystąpieniem do integracji, należy najpierw zająć się przygotowaniem katalogów w aplikacji jDesigner. Zostaną w nim umieszczone wszystkie niezbędne obiekty, które pozwolą na komunikacje Apaczka Webservices API z własnym serwisem. Pierwszy katalog będzie nosił nazwę API, zostanie w nim umieszczone API Apaczki, jak również inne generowane w przyszłości obiekty API. By utworzyć katalog, klikamy prawym przyciskiem myszy w miejscu, gdzie w designer znajdują się wszystkie nasze obiekty i katalogi. Następnie wybieramy z listy opcje nowy->katalog. Po czym pojawi się okno, w którym nadajemy nazwę nowemu katalogowi:

 


Następnie tworzymy katalog Apaczka. Dokonujemy tego analogicznie jak w przypadku API, jednak z małą różnicą. Zamiast klikać prawym przyciskiem myszy na dowolne miejsce, to klikamy na poprzednio stworzony folder. Gdy już posiadamy katalog Apaczka, to przystępujemy do utworzenia katalogów WebServices, DAO, Config, xml oraz Install. Dokonujemy tego tak samo, jak w poprzednich przypadkach, tylko tym razem prawym przyciskiem myszy klikamy na katalog Apaczka. Utworzona struktura katalogów powinna wyglądać następująco:

 


Gdy posiadamy już stworzona pełną strukturę katalogów możemy przystąpić do przygotowania paczki obiektów API.

2 Generowanie klas z załącznika WSDL


W naszej integracji w celu połączenia z serwisem Apaczka Webservice API, został wykorzystany złącznik w formacie WSDL. Za jego pomocą wygenerowano klasy, które są niezbędne do prawidłowego komunikowania się serwisem Apaczka. Można tego za pomocą konsoli z wierszem poleceń znajdującego się w systemie. By tego dokonać, należy pamiętać, że musimy mieć zainstalowane na komputerze oprogramowanie Java. Gdy jesteśmy pewni, że posiadamy owo oprogramowanie możemy przystąpić do generowania klas z załącznika WSDL. Krokiem, który musimy wykonać jako pierwszy, jest odnalezienie lokalizacji pliku „wsimport.exe”. W moim przypadku znajdował się on w katalogu: C:\Program Files (x86)\Java\jdk1.8.0_05\bin.
Kiedy poznamy już lokalizacje swojego pliku, to możemy przystąpić do kolejnego kroku, którym jest uruchomienie wiersza poleceń (cmd). Dokonujemy tego przez opcje uruchom (skrót klawiszowy Windows+R), w której wpisujemy polecenie „cmd”.

 

 


Po uruchomieniu konsoli, za pomocą polecenia „cd” przechodzimy do katalogu, w którym znajduje się nasz plik „wsimport”.

 

 


Po wykonaniu tej czynności, możemy przystąpić do następnego kroku, którym jest generowanie klas. Dokonujemy tego poprzez wpisanie w konsoli polecenia:

wsimport <link/ ścieżka do wsdl> -Xnocompile -d <ścieżka zapisu wygenerowanych klas> -extension -keep -XadditionalHeaders -B-XautoNameResolution

 

 


Po wykonaniu wyżej wspomnianego wygenerowane klasy zostają wygenerowane i zapisane we wskazanym miejscu. Wyglądają one następująco:

 

 

3 Umieszczenie wygenerowanych klas w środowisku jDESIGNER™


Po wygenerowaniu klas należy umieścić je w jDesigner jako klasy Groovy. Każdą z nich umieszczamy w katalogu WebService, który utworzyliśmy podczas tworzenia struktury katalogów. Żeby tego dokonać, należy otworzyć wygenerowane klasy za pomocą jakiegoś edytora tekstu np. Notepad++. Wybieramy pliki, które w swojej nazwie zawierają rozszerzenie „*.java”.
Kiedy otworzymy już daną klasę w edytorze tekstu, klikamy prawym przyciskiem myszy na katalog WebServices i z listy wybieram Nowy->Klasa Groovy.

 

 


Po czym pojawi się okienku, w którym nadajemy nazwę tworzonej klasie. Nazwa nowo tworzonej klasy powinna być identyczna co klasy otworzonej w edytorze tekstu.

 

 


Po utworzeniu nowej klasy kopiujemy do niej, zawartość wygenerowanej klasy, którą mamy otwartą w edytorze tekstu.

 

 


Jak widać na powyższym przykładzie, należy dopilnować również, aby package był odpowiednio skonfigurowany zgodnie ze ścieżką naszego katalogu oraz dodajemy importy palio. Na koniec zapisujemy dany obiekt i w ten sam sposób tworzymy wszystkie pozostałe wygenerowane klasy. Po umieszczeniu w katalogu wszystkich klas, struktura katalogowa powinna wyglądać następująco:

 

 

 

4 Przekazywanie danych do klas


Po wykonaniu wyżej omówionych czynności w katalogu API Apaczki tworzymy stronę z obiektem Groovy o nazwie ControllerApaczka. Tworzymy ja w następujący sposób: klikamy prawym przyciskiem myszy na folder Apaczka, po czym wybieramy Nowy-> Strona z obiektem

 

 


Po czym pojawi nam się okienko w którym nadajemy im nazwę i wybieramy jakiego tupu ma być obiekt. W naszym przypadku tworzymy obiekt Groovy.

 

 


ControllerApaczka jest odpowiedzialny za komunikacje połączenie między użytkownikiem a tworzoną paczką. Funkcje umieszczone są odpowiedzialne za komunikacje naszego API ze stroną WWW. Dzięki, której będzie on pobierał od użytkownika i generował niezbędne dane. Po czym będzie przesyłał je do odpowiednich funkcji podczas ich wywoływania, w celu wygenerowania zamówienia przesyłki. Dodatkowo będą w nim znajdować się funkcje komunikujące się z naszym DAO, które omówiono w punkcie (5) oraz funkcje komunikujące się z obiektami XML, które omówiono w punkcie (6)

 

 

 

5 Tworzenie DAO $*api.apaczka.Dao.Country


Do składania zamówienia należy podać ID państwa, z którego będzie wysłana paczka, jak również państwa, do którego będzie wysyłana przesyłka. W tym celu zostanie utworzona w bazie danych tabela o nazwie apaczka_country. By tego dokonać, należy użyć następującego polecenia SQL korzytając z zakładaki SQL W jDESIGNER™:


CREATE TABLE apaczka_country(
ID NUMERIC (12) NOT NULL UNIQUE PRIMARY KEY AUTOINCREMENT,
country_cod VARCHAR(45) NOT NULL,
country_id NUMERIC (12) NOT NULL,
country_name VARCHAR(45) NOT NULL
);


Po jej utworzeniu następnym krokiem będzie wywołanie skryptu XML getCaoutry, który znajduje się w katalogu xml. Został on opisany w punkcie (6), który znajduje się poniżej.
Gdy uzyskamy odpowiedź ze skryptu, należy ją umieścić w utworzonej wcześniej tabeli. By tego dokonać należy użyć następującego polecenia SQL

 

INSERT INTO apaczka_country(id,country_cod, counttry_id,country_name) VALUES (1,"AF" ,3, "Afganistan")

 


Struktura tabeli apaczka_country powinna wyglądać następująco:

 

 


Kiedy już umieścimy całą odpowiedz w tabeli, możemy następnie przystąpić do utworzenia i skonfigurowania obiektu Country. W celu jego utworzenia postępujemy tak samo, jak to miało miejsce w przypadku poprzednio tworzonych obiektów Groovy.
Po jego utworzeniu przystępujemy do konfiguracji obiektu. Umieszczamy w nim zmienne, które przejmą dane pobrane za pomocą poleceń SQL. Jak również polecenia SQL, które będą nam się komunikować z bazą i pobierać dane z odpowiedniej tabeli.
Struktura obiektu powinna wyglądać następująco:

 

 

 

6 Tworzenie obiektów XML


Do celów komunikacji naszego API z serwisem Apaczka użyto skryptów XML, które mają na celu przesłanie danych za pomocą odpowiedniej składni w celu złożenia zamówienia.
W tym celu w katalogu xml zostały utworzone skrypty XML odpowiedzialne za złożenie zamówienia, do których kontroler za pomocą kontrolera zostają przesłane odpowiednie dane pozwalające na złożenie zamówienia.
By stworzyć obiekt ze skryptem XML, tworzymy nowy obiekt Groovy, który tworzymy w identyczny sposób, jak to miało miejsce powyżej (np. tworzenie obiektów wygenerowanych klas).
W katalogu xml tworzymy następujące obiekty:

6.1. Valuation $*api.apaczka.xml.Valuation

Skrypt służy do wyliczenia kosztów przesyłki przed złożeniem zamówieni.
Podczas jego wywołania przekazywane są do niego dane takie jak:

  • Id konka Apaczka,
  • Dane nadawcy i adresata paczki, do których należą: id państwa, kod pocztowy, nazwa miasta
  • dane przesyłki, do których należą: wymiary szerokości, wysokości i długości i wysokości paczki, waga paczki, cena wysyłanego zamówienia.

Poniżej ukazano wygląd klasy ze skryptem:

 

 


Po wysłaniu XML-a do serwisu Apaczki w odpowiedzi otrzymujemy odpowiedź o koszcie przesyłki w postaci XML. Odpowiedź ma następującą postać:

 

 

Koszt dostawy znajduje się w linii 41 i jest podany w groszach. Jeśli chcemy go pobrać do zmiennej i przekodować na postać zmiennoprzecinkową należy następującego polecenia:

this.value=Palio.toBigDecimal(XPath.getValue(xml2, "//Envelope/Body/calculatePriceResponse/return/order/netAmount"))/100


Powyższe polecenie pobiera z odpowiedzi dane w postaci tekstu, następnie rzutuje tekst na dane typu BigDecimal (liczba zmiennoprzecinkowa), a na koniec dzieli przez sto by przypisać do zmiennej wartość kwoty w PLN
Oczywiście należy pamiętać o zaimportowaniu biblioteki Xpath, ponieważ bez tego wyżej wypisane polecenie nie zadziała.

6.2. XmlAuthorization $*api.apaczka.xml.XmlAuthorization

Skrypt służy do potwierdzenia autoryzacji logowania się do konta Apaczka. Skrypt ten jest jedną z części większego skryptu, który posłuży do składania zamówienia wysyłki paczki.
Podczas jego wywołania przekazywane są do niego dane takie jak:

  • ApiKej – jest to indywidualny klucz dostępu dla integrowanego środowiska do serwisu Apaczka
  • Login i hasło – dane pozwalające na zalogowanie użytkownika do serwisu Apaczki

Poniżej ukazano wygląd klasy ze skryptem:

 

 

 

6.3. XmlOrder $*api.apaczka.xml.XmlOrder

Skrypt służący do przesyłania danych niezbędnych do złożenia zamówienia. Skrypt ten jest jedną z części większego skryptu, który posłuży do składania zamówienia wysyłki paczki.
Podczas jego wywołania przekazywane są do niego dane takie jak:

  • Adres nadawcy i odbiorcy przesyłki do których należą dane takie jak: Imię i nazwisko, adres ( ulica, numer domu/mieszkania, kod pocztowy, miasto, kraj),
  • dane kontaktowe do których należą:imię i nazwisko osoby do kontaktu, numer telefonu, email
  • Informacje, czy nadawca i odbiorca mają otrzymywać informacje w postaci email/sms o statusie przesyłki
  • Informacje o typie zamówienia kuriera, czy sami dostarczymy przesyłkę do centrali, w danym terminie ma się po nią zgłosić kurier
  • Typ zamawianej usługi kurierskiej

Budowa klasy przechowującej omawiany skrypt została przedstawiona poniżej:

 

 

 

6.4. XmlShipment $*api.apaczka.xml.XmlShipment

Skrypt służący do przesyłania zawierających dane wysyłanej paczki. Skrypt ten jest jedną z części większego skryptu, który posłuży do składania zamówienia wysyłki paczki.
Podczas jego wywołania przekazywane są do niego dane takie jak:

  • Wymiary wysyłanej paczki (długość x szerokość x wysokość)
  • Waga wysyłanej paczki
  • Cena wysyłanego w paczce zamówienia
  • Typ przesyłki (list, paczka lub paleta)

 

 

 

6.5. Connection $*api.apaczka.xml.Connection

Skrypt służący do połączenia w spójną i jednolitą całość wszystkich czterech skryptów opisanych powyżej (podpunkty 6.1-6.4). Budowa klasy przechowującej wspomniany skrypt została przedstawiona poniżej:

 

 

 

6.6. Fallow $*api.apaczka.xml.Follow

Skrypt służący do składania zamówienia na wysłanie przesyłki. Podczas jego wywołania przekazywany do niego jest zawartość skryptu Connection. Budowa klasy przechowującej wspomniany skrypt została przedstawiona poniżej:

 

 


Po wysłaniu XML-a do serwisu Apaczki w odpowiedzi otrzymujemy odpowiedź o złożeniu zamówienia w postaci XML. Odpowiedź wygląda następująco:

 

 

 

6.7. getCountry $*api.apaczka.xml.GetCountry

Skrypt służący do pobierania informacji o państwach, do których może zostać wysłana przesyłka. Budowa klasy przechowującej wspomniany skrypt została przedstawiona poniżej:

 

 


Po jego wywołaniu otrzymujemy odpowiedz w postaci XML, w której zawarte są informacje takie jak:

  • Nazwa państwa
  • Id państwa
  • kod państwa

Odpowiedź na wywołany skrypt ma następującą postać:

 

 


Skrypt XML getCountry będzie wykonywany tylko raz, a następnie uzyskaną odpowiedz umieszczamy w w tabeli <nazwa tabeli >. Dokładny opis umieszczenia odpowiedzi w bazie danych został opisany w punkcie (5). Natomiast pobranie interesujących nas danych możemy przeprowadzić za pomocą następujących poleceń:

// Pobranie kodu państwa
String code= XPath.getValue(xml2, "//Envelope/Body/getCountriesResponse/return/countries/Country/code")
// Pobranie id państwa
String id= XPath.getValue(xml2, "//Envelope/Body/getCountriesResponse/return/countries/Country/id")
// Pobranie nazwy państwa
String id= XPath.getValue(xml2, "//Envelope/Body/getCountriesResponse/return/countries/Country/name")
6.8. GetWaybillDocument $*api.apaczka.xml.GetWaybillDocument

Skrypt służy do pobrania listu przewozowego w postaci pliku pdf. Zostaje on wywołany po zakończeniu składania zamówienia i jako parametr otrzymuje id założonego zamówienia i dane autoryzujące nasze konto. Budowa klasy przechowującej wspomniany skrypt została przedstawiona poniżej:

 



Po wysłaniu skryptu do serwisu Apaczki w odpowiedzi otrzymujemy następującego XML-a:

 

 


W linii numer 8 otrzymujemy zawartość pliku PDFz listem przewozowym. Został on zakodowany w Base64. Żeby przeprowadzić dekodowanie należy przypisać zawartość odpowiedzi do zmiennej tekstowej. Możemy tego dokonać za pomocą polecenia:

String encodePdf= XPath.getValue(xml2, "//Envelope/Body/getWaybillDocumentResponse/return/waybillDocument")


Następnie zawartość zmiennej należy odkodować za pomocą polecenia:

String decodePdf = new String(encodePdf.decodeBase64(), "UTF-8")


W tym momencie możemy zapisać zdekodowany plik.

7 Tworzenie obiektu konfiguracyjnego $*api.apaczka.Config.Config


Integracje, które tworzymy, jest uniwersalną paczką API, które będzie można przekazać innym integratorom i podpiąć do dowolnego systemu. W tym celu został stworzony obiekt konfiguracyjny „Config”, który pozwoli na przyśpieszenie integracji naszej paczki w innych systemach sklepów internetowych. Dlatego zawarte zostały w nim dane konfiguracyjne, które są indywidualne dla każdego użytkownika serwisu Apaczka. Dzięki czemu przyszły Integrator utworzonej struktury Apaczka Webservice API, nie będzie musiał przeglądać wszystkich plików i zapoznawać się z działaniem każdej z funkcji umieszczonych w klasach. Wystarczy że poda odpowiednie dane w pliku konfiguracyjnym i będzie mógł od razu podpiąć API do swojego systemu.
By stworzyć obiekt config należy kliknąć prawym przyciskiem myszy na wcześniej przygotowanym katalogu Config, następnie wybieramy Nowy->obiekt.

 

 


Po czym pojawi się okienku, w którym nadajemy nazwę tworzonego obiektu.

 

 


W obiekcie config będą znajdować się niezbędne dane wymagane do połączenia paczki API z własnym systemem. Integrator będzie w nim podawał takie dane jak ApiKey, Login, Hasło i customerId, które są indywidualnymi danymi dla każdego z użytkowników serwisu Apaczka. Struktura obiekty konfiguracyjnego powinna wyglądać następująco:


 

Struktura katalogowa powinna wyglądać następująco:

 

 

 

8 Obiekt Readme $*api.apaczka.Install.readme


Pamiętając że naszą paczkę będzie mógł otrzymać każdy, kto będzie chciał dokonać integracji serwisu Apaczki z własną stroną. W tym celu ostatnim krokiem, który został wykonany jest utworzenie obiektu ReadMe w katalogu Install. By tego dokonać należy postąpić analogicznie jak przy tworzeniu obiektu Config, tylko w tym przypadku wybieramy katalog Install.
ReadMe jest integralną częścią naszej uniwersalnej paczki API, po której przeczytaniu integrator naszej paczki będzie wiedział jak ją przeprowadzić, ponieważ zostanie zapoznany z działaniem naszego API. Dlatego umieszczone w nim informację objaśniają zawartość i działanie:

  • wygenerowanych klas,
  • kontrolera,
  • obiektu config


Dodatkowo podane zostały w nim niezbędne informacje do poprawnej konfiguracji paczki API. Należeć do nich będą:

  • Linki do niezbędnych bibliotek i dokumentacji
  • Zastosowanie i użytkowanie API Apaczki
  • Objaśnienie pełnej konfiguracji obiektu Config
  • Objaśnienie możliwości testowania przygotowania paczki zanim w pełni zostanie podpięta do sklepu internetowego użytkownika.
  • Zasada działania i przygotowanie obiektów testowych, ponieważ serwis Apaczki niestety nie przygotował środowiska testowego. Co za tym idzie testów trzeba dokonać we własnym zakresie w części deweloperskiej- produkcyjnej serwisu.
  • Uwagi do działania systemu, które zostały zaobserwowane podczas przeprowadzania testów działania API.

Cała struktura katalogowa po utworzeniu całego API powinna wyglądać następująco:

 

 

 

Podsumowanie


W ten o to prosty sposób została stworzona struktura, która jest uniwersalną paczką API. Dzięki czemu Apaczka Webservice API może zostać zintegrowana z dowolnym systemem sklepu internetowego. Co ułatwi i znacznie przyśpieszy użytkownikom przyszłe integracje Apaczka Webservice API do własnych systemów, ponieważ zamiast budować całe API będą oni musieli wykonać kilka następujących kroków:

  • Zapoznać się z obiektem ReadMe, który wyjaśni im działanie paczki API
  • Skonfigurowanie do własnych potrzeb obiektu Config
  • Odpowiednio wywołać we własnym systemie odwołanie do klasy ControllerApaczka, co pozwoli na przekazanie danych niezbędnych do złożenia zamówienia.

 



Return