Wysyłka przesyłek za pomocą API UPS – certyfikacja

Aby móc zautomatyzować wysyłkę paczek za pomocą API UPS trzeba wykonać kilka kroków oraz poznać proces wysyłania paczek.

Co potrzebujemy?

Aby móc wysłać paczkę za pomocą UPS będziemy (na różnych etapach) potrzebować następujące rzeczy:

  1. konto w UPS
  2. klucz do API
  3. klient SOAP (np. soapUI)
  4. pakiet integracyjny UPS 'Wysyłanie’ (Shipping_Pkg)
  5. znajomość języka programowania ;)
  6. poprawnie przeprowadzony proces certyfikacji

Konto w UPS, Klucz do API

Aby rozpocząć przygotowania, należy mieć założone konto w ups.com. Następnie przechodzimy na stronę https://www.ups.com/upsdeveloperkit?loc=pl_PL, gdzie można zamówić klucz. Jest to dobre miejsce, gdyż są w nim umieszczone praktycznie wszystkie informacje nam potrzebne. Problem w tym, że ciężko trafić na wyżej wymienioną stronę.

Dostęp produkcyjny

Domyślnie, UPS daje dostęp „produkcyjny” do kilku modułów. Pozostałe (związane z fizyczną wysyłką) są w trybie testowym. Oznacza to, że możemy próbnie przechodzić cały proces wysyłki, ale nie zostanie ona wysłana. Należy skierować swoją aplikację na url’e zaczynające sięod wwwcie (Customer Integration Environment). W przypadku, gdy spróbujemy za pomocą klucza uzyskać dostęp do wersji produkcyjnej (live) uzyskamy komunikat o braku dostępu.

Pakiet integracyjny UPS 'Wysyłanie’ (Shipping_Pkg)

Zakładam, że interesuje nas wysyłka paczki. W tym celu musimy pobrać pliki do interfejsu 'Przesyłanie’. Spakowane archiwum jest dostępne na wcześniej podanej stronie. Zawiera ono pliki pdf oraz przykładowe kawałki kodu oraz pliki wsdl.
Dostęp do wysyłki jest w trybie testowym – aby móc wysyłać paczki musimy przejść proces certyfikacji.

Po pobraniu plików pdf odkryjemy, że proces wysyłania paczki został podzielony na dwa etapy:

  • przesłanie danych o paczce i potwierdzenie dostępności usługi (confirmRequest)
  • potwierdzenie danych o paczce (acceptRequest)

Jako odpowiedź na confirmRequest uzyskamy confirmResponce, który (o ile wszystko jest ok) będzie zawierał element Digest. Musimy pobrać ten element, a następnie przekazać go do acceptRequest. W odpowiedzi na niego otrzymamy acceptResponse, który będzie zawierał numer paczki oraz list przewozowy

Rozpoczynamy

Komunikacja między klientem a serwerem odbywa się z wykorzystaniem plików xml, których poszczególne (jak się okazuje – nie wszystkie) pola są opisane w dokumentacji.
Aby zacząć bawić się w dowolnym języku programowania najlepiej jest na początku „rozpoznać wroga”, czyli pobawić się różnymi parametrami.

Bardzo dobrym pomysłem jest ściągnięcie klienta pozwalającego na preparowanie i wysyłanie requestów na żywo. Dobrym (choć posiadającym pewne wady) narzędziem jest soapUI (wersja bezpłatna jest do ściągnięcia na sourceforge).
Zakładając, że mamy już pliki związane z pakietem programistycznym Shipping_Pkg odpalamy soapUI. Wybieramy w menu File->New soapUI Project. Jako nazwę możemy wpisać dowolny ciąg znaków. Ważne jest wybranie odpowiedniego pliku jako 'Initial WSDL file’. Należy wskazać „Shipping PACKAGE/PACKAGE Web Services/SCHEMA-WSDLs/ship.wsdl” z wypakowanego pliku Shipping_Pkg. Bardzo dobry pomysłem jest zaznaczenie 'Create sample request for all operations’. Po kliknięciu OK powinniśmy ujrzeć podobny widok:

Klikamy dwukrotnie na Request 1 w processShipConfirm. Zobaczymy nowe okno, w którym ujrzymy komplet danych wysyłanych do UPS.
Jest to jeden z cięższych etapów, dlatego dla szybkiego startu przygotowałem przykładowy plik xml, który (po podmianie [Username] – 3 razy, [Passowrd] oraz [AccessLicenseNumber]) powinien wyprodukować poprawną odpowiedź. Jest to wysyłka paczki o wymiarach 1x1x1cm, wadze 1kg pod kod pocztowy miasta Gliwice i zakładający, że płacącym za paczkę jest ta sama osoba, która wysyła zgłoszenie.

Chciałbym na tym etapie zwrócić uwagę na fakt, że soapUI nie zawsze robi to, czego chcemy. Czasami wysyła on jeszcze raz starą treść xml’a pomimo, że ma podaną nową. Zdarzyło mu się także sypać dziwnymi błędami podczas otwierania plików wsdl – rozwiązaniem było przeniesienie plików nieco wyżej (krótsza ścieżka) i część problemów ustało.

Certyfikacja

Uzyskanie certyfikatu zgodnie ze specyfikacją wymaga wygenerowania 39 plików i przesłania ich do weryfikacji. 39 brzmi być może jako ogromna liczba, ale w rzeczywistości nie jest tak źle. Musimy:

  • wysłać 5 paczek i zapisać sobie wygenerowane w trakcie tego xmle (request) jak i odpowiedzi (reponse). Dla confirmRequest, confirmResponse, acceptRequest i acceptResponse daje to nam 4*5 = 20 plików
  • wygenerować obrazy etykiet oraz wynikowych plików html. Obraz etykiety jest dostępny w xmlu jako graphicImage. Jest to plik gif (pod warunkiem, że zażyczyliśmy sobie taki) zapisany jako base64. Razem z nim jest jeszcze HTMLImage, który zawiera plik html (też base64) zawierający w sobie element <img src> wskazujący na plik graficzny. Należy tutaj zadbać, aby zapisać plik gif z odpowiednią nazwą (label<numer_listu>.gif). Te 2 pliki są także wymagane do procesu weryfikacji. 2 * 5 = 10. Mamy już 30 plików.
  • należy anulować 4 z podanych w pliku pdf przesyłek. Można to zrobić albo z poziomu napisanej przez siebie aplikacji albo wygenerować odpowiednie xml’e za pomocą soapUI :). Numery listów przewozowych są podane w pliku pdf i tylko je należy anulować. Należy oczywiście zapisać request jak i response. Daje to nam 2*4 = 8 plików, czyli mamy już 38.
  • plik High Value Report (o nim poniżej) – łącznie 39 plików.

Tak przygotowane pliki wysyłamy na podanego w pdfi’e maila. Warto pisać po angielsku, gdyż z reguły jest to centrala w USA. Jest nawet zaleta tej lokalizacji  – z powodu różnicy czasu oni pracują, gdy my śpimy – wysyłamy zatem maila wieczorem, a rano jest już odpowiedź.

Gdy wszystko będzie ok, sprawdzamy po 2 dniach status klucza i cieszymy się z udanego procesu integracji. Oczywiście, w międzyczasie trzeba jeszcze trochę programowania.

High Value Report

High Value Report muszę poświęcić osobny akapit. Wynika to z faktu, iż UPS ma pewną nieścisłość w dokumentacji oraz w plikach wsdl i xsd. Jeżeli wyślemy paczkę jako taką z zadeklarowaną wartością (ubezpieczeniem) powyżej 999$ automatycznie generuje się ten raport. Okazuje się jednak, iż deklarację należy przeprowadzić pod następującym xPath:
/ShipmentConfirmRequest/Shipment/Package/PackageServiceOptions/DeclaredValue:
<v11:DeclaredValue>
<v11:Type>
<v11:Code>01</v11:Code>
</v11:Type>
<v11:CurrencyCode>PLN</v11:CurrencyCode>
<v11:MonetaryValue>100000</v11:MonetaryValue>
</v11:DeclaredValue>
Dokumentacja mówi o InsuredValue zamiast DeclaredValue.

Po zadeklarowaniu odpowiedniej wartości w odpowiedzi acceptRequest uzyskamy jeszcze jedną wartość – /ShipmentAcceptResponse/ShipmentResults/ControlLogReceipt/GraphicImage. Będzie ona także zapisana jako Base64. Po zdekodowaniu należy wysłać ten plik jako część całego pakietu.

Podsumowanie

Po uzyskaniu certyfikatu należy zmienić url, pod jaki wysyłane są requesty. Zamiast wwwcie.ups… wstawiamy onlinetools.ups…