Obsługa Spedycja.net z poziomu aplikacji internetowej

Sklep internetowy przyjmuje zamówienie, a przesyłka kurierska ma powstać bez udziału człowieka. Do tego służy funkcja zapisana w pliku DLL, którą wywołuje aplikacja zewnętrzna. Biblioteka zapisuje paczki w bazie Spedycja.net i zwraca identyfikator zlecenia wysyłki.

Wywołanie funkcji z pliku DLL

Aplikacja internetowa nie zapisuje wierszy w bazie Spedycja.net samodzielnie. Wywołuje funkcję z biblioteki, która zawiera definicje klas i struktur wraz z wydrukami potrzebnymi do poprawnego zapisu. Klasa SpedytorLib.Dll wraz ze strukturami SpedytorLib.Dll* obsługuje całą wymianę danych, a gwiazdka oznacza nazwę konkretnej struktury wymaganej przy wywołaniu.

Plik DLL musi być dostępny na serwerze, na którym działa aplikacja wywołująca. Programista otrzymuje gotowe elementy zamiast projektować własne zapisy do bazy, więc integracja ogranicza się do wypełnienia struktur i odczytu wyniku. Starszy opis tej samej wymiany znajduje się na stronie o integracji ze spedycją.

Zamówienie ze sklepu jako zlecenie wysyłki

Najprostszy scenariusz zaczyna się w sklepie internetowym. Zamówienie jest opłacone i spakowane, a aplikacja sklepu tworzy zlecenie w Spedycja.net jednym wywołaniem funkcji. Wynik wraca w tej samej chwili, więc sklep wie, czy może uruchomić wydruk.

1. Klient składa zamówienie, a aplikacja zapisuje je we własnej bazie.
2. Aplikacja wypełnia strukturę danymi odbiorcy i paczki oraz wywołuje funkcję z biblioteki.
3. Biblioteka zapisuje zlecenie w bazie Spedycja.net i zwraca wynik razem z identyfikatorem zlecenia.
4. Aplikacja zapisuje identyfikator przy zamówieniu i wskazuje go przy wydruku.

Reguła: aplikacja nie zakłada, że wywołanie się powiodło. Najpierw odczytuje wynik, a dopiero potem zapisuje identyfikator przy zamówieniu i uruchamia wydruk. Etykieta dla zlecenia, którego nie ma w bazie, jest etykietą bez przesyłki.

Pola Odbiorca i Przewoźnik w dokumencie WZ pokazują, jakie dane towarzyszą wydaniu. Proces opisuje strona o wydaniu z magazynu, a zewnętrzne aplikacje opisują strony o aplikacji internetowej WMS i o programowaniu magazynowym.

Ponowienie wywołania bez duplikatu zlecenia

Sieć bywa zawodna. Jeśli odpowiedź nie dotrze do sklepu, aplikacja ponowi wywołanie, a w Spedycja.net powstaną dwa zlecenia dla jednego zamówienia. Ochronę trzeba zbudować po stronie aplikacji wywołującej, bo to ona zna numer zamówienia.

Poniższy przykład jest ilustracyjny i nie pokazuje kodu produktu. Tabela śladów wywołań ma klucz główny na numerze zamówienia, więc drugi zapis dla tego samego zamówienia kończy się błędem, zanim biblioteka zostanie wywołana po raz drugi.

CREATE TABLE dbo.ZleceniaSpedycjiSklepu (
    ZamowienieId          int         NOT NULL,
    IdentyfikatorZlecenia int         NULL,
    Status                varchar(10) NOT NULL DEFAULT 'W_TOKU',
    CONSTRAINT PK_ZleceniaSpedycjiSklepu PRIMARY KEY (ZamowienieId)
);

-- przed wywołaniem funkcji z biblioteki
INSERT INTO dbo.ZleceniaSpedycjiSklepu (ZamowienieId) VALUES (@ZamowienieId);

-- po poprawnym wyniku wywołania
UPDATE dbo.ZleceniaSpedycjiSklepu
SET IdentyfikatorZlecenia = @Id, Status = 'GOTOWE'
WHERE ZamowienieId = @ZamowienieId;

• Klucz główny. Tworzy indeks unikatowy, który odrzuca drugi wpis dla tego samego zamówienia. Budowę indeksów opisuje dokumentacja architektury indeksów SQL Server.
• Status W_TOKU. Wiersz bez identyfikatora oznacza próbę, która nie zakończyła się wynikiem, więc przed ponowieniem trzeba ją sprawdzić ręcznie albo zapytaniem kontrolnym.
• Identyfikator zlecenia. Zapisany przy zamówieniu pozwala wydrukować etykietę ponownie bez tworzenia nowego zlecenia.
• Status GOTOWE. Zamówienia z tym statusem pomija każda następna próba, więc wywołanie jest bezpieczne przy dowolnej liczbie powtórzeń.

Obsługa wyniku i błędów po stronie aplikacji

Funkcja zwraca wynik z informacją o powodzeniu zleconych zadań. Aplikacja wywołująca musi rozróżnić trzy sytuacje, bo każda wymaga innej reakcji. Rozróżnienie opiera się na wyniku wywołania i na śladzie zapisanym przed jego rozpoczęciem.

Ostatni wiersz jest najtrudniejszy. Przerwana odpowiedź nie dowodzi, że zlecenie nie powstało, bo biblioteka mogła zapisać dane tuż przed zerwaniem połączenia. Dlatego aplikacja najpierw szuka zlecenia po numerze zamówienia, a dopiero potem decyduje o ponowieniu.

Uprawnienia i miejsce wywołania

Funkcja działa w kontekście konta, na którym pracuje aplikacja internetowa. To konto musi mieć prawo zapisu w bazie Spedycja.net, a parametry połączenia nie powinny trafiać do kodu strony. Standardowym miejscem jest plik konfiguracyjny aplikacji, opisany na stronie o logowaniu do WMS i konfiguracji IIS.

Zakres uprawnień warto ograniczyć do operacji potrzebnych przy tworzeniu zleceń. Konto sklepu nie musi mieć dostępu do kartotek ani do dokumentów finansowych. Podział ról użytkowników opisuje strona o rolach i użytkownikach w systemie WMS.

Wywołanie w tle zamiast w żądaniu strony

Wywołanie funkcji w trakcie obsługi żądania HTTP wydłuża czas odpowiedzi sklepu. Gdy baza spedycyjna odpowiada wolno, klient czeka na potwierdzenie zamówienia. Lepszym układem jest zapis zamówienia, odpowiedź dla klienta, a dopiero potem wywołanie funkcji w osobnym zadaniu.

Ślad w tabeli aplikacji pełni wtedy rolę kolejki. Zadanie w tle wybiera wiersze o statusie W_TOKU. Dla każdego wywołuje funkcję, a potem zapisuje wynik. Przy awarii serwera zadanie wznawia pracę od pierwszego wiersza bez identyfikatora, więc żadne zamówienie nie zostaje pominięte.

Scenariusze testowe przed uruchomieniem

Integrację sprawdza się na kopii bazy, nigdy na danych produkcyjnych. Test powinien obejmować nie tylko ścieżkę, w której wszystko działa. Przerwane połączenie i powtórzone wywołanie ujawniają błędy, których nie widać przy pojedynczym zamówieniu.

• Zamówienie poprawne. Zlecenie powstaje, identyfikator zapisuje się przy zamówieniu, a wydruk dotyczy właściwej przesyłki.
• Dane niepełne. Wynik negatywny nie zostawia śladu ze statusem GOTOWE ani wydruku.
• Zerwane połączenie. Aplikacja sprawdza bazę przed ponowieniem i nie tworzy drugiego zlecenia.
• Powtórzone wywołanie. Drugi zapis dla tego samego zamówienia zostaje odrzucony przez klucz główny.

Wymiana danych a magazyn

Zlecenie wysyłki dotyczy towaru, który ktoś musi najpierw skompletować. Magazyn pracuje na własnej bazie, a Spedycja.net na własnej, więc jedna aplikacja obsługuje wydanie, a druga przesyłkę. Opis programu zawiera kilka cech, które łączą te dwa obszary.

Zasada FIFO wydaje najpierw towar przyjęty najwcześniej, a LIFO najpóźniej. Wybór zależy od asortymentu, bo towar z terminem ważności wymaga FIFO. Strony o programach magazynowych OnLine i o systemie WMS opisują całość funkcji. Integracja z ERP ogranicza ręczne wprowadzanie danych także po stronie wysyłki.

Rozdzielenie baz ma jeszcze jedną konsekwencję. Awaria jednej aplikacji nie zatrzymuje drugiej, więc magazyn może dalej przyjmować i wydawać towar, gdy moduł wysyłkowy jest niedostępny. Zlecenia czekają wtedy w kolejce aplikacji wywołującej i trafiają do Spedycja.net po przywróceniu działania. Taki układ wymaga jednak monitorowania kolejki, bo długa przerwa zostawia wiersze ze statusem W_TOKU, które ktoś musi zauważyć i wyjaśnić.

Urządzenia i automatyzacja przy wysyłce

Pakowanie kończy się skanem na terminalu, który potwierdza zebraną paczkę. Opis terminali zawiera strona o komputerach ręcznych Zebra TC5X. Jeśli magazyn używa przenośników lub robotów, zasady współpracy z systemem opisuje artykuł o automatyzacji w magazynie.

Wdrożenie obejmuje wybór wersji i konfigurację, a także szkolenie obsługi. Każdy magazyn ma inną specyfikę, dlatego konsultant musi znać branżę klienta, zanim dobierze zakres wymiany. Ogólny opis rozwiązania znajduje się na stronie aplikacji dla magazynów wysokiego składowania oraz na stronie producenta Studio WMS.net. Podstawową terminologię tego obszaru porządkuje słownik pojęć CSCMP.

Pytania i odpowiedzi o obsługę Spedycja.net z aplikacji internetowej

Glosariusz pojęć związanych z obsługą Spedycja.net

Plik DLL

Biblioteka dynamiczna z funkcjami, które wywołuje inna aplikacja. W tym przypadku zawiera funkcję tworzącą zlecenia w Spedycja.net.

SpedytorLib.Dll

Klasa obsługująca całą wymianę danych ze Spedycja.net, używana razem ze strukturami o nazwach SpedytorLib.Dll*.

Struktura danych

Zbiór pól przekazywany do funkcji, który opisuje odbiorcę i paczkę.

Zlecenie wysyłki

Zapis w bazie Spedycja.net opisujący przesyłkę do przygotowania. Każde zlecenie ma własny identyfikator.

Identyfikator zlecenia

Wartość zwracana przez funkcję, która wskazuje zlecenie przeznaczone do wydruku.

Klucz główny

Ograniczenie tabeli, które gwarantuje unikatowość wiersza i tworzy indeks wspierający wyszukiwanie.

FIFO

Zasada wydawania towaru, w której pierwszy przyjęty towar jest wydawany jako pierwszy.

LIFO

Zasada wydawania towaru, w której ostatni przyjęty towar jest wydawany jako pierwszy.

Warto przeczytać