Spis treści DOKUMENTACJA TECHNICZNA. STS API wersja 1.1
-
Wanda Jabłońska 4 lat temu Przeglądów:
1 Spis treści 1. Korzystanie z interfejsu STS API Warunki korzystania z interfejsu Zabezpieczenia interfejsu Specyfikacja interfejsu STS API Proces składania zamówienia za pośrednictwem STS API Opis metod Przeprowadzenie integracji w środowisku produkcyjnym Dodatek Lista zmian Lista dostępnych przewoźników Lista rodzajów opakowania. 14
2 1. Korzystanie z interfejsu STS API Współpraca z interfejsem udostępnionym przez platformę odbywa się za pośrednictwem protokołu SOAP w wersji 1.1 z kodowaniem znaków UTF-8. Zabezpieczenia przesyłanych danych opierają się na weryfikacji danych klienta poprzez, wpierw, logowanie klienta do interfejsu API, następnie przekazywanie klucza API oraz klucza sesji otrzymanego podczas procedury logowania. Proces logowania oraz sposób autoryzacji klienta zostanie opisany w dalszej części dokumentacji. 1.1 Warunki korzystania z interfejsu Dostęp do interfejsu może być wykorzystywany tylko przez podmiot, który zaakceptował Regulamin korzystania z usług STS Kurier dostępny na stronie oraz zarejestrował się i uzyskał indywidualne dane logowania w procesie rejestracji. Przekazywanie danych dostępowych do interfejsu STS API traktowane jest jako nadużycie ze skutkiem zablokowanie dostępu do interfejsu STS API. 1.2 Zabezpieczenia interfejsu Każdorazowo rozpoczynając pracę z interfejsem STS API należy wywołać metodę login, przekazując jako parametr login i hasło ustawiony w procesie rejestracji, oraz otrzymany klucz API. W odpowiedzi zwrotnej otrzymają Państwo identyfikator aktualnej sesji. Wywołując metody udostępnione w ramach interfejsu STS API, w celu autoryzacji należy przekazać jako dodatkowy parametr identyfikator sesji otrzymany w procesie logowania.
3 2. Specyfikacja interfejsu STS API Interfejs STS API posiada dwa rodzaje metod; kluczowe do przeprowadzenia procesu zamówienia i otrzymania etykiet, oraz operacje pomocnicze, które wspomagają klienta podczas procesu składania zamówień. Jest to np. wycena przesyłki, sprawdzenie godziny podjazdu kuriera po przesyłkę. Wszystkie dostępne operacje zostały opisane w dalszej części tego rozdziału. 2.1 Proces składania zamówienia za pośrednictwem STS API Przebieg składania zamówienia zamówienia za pośrednictwem interfejsu STS API składa się z następujących etapów: 1. Logowanie do systemu STS (metoda login) 2. Pobranie ofert przewoźników dla zadanych gabarytów przesyłki (metoda getoffers niewymagane) 3. Wycena przesyłki dla wybranego przewoźnika i gabarytów przesyłki (metoda rateshipment niewymagane) 4. Pobranie dostępnych terminów odbioru przesyłki dla wybranego przewoźnika (metoda getpickupdate) 5. W przypadku Paczkomatów pobranie paczkomatu: nadawcy, odbiorcy, alternatywnego paczkomatu odbiorcy (metoda getinpostmachines) 6. Sprawdzenie poprawności danych zamówienia (metoda validateshipment niewymagane) 7. Złożenie zamówienia i zapisanie zwróconych etykiet (metoda processshipment) 2.2 Opis metod AuthenticationReply login (string apilogin, string apipassword, string apikey) string apilogin – Login użytkownika string apipassword – Hasło użytkownika string apikey – Klucz API AuthenticationReply wynik_logowania obiekt typu AuthenticationReply
4 AuthenticationReply $code $notifications $sessionid integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu string Identyfikator sesji, jeśli powodzenie OfferReply rateshipment (RateRequest shipmenttoevaluate, string apikey, string sessionid) RateRequest shipmenttoevaluate – Dane zamówienia przesyłki
5 RateRequest $service Service Dane usługi $shipper $packaging string Nazwa przewoźnika string Nazwa opakowania $packages $packageserviceoptions $sender Package[] Tablica danych przesyłek $weight integer Waga przesyłki $length integer Długość przesyłki $height integer Wysokość przesyłki $width integer Szerokość przesyłki $shape integer Kształt przesyłki, 1 – sześcian, 2 – owalny, 3 – inny $packaging integer Opakowanie przesyłki, 1 – karton, 2 – folia, 3 – inne $packagevalue float Wartość przesyłki PackageServiceOptions Usługi dodatkowe $insurance float Wartość ubezpieczenia przesyłki $COD float Wartość pobrania $description string Zawartość przesyłki $remarks string Uwagi Party Dane nadawcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj
6 $recipient Party Dane odbiorcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj OfferReply wycena_przesyłki obiekt typu OfferReply OfferReply $code $notifications integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu $offer Offer Oferta $service $pricenetto $pricebrutto Service $shipper $packaging float cena netto float cena brutto string Nazwa przewoźnika string Nazwa opakowania OffersReply getoffers (OfferRequest offerrequest, string apikey, string sessionid) OfferRequest offerrequest – Dane do wyceny OfferRequest
7 $service Service Dane usługi $shipper $packaging string Nazwa przewoźnika Wartość NONE string Nazwa opakowania $packages $packageserviceoptions Party $sender Package[] tablica danych przesyłek $weight integer Waga przesyłki $length integer Długość przesyłki $height integer Wysokość przesyłki $width integer Szerokość przesyłki $shape integer Kształt przesyłki, 1 – sześcian, 2 – owalny, 3 – inny $packaging integer Opakowanie przesyłki, 1 – karton, 2 – folia, 3 – inne $packagevalue float Wartość przesyłki PackageServiceOptions Usługi dodatkowe $insurance float Wartość ubezpieczenia przesyłki $COD float Wartość pobrania $description string Zawartość przesyłki $remarks string Uwagi Party Dane nadawcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj
8 Party $recipient Party Dane odbiorcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj OffersReply oferty – Odpowiedź z cenami OffersReply $code $notifications integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu $offer Offer[] Tablica ofert $service $pricenetto $pricebrutto Service $shipper $packaging float cena netto float cena brutto string Nazwa przewoźnika string Nazwa opakowania ShipmentReply processshipment (ShipmentRequest shipment, string apikey, string sessionid) ShipmentRequest shipment – Dane zamówienia przesyłki
9 ShipmentRequest $pickupdate PickupDateInfo Data i godzina odbioru przesyłki. $pickupdate string Data nadania przesyłki, format YYYY-MM-DD $readytime string Godzina od której przesyłka jest gotowa do odbioru HH:MM $closetime string Godzina do której przesyłka jest gotowa do odbioru HH:MM $service Service Dane usługi $shipper $packaging string Nazwa przewoźnika string Nazwa opakowania $packages $packageserviceoptions $inpostmachines $sender Package[] Tablica danych przesyłek $weight integer Waga przesyłki $length integer Długość przesyłki $height integer Wysokość przesyłki $width integer Szerokość przesyłki $shape integer Kształt przesyłki, 1 – sześcian, 2 – owalny, 3 – inny $packaging integer Opakowanie przesyłki, 1 – karton, 2 – folia, 3 – inne $packagevalue float Wartość przesyłki PackageServiceOptions Usługi dodatkowe $insurance float Wartość ubezpieczenia przesyłki $COD float Wartość pobrania $description string Zawartość przesyłki $remarks string Uwagi InpostMachines Dane dla paczkomatów (tylko w przypadku Paczkomatów) $sendermachine string Kod paczkomatu nadawcy $recipientmachine string Kod paczkomatu odbiorcy $alternativerecipientmachine string Alternatywny kod paczkomatu odbiorcy Party Dane nadawcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj
10 $recipient Party Dane odbiorcy $contact Contact Dane kontaktowe $companyname string Nazwa $personname string Osoba kontaktowa $phonenumber string Telefon $ address string Adres $address Address Dane adresowe $street $postalcode $city $stateorprovincecode $country string[] Tablica z danymi ulicy, numer domu, numer mieszkania string Kod pocztowy string Miasto string Prowincja / stan string Kraj ShipmentReply dane Tablica błędów w przypadku niepowodzenia, lub tablica z etykietami ShipmentReply $code $notifications $ordernumber $labels integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu integer Numer zamówienia, jeśli powodzenie string[] Zakodowane etykiety base64; ShipmentReply validateshipment (ShipmentRequest shipment, string apikey, string sessionid) ShipmentRequest shipment – Dane zamówienia przesyłki ShipmentReply dane Tablica z listą błędów podczas walidacji przesyłki PickupReply getpickupdate(string shipper, Address pickupaddress, Address deliveryaddress, string apikey, string sessionid)
11 string shipper – Identyfikator przewoźnika Address pickupaddress – Adres odbioru przesyłki Address deliveryaddress – Adres dostawy przesylki PickupReply godziny_podjazdu Tablica z listą błędów w przypadku niepowodzenia, lub tablica z listą dat i godzin od, do oraz minimalnym rozmiarem okienka czasowego. PickupReply $code $notifications $dates integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu array Tablica z datami i godzinami odbioru przesyłki przez kuriera PrepaidAccountReply getprepaidaccount(string apikey, string sessionid) PrepaidAccountReply stan_konta Tablica z listą błędów w przypadku niepowodzenia, lub stan konta prepaid. PrepaidAccountReply $code $notifications $account integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu float Stan konta prepaid InpostMachinesReply getinpostmachines(inpostmachinesrequest machinesrequest, string apikey, string sessionid) Opis: Pobranie listy paczkomatów nadawcy, odbiorcy, oraz paczkomatu alternatywnego odbiorcy,
12 zwracana lista paczkomatów realizujących, lub nie, usługę pobrania, zwracana informacja jest w postacie tablicy string[], każdy z elementów zawiera gotowy kod HTML do wstawienia w pole SELECT formularza na stronie. InpostMachinesRequest machinesrequest – Dane do zlokalizowania paczkomatu InpostMachinesRequest $senderpostalcode $recipientpostalcode $cod string Kod pocztowy nadawcy format LL-LLL string Kod pocztowy odbiorcy format LL-LLL boolean Czy paczkomaty obsługujące wpłaty – usługa pobrania InpostMachinesReply machinesreply Tablica z listą błędów w przypadku niepowodzenia, lub obiekt z danymi identyfikującymi paczkomaty. InpostMachinesReply $code $notifications $machines integer Identyfikuje sukces / błąd. 1 sukces, 0 – błąd Notification[] Tablica komunikatów $errorcode integer Kod błędu $message string Komunikat błędu InpostMachines Obiekt z danymi maszyn ShipmentReply getshippinglabels(integer stsnumber, string apikey, string sessionid) Opis: Pobranie etykiet dla zamówienia. Etykiety zwracane są jako plik PDF, zakodowane algorytmem base64. integer stsnumber Numer zamówienia w systemie STS ShipmentReply dane Tablica błędów w przypadku niepowodzenia, lub tablica z etykietami
13 2.3 Przeprowadzenie integracji w środowisku produkcyjnym Aby dokonać testowania integracji z interfejsem STS API na środowisku produkcyjnym należy w Strefie klienta zaznaczyć opcję tryb testowy, w sekcji STS API. Tryb testowy pozwala na składanie zamówień bez pomniejszania środków na koncie klienta. Zamówienia nie będą przekazywane przewoźnikowi, nie będzie także zwracana etykieta. Pozostałe funkcjonalności zostają zachowane.
14 3. Dodatek 3.1 Lista zmian Data Dokumentacja STS API w wersji Dodany interfejs getprepaidaccount Dodana obsługa Paczkomatów – Dodany interfejs getinpostmachines Dodany interfejs getshippinglabels Zmiany 3.2 Lista dostępnych przewoźników Identyfikator API OPEK UPS_STANDARD KEX RABEN UPS_EXPRESS_SAVER DPD FEDEX_ECONOMY FEDEX_PRIORITY PACZKOMATY Nazwa kuriera / usługi Opek UPS Standard K-EX Raben UPS Express Saver DPD FedEx Economy FedEx Priority Inpost Paczkomaty 3.3 Lista rodzajów opakowania Identyfikator API PACZKA KOPERTA PALETA Paczka Koperta Paleta Nazwa opakowania
