Integracja WAPRO z magazynem wysokiego składowania Studio WMS.net

Przy dużym asortymencie liczy się gdzie towar leży i z jaką partią, a nie sama ilość w magazynie. WAPRO Mag prowadzi ewidencję ilościowo-wartościową, a Studio WMS.net dokłada precyzyjną lokalizację oraz numery partii. Osobno prowadzi terminy przydatności. Strona opisuje podział ról obu systemów oraz techniczną stronę ich połączenia przez API.

Podział ról WAPRO Mag i Studio WMS.net

Systemy Asseco WAPRO ewidencjonują towar od strony księgowej. Studio WMS.net odpowiada za to, co dzieje się na regale: lokalizację i numer partii. Prowadzi też numery seryjne oraz daty produkcji i przydatności. Wymiana danych musi więc rozdzielać obie warstwy, a nie kopiować jedną do drugiej.

Historia obrotów magazynowych pozwala sprawdzić, kiedy i od kogo kartoteka została przyjęta oraz kiedy i dla kogo wydana. Widoczna jest też historia miejsc składowania. Dane mogą być wyświetlane jako lista albo grupowane według dowolnego kryterium, na przykład miesięcznie.

Architektura połączenia

Integracja opiera się na REST API albo na dedykowanym komponencie pośredniczącym, który tłumaczy bazę MSSQL systemu WAPRO na komunikaty zrozumiałe dla WMS. Model jest bezstanowy. Komunikacja jest dwukierunkowa i asynchroniczna, a kolejka zadań znajduje się po stronie integratora. Wyzwalaczem wymiany bywa zmiana statusu dokumentu w WAPRO albo harmonogram zadań.

Asynchroniczność oznacza, że terminal nie czeka na odpowiedź WAPRO w trakcie skanu. Operacja zapisuje się lokalnie, a wysyłka do ERP odbywa się z kolejki. Chwilowa niedostępność ERP nie wydłuża więc pracy magazyniera, a komunikaty zostają wysłane po powrocie łączności.

• Format danych. JSON w kodowaniu UTF-8, w niektórych wdrożeniach XML.
• Protokół. HTTPS z TLS w wersji 1.2 lub nowszej.
• Autoryzacja. Token Bearer w formacie JWT albo klucz API w nagłówku HTTP.
• Wyzwalacz. Zmiana statusu dokumentu w WAPRO albo zadanie z harmonogramu.

Reguła: jeżeli integracja nie korzysta z natywnego interfejsu API WAPRO, wystawia własną warstwę usługową w .NET Core, która komunikuje się z bazą przez procedury składowane. Takie rozwiązanie jest bezpieczniejsze niż bezpośrednie operacje na tabelach.

Synchronizacja kartotek z WAPRO

Zanim magazyn zacznie pracować, oba systemy muszą używać tych samych indeksów. Kierunek wymiany jest jednoznaczny: z WAPRO do WMS. Dodanie nowego towaru albo kontrahenta w WAPRO wywołuje komunikat do WMS, a wyzwalaczem bywa zmiana rekordu albo cykliczne zadanie. Punktem końcowym takiej wymiany jest zwykle metoda POST /api/products/sync.

W komunikacie przekazuje się indeks towarowy i kod EAN, a także nazwę i jednostki miary. Dochodzą waga oraz wymiary, które WMS wykorzystuje przy wyborze gniazda paletowego. Dane teleadresowe kontrahentów przesyła się osobno, bo zmieniają się rzadziej niż kartoteka towarowa.

Mapowanie obiektów WMS i WAPRO

Klucz powiązania rozstrzyga o tym, czy ponowne wywołanie utworzy nowy rekord, czy zaktualizuje istniejący. Kontrahenta synchronizuje się po NIP, a nie po nazwie, bo nazwa zmienia się częściej niż identyfikator podatkowy.

Przyjęcie i wydanie w obiegu WAPRO

Przyjęcie zaczyna się od zamówienia do dostawcy (ZD) albo dokumentu PZ w buforze. Do WMS trafia żądanie z danymi dostawy. Magazynier widzi awizo na terminalu i skanuje towar. Po zamknięciu dokumentu WMS odsyła do WAPRO faktycznie przyjęte ilości. Dokument w buforze zostaje wtedy zatwierdzony. Planowanie rampy opisuje strona o awizacji dostaw.

1. Zamówienie klienta. Handlowiec wystawia ZK w WAPRO.
2. Zlecenie wydania. Dokument trafia do WMS jako zlecenie do realizacji, a WMS blokuje towar w swojej bazie przez rezerwację lokacji.
3. Kompletacja. WMS prowadzi operatora według ścieżki zbiórki, a po spakowaniu paczki generuje etykietę kurierską.
4. Aktualizacja ERP. WMS przesyła komunikat o zakończeniu zbiórki, a WAPRO tworzy dokument WZ lub fakturę i zdejmuje stan.

Jeżeli ilość zebrana jest mniejsza od zamówionej, wartość shortage jest większa od zera. Integrator powinien wtedy wywołać w WAPRO procedurę korekty pozycji dokumentu przed wystawieniem faktury. Magazyn fizyczny wydaje się więc dokładnie tyle, ile zapisano w dokumencie sprzedaży.

Procedura składowana potwierdzenia wydania

Warstwa pośrednia zapisuje potwierdzenie we własnej tabeli, a dopiero stąd wysyła je do WAPRO. Poniższy przykład jest ilustracyjny i nie przedstawia schematu żadnego z systemów. Klucz główny chroni przed duplikatem, a blok TRY...CATCH pozwala bezpiecznie powtórzyć wywołanie po przerwie.

CREATE TABLE integracja.PotwierdzeniaWydan (
    NumerZK      nvarchar(30)  NOT NULL,
    Sku          nvarchar(40)  NOT NULL,
    IloscZebrana decimal(18,3) NOT NULL,
    Brak         decimal(18,3) NOT NULL DEFAULT 0,
    Status       varchar(12)   NOT NULL DEFAULT 'DO_WYSLANIA',
    PRIMARY KEY (NumerZK, Sku)
);
GO
CREATE PROCEDURE integracja.ZapiszPotwierdzenie
    @NumerZK nvarchar(30), @Sku nvarchar(40),
    @IloscZebrana decimal(18,3), @Brak decimal(18,3)
AS
BEGIN
    SET NOCOUNT ON;
    BEGIN TRY
        BEGIN TRAN;
        INSERT integracja.PotwierdzeniaWydan (NumerZK, Sku, IloscZebrana, Brak)
        VALUES (@NumerZK, @Sku, @IloscZebrana, @Brak);
        COMMIT;
    END TRY
    BEGIN CATCH
        IF @@TRANCOUNT > 0 ROLLBACK;
        IF ERROR_NUMBER() NOT IN (2627, 2601) THROW;  -- duplikat klucza: powtórzone wywołanie
    END CATCH
END;

Składnię opisują dokumentacje TRY...CATCH i CREATE PROCEDURE. Duplikat klucza jest pomijany, więc drugie wywołanie tego samego potwierdzenia nie zmienia danych, a inne błędy są zgłaszane dalej.

Błędy, ponowienia i uzgadnianie stanów

Błąd 400 wymaga poprawy danych, a nie ponowienia: powtórka komunikatu z błędnym kodem EAN zawsze da ten sam wynik. Ponawia się tylko błędy przejściowe, czyli odpowiedzi 5xx i 429.

Raz na dobę, na przykład o godzinie 02:00, warto wykonać pełne porównanie stanów. Zwraca ono listę różnic między ilością w WMS a ilością w ERP i wykrywa rozbieżności wynikające z ręcznych korekt w WAPRO. Stan faktyczny w magazynie wysokiego składowania opisuje strona o magazynie wysokiego składowania.

Bezpieczeństwo i dziennik

• Dziennik komunikatów. Każdy komunikat JSON zapisuje się w bazie integratora przez co najmniej 30 dni.
• Lista adresów IP. Dostęp mają tylko wybrane serwery WMS.
• Sekrety poza kodem. Klucze do API WAPRO i SoftwareStudio przechowuje się w zmiennych środowiskowych lub w magazynie kluczy.
• Ograniczanie tempa. Przy odpowiedzi 429 integrator zwalnia wysyłkę zamiast ponawiać ją natychmiast.

Co zmienia integracja dla handlowca i magazynu

Handlowiec w WAPRO widzi rzeczywisty stan, więc nie sprzeda towaru, którego fizycznie nie ma. Dokumenty WZ i PZ powstają same, w wyniku pracy magazynierów. WAPRO przechowuje dane finansowe, a WMS dane o numerach partii i datach ważności oraz o miejscach składowania.

Taki podział pozwala odtworzyć drogę partii od przyjęcia do wydania bez przeszukiwania dwóch systemów. Zasady opisuje strona o partiach produkcyjnych i datach ważności, a spis z natury w takim układzie opisuje strona o inwentaryzacji w magazynie.

Formularze, kody kreskowe i raporty

Formularze używane przy zakładaniu kartotek i rejestracji dokumentów można dopasować do firmy na dwa sposoby. Personalizacja podstawowa odbywa się w narzędziu administracyjnym: jest szybka, ale ma ograniczenia funkcjonalne. Personalizacja zaawansowana zmienia szablony prezentacji danych i wymaga znajomości szablonów HTM. Szczegóły opisuje strona o projektowaniu formularzy.

Kody kreskowe 1D lub 2D identyfikują pozycję i mogą pochodzić z bazy WF-mag WAPRO albo być prowadzone niezależnie w systemie magazynowym. Raporty prac magazynierów i zajętości miejsc składowania powstają w SQL Reporting Services, a dostęp przez przeglądarkę mają także klienci i partnerzy. Zasady opisuje strona o raportowaniu na serwerze SQL. Pracę z terminalami opisuje aplikacja WMS na Androida, a rozmieszczenie palet zarządzanie magazynem wysokiego składowania.

Pytania i odpowiedzi o integrację WAPRO z WMS

Glosariusz pojęć związanych z integracją WAPRO z WMS

WAPRO Mag

System Asseco WAPRO do ewidencji ilościowo-wartościowej magazynu, działający na bazie MSSQL.

REST API

Interfejs HTTP, w którym operacje na zasobach wykonuje się metodami GET, POST, PUT i PATCH, najczęściej z danymi w formacie JSON.

Token Bearer

Token przekazywany w nagłówku HTTP, który potwierdza uprawnienia klienta API.

Procedura składowana

Nazwany zestaw instrukcji T-SQL zapisany w bazie SQL Server. Integracja używa jej zamiast bezpośrednich operacji na tabelach.

ZD i ZK

Zamówienie dostawy do dostawcy oraz zamówienie od klienta, dokumenty źródłowe dla przyjęcia i wydania.

Ponowienie z rosnącym odstępem

Mechanizm exponential backoff, w którym kolejne próby wysyłki następują w coraz dłuższych odstępach.

Uzgadnianie stanów

Cykliczne porównanie ilości w WMS i w ERP w celu wykrycia rozbieżności po ręcznych korektach.

Dziennik audytowy

Zapis komunikatów integracyjnych w bazie integratora, przechowywany co najmniej 30 dni.

Stateless

Cecha interfejsu, w którym każde żądanie niesie komplet informacji, a serwer nie przechowuje stanu sesji między wywołaniami.

Warto przeczytać