Kolejka importu od agencji - komunikaty o zgłoszeniu i zwolnieniu towaru

Kolejka importu od agencji zbiera komunikaty o zgłoszeniu i zwolnieniu towaru, które zmieniają statusy celne partii. Na ekranie widać, co przyszło, w jakim kanale i z jakim wynikiem, a komunikat z błędem można ponowić po poprawieniu danych. Poprzedni ekran to zwolnienia i blokady, następny - terminy dozoru.

Nad listą są trzy filtry: Status przetwarzania, Kanał i Agencja celna, oraz przyciski Odśwież, Ponów wybrany komunikat, Symuluj komunikat agencji i Wczytaj komunikat z pliku (JSON). Kolumny listy to Odebrano, Kanał, Agencja celna, Komunikat, MRN lub numer, Przetworzono i Status. W ostatniej kolumnie ikona oka otwiera szczegóły komunikatu. Lista zawiera do 300 wierszy.

Do czego służy kolejka

Agencja celna prowadzi zgłoszenia celne, a program tylko odbiera ich wynik. Dwa rodzaje komunikatów zmieniają ewidencję: Zgłoszenie (przeniesienie partii ze statusu Pod dozorem na Zgłoszony) i Zwolnienie towaru (przeniesienie na Zwolniony). Każdy komunikat najpierw trafia do kolejki, a dopiero potem jest przetwarzany. Dzięki temu widać, co przyszło i z jakim skutkiem, także gdy przetwarzanie się nie udało.

Filtr Kanał rozróżnia komunikaty wysłane przez API, przez FTPS i wczytane jako plik. W bazie demonstracyjnej punkt przyjmujący komunikaty od agencji nie jest wdrożony, więc komunikaty powstają przez symulację i przez wczytanie pliku JSON w takim samym formacie, jakiego użyłaby agencja. Strona nie obiecuje więc automatycznego odbioru komunikatów u klientów. Szczegóły techniczne opisują strony dla wdrożeniowców, w tym komunikaty agencji.

Program prowadzi ewidencję magazynową i nie jest certyfikowanym modułem celnym. Zmiana statusu partii po przetworzeniu komunikatu oznacza, że ewidencja zapisała to, co przysłała agencja. Nie jest to zgłoszenie do urzędu.

Filtry i przyciski

Z kokpitu prowadzą na ten ekran dwa kafelki: Komunikaty z błędem importu otwierają go z filtrem Błąd, a Komunikaty oczekujące - z filtrem Oczekuje. Kafelki opisuje strona Kokpit dozoru celnego.

Lista komunikatów

Lista pokazuje do 300 wierszy. Do konkretnego komunikatu dojdziesz szybciej filtrem statusu niż przewijaniem całej kolejki.

Szczegóły komunikatu

Ikona oka otwiera kartę "Komunikat" z numerem dokumentu. Na karcie są agencja, kanał, rodzaj komunikatu, czas odebrania i status. Gdy komunikat zakończył się błędem, pojawia się pole "Błąd przetwarzania" z treścią błędu. Gdy status to Częściowy, to samo miejsce zajmuje pole "Uwagi przetwarzania", które wskazuje pominięte pozycje. Pod nim stoi podpowiedź, że po poprawieniu danych komunikat można ponowić.

Karta pokazuje dane nagłówkowe komunikatu, pole Błąd przetwarzania i podpowiedź o ponowieniu. Niżej widać treść komunikatu jako sformatowany JSON, którego nie można edytować. Na dole stoi hash treści SHA-256 w formie skrótu. Hash służy do rozpoznawania duplikatów i pozwala porównać dwa pliki, które wyglądają tak samo.

Treść komunikatu jest zapisana w kolejce dokładnie w takiej postaci, w jakiej przyszła. Nie edytujesz jej na karcie, a przycisk Ponów przetwarza ją jeszcze raz bez zmian. Poprawić można więc dane w programie, od których zależał błąd, np. kartotekę klienta, ale nie sam komunikat. Jeżeli błąd leży w treści, agencja musi przysłać poprawiony komunikat, a w demo wczytuje się poprawiony plik.

Statusy komunikatów

Status Częściowy powstaje w dwóch sytuacjach. Pierwsza: pozycja z komunikatu nie ma partii do dopasowania na dokumencie. Druga: partia, której pozycja dotyczy, jest zablokowana i zostaje bez zmian, bo komunikat agencji nie zdejmuje blokady. Pozostałe pozycje komunikatu zostają przetworzone.

Przetwarzanie w jednej transakcji

Błąd cofa całość. Komunikat jest przetwarzany w jednej transakcji. Jeśli którakolwiek pozycja albo kontrola zakończy się błędem, statusy partii nie zmieniają się w ogóle, a komunikat dostaje status Błąd.

Dzięki temu komunikat nie zostawia ewidencji w połowie zmienionej. Po naprawie przyczyny wystarczy go ponowić, a nie ma potrzeby cofać pojedynczych partii. Wyjątkiem od reguły jest status Częściowy, który nie jest błędem: pozycje, dla których partie się znalazły, zmieniają status, a pozostałe są wymienione w uwagach.

Komunikat Zgłoszenie dla dokumentu, którego rejestr nie zna, tworzy ten dokument ze statusem Zgłoszony i uwagą "Utworzony z importu komunikatu agencji.". Komunikat Zwolnienie towaru dla nieznanego dokumentu kończy się błędem, bo zwolnienia nie ma do czego przypisać.

Przy dopasowaniu pozycji program szuka klienta po NIP albo po identyfikatorze, indeksu w kartotece tego klienta i, jeśli komunikat go podaje, numeru kontenera. Zwolnienie towaru przenosi partie dokumentu ze statusu Pod dozorem albo Zgłoszony na Zwolniony.

Jeśli partie są w tym samym czasie zatwierdzane w dokumencie wydania, import czeka na zakończenie tej operacji. Po upływie czasu oczekiwania ekran zgłasza komunikat "Partie są właśnie zatwierdzane w wydaniu (blokada wiersza) - ponów komunikat za chwilę.". Wystarczy poczekać chwilę i użyć Ponów.

Duplikaty i hash treści

Przy odbiorze program liczy skrót SHA-256 z treści komunikatu. Gdy kolejka ma już komunikat o takim samym haszu, nowy jest duplikatem i nie zmienia stanu. Dotyczy to także pliku wczytanego drugi raz. Dwa komunikaty różniące się choćby jednym znakiem mają różne hashe, więc poprawiony plik nie zostanie potraktowany jak duplikat.

Plik do wczytania musi mieć rozszerzenie .json albo .txt, nie może przekraczać 200 kB i powinien być zapisany w kodowaniu UTF-8.

Pola komunikatu JSON

Komunikat jest obiektem JSON. Poniższa tabela opisuje pola; ten sam format przyjmują symulacja i wczytanie pliku.

Typowe błędy i ich naprawa

Praca z kolejką na co dzień

Rano zacznij od kokpitu. Kafelek Komunikaty z błędem importu mówi, czy któryś komunikat wymaga reakcji, a kafelek Komunikaty oczekujące - czy coś czeka na przetworzenie. Kliknięcie kafelka otwiera kolejkę z gotowym filtrem, więc nie trzeba go ustawiać ręcznie.

Komunikat z błędem czytaj w kolejności: pole Błąd przetwarzania, potem dane, od których błąd zależy. Błąd o indeksie albo kliencie naprawia się w kartotekach programu, a błąd o strukturze komunikatu wymaga nowego komunikatu od agencji. Dopiero po naprawie ma sens przycisk Ponów wybrany komunikat. Ponowienie bez zmiany danych da ten sam błąd i nic w ewidencji nie zepsuje, ponieważ nieudane przetwarzanie nie zmienia statusów partii.

Po komunikacie ze statusem Przetworzony sprawdź skutek na właściwym ekranie. Partie dokumentu mają nowy status w zwolnieniach i blokadach, a status dokumentu w rejestrze wynika ze statusów jego partii. Partie ze statusem Zwolniony pozwalają zatwierdzić WZC, o ile termin dozoru nie minął. Komunikat Częściowy zawsze przeczytaj do końca, bo mogą w nim stać partie zablokowane, które zwolnienie od agencji pominęło.

Symulacja komunikatu agencji

Przycisk Symuluj komunikat agencji otwiera okno z dwoma polami: Dokument celny i Rodzaj komunikatu. Rodzaj Zgłoszenie (MRN) przenosi partie dokumentu ze statusu Pod dozorem na Zgłoszony, a rodzaj Zwolnienie towaru - na Zwolniony. System buduje komunikat JSON z danych dokumentu i przetwarza go tak, jak komunikat odebrany od agencji, więc wynik jest widoczny w kolejce razem z hashem i statusem.

Okno ma dwa pola obowiązkowe: Dokument celny i Rodzaj komunikatu. Po zatwierdzeniu system buduje komunikat JSON z danych dokumentu i przetwarza go w kolejce. Symulacja zmienia statusy partii dokumentu, więc w ćwiczeniu okno tylko otwieramy i zamykamy bez zatwierdzania.

Symulacja zmienia dane demonstracyjne: partie dokumentu naprawdę zmienią status, a wpis w historii zostanie zapisany. Statusu nie da się cofnąć przyciskiem, a status Zwolniony i Unijny nie mają zmian wstecz, dlatego na zajęciach używaj symulacji tylko na dokumencie przewidzianym do pokazu i tylko wtedy, gdy prowadzący tak zdecyduje. Przyciski Symuluj zgłoszenie agencji i Symuluj zwolnienie towaru ma też rejestr dokumentów celnych przy dokumencie.