Import komunikatów od agencji celnej w Studio WMS.net działa tak, że każdy komunikat o zgłoszeniu albo zwolnieniu towaru najpierw trafia do kolejki importu, a dopiero potem jest przetwarzany. Wynik jest jedną transakcją: komunikat zmienia statusy partii w całości albo wcale. Duplikat rozpoznaje skrót SHA-256 treści. Moduł Dozór celny to ewidencja, a nie system celny.
Agencja celna prowadzi zgłoszenia poza programem, a moduł tylko odbiera ich wynik. Moduł Dozór celny jest dostępny w środowisku demonstracyjnym platformy StudioSystem ST 26, a wdrożenie następuje po uzgodnieniu zakresu; nie jest to produkt wdrożony u klientów. Przegląd całego modułu daje strona o module dozoru celnego.
Komunikat od agencji najpierw trafia do kolejki
Dwa rodzaje komunikatów zmieniają ewidencję. Zgłoszenie przenosi partie dokumentu ze statusu Pod dozorem na Zgłoszony, a Zwolnienie towaru - ze statusu Pod dozorem albo Zgłoszony na Zwolniony. Każdy komunikat zostaje w kolejce także wtedy, gdy przetwarzanie się nie udało, więc widać, co przyszło i z jakim skutkiem.
Kolejka rozróżnia trzy kanały: API, FTPS i plik. W środowisku demonstracyjnym nie ma punktu API przyjmującego komunikaty od agencji, więc komunikaty powstają przez symulację i przez wczytanie pliku JSON w takim samym formacie, jakiego użyłaby agencja. Strona nie obiecuje automatycznego odbioru komunikatów ani integracji z konkretną agencją.
Schemat pokazuje kolejność. Najpierw program liczy hash treści i sprawdza, czy taki komunikat już jest. Potem kontroluje strukturę i dopasowuje dane do kartotek, a na końcu zapisuje zmiany statusów w jednej transakcji z jednym z trzech wyników: Przetworzony, Częściowy albo Błąd.
Zmiana statusu po przetworzeniu oznacza, że ewidencja zapisała to, co przysłała agencja. To nie jest zgłoszenie do urzędu, a status partii opisuje strona o statusach celnych partii.
Hash SHA-256 rozpoznaje duplikaty
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. Kontrola duplikatów po haszu różni się od kontroli po numerze dokumentu, którą opisuje strona o elektronicznej wymianie dokumentów. Wzorzec zapisu w T-SQL, z hashem i unikalnym indeksem, pokazuje artykuł o imporcie JSON z hashem SHA-256.
Jedna transakcja daje trzy wyniki, a 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. Komunikat nie zostawia więc ewidencji w połowie zmienionej, a po naprawie przyczyny wystarczy go ponowić.
| Kod | Status | Znaczenie | Co robić |
|---|---|---|---|
| 0 | Oczekuje | komunikat jest w kolejce i nie został jeszcze przetworzony | otworzyć szczegóły; komunikat można przetworzyć przyciskiem Ponów wybrany komunikat |
| 1 | Przetworzony | komunikat zmienił statusy partii i zapisał wpis w historii ze źródłem IMPORT | nic; przycisk Ponów nie działa dla tego statusu |
| 2 | Błąd | przetwarzanie się nie udało, wszystkie zmiany zostały cofnięte | przeczytać pole Błąd przetwarzania, a po poprawie danych ponowić |
| 3 | Częściowy | część pozycji zmieniła status, a część pominięto | przeczytać pole Uwagi przetwarzania i zdecydować, czy poprawić brakujące pozycje |
Reguła importu. Błąd w jednej pozycji cofa cały komunikat, a status Częściowy nie jest błędem: pozycje z partiami zmieniają status, a pominięte są wymienione w uwagach.
Status Częściowy powstaje w dwóch sytuacjach: pozycja z komunikatu nie ma partii do dopasowania na dokumencie albo partia jest zablokowana i zostaje bez zmian, bo komunikat agencji nie zdejmuje blokady. 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ć.
Pola komunikatu i dopasowanie do kartotek
Komunikat jest obiektem JSON, a ten sam format przyjmują symulacja i wczytanie pliku. Tabela opisuje pola; przykłady są wymyślone.
| Pole | Znaczenie | Przykład (wymyślony) |
|---|---|---|
| typKomunikatu | ZGLOSZENIE albo ZWOLNIENIE; inna wartość kończy się błędem | ZWOLNIENIE |
| typDokumentu | jeden z trzech typów dokumentu celnego: T1, DSK albo MRN | MRN |
| mrn | numer dokumentu celnego; brak numeru kończy się błędem | 26PLEXAMPLE000001A |
| klientNip | NIP klienta, do którego należy towar; gdy komunikat go nie zawiera, używany jest identyfikator klienta | 1234567890 |
| agencjaNip | opcjonalny NIP agencji, do wskazania agencji | 0987654321 |
| kodProcedury | kod procedury celnej, na przykład 71 | 71 |
| dataZwolnienia | data w formacie ISO 8601, wymagana dla komunikatu ZWOLNIENIE | 2026-10-17T09:42:00+02:00 |
| pozycje | lista pozycji: lp, indeks, ilosc, jm, masaBruttoKg i opcjonalnie nrKontenera | lp 1, indeks ART-A, ilosc 120, jm SZT |
Przy dopasowaniu program szuka klienta po NIP, a gdy komunikat NIP nie zawiera - po identyfikatorze klienta. Potem sprawdza indeks w kartotece tego klienta i, jeśli komunikat go podaje, numer kontenera. Ogólny opis kartotek daje strona o kartotekach w systemie WMS. Błąd o kliencie albo indeksie naprawia się w kartotekach programu, a błąd o strukturze komunikatu wymaga nowego komunikatu od agencji.
Błędy po stronie danych i sposób naprawy
Pole Błąd przetwarzania na karcie komunikatu podaje przyczynę słowami. Przy innych statusach to samo miejsce nazywa się Uwagi przetwarzania. Treść komunikatu jest zapisana w kolejce dokładnie tak, jak przyszła, i nie da się jej edytować, a przycisk Ponów wybrany komunikat przetwarza ją jeszcze raz bez zmian.
| Co widać w polu błędu | Przyczyna | Co poprawić |
|---|---|---|
| zła struktura komunikatu | treść nie jest poprawnym obiektem JSON | agencja przysyła poprawny komunikat; w demo wczytuje się poprawiony plik |
| nieprawidłowy typ komunikatu albo dokumentu | wartość spoza dozwolonych | poprawiony komunikat; ponowienie nie pomoże, bo treść jest ta sama |
| brak numeru dokumentu | komunikat nie ma pola z numerem | poprawiony komunikat |
| zwolnienie bez daty zwolnienia | komunikat ZWOLNIENIE nie ma daty | poprawiony komunikat |
| nieznany klient | żaden klient nie ma podanego NIP ani identyfikatora | uzupełnić NIP w kartotece klienta i ponowić |
| indeks spoza kartoteki klienta | indeks z komunikatu nie należy do kartoteki tego klienta | dodać indeks do kartoteki albo poprawić komunikat, potem ponowić |
| nieznany dokument przy zwolnieniu | rejestr nie zawiera dokumentu, a zwolnienie go nie tworzy | dodać dokument w rejestrze albo najpierw przetworzyć komunikat Zgłoszenie |
Karta komunikatu podpowiada, że po uzupełnieniu kartoteki można użyć przycisku Ponów wybrany komunikat, a ponowienie korzysta z zapisanej treści, więc agencja nie musi wysyłać komunikatu drugi raz. Ponowienie bez zmiany danych da ten sam błąd, ale niczego w ewidencji nie zepsuje, bo nieudane przetwarzanie nie zmienia statusów partii.
Symulacja i plik JSON w wersji demonstracyjnej
Przycisk Symuluj komunikat agencji otwiera okno z dwoma polami obowiązkowymi: Dokument celny i Rodzaj komunikatu. Rodzaj Zgłoszenie (MRN) przenosi partie z Pod dozorem na Zgłoszony, a rodzaj Zwolnienie towaru ze statusu Pod dozorem albo Zgłoszony na Zwolniony. System buduje komunikat JSON z danych dokumentu i przetwarza go tak, jak odebrany od agencji.
Symulacja zmienia dane demonstracyjne naprawdę: partie dokumentu zmieniają status, a wpis w historii zostaje zapisany. Statusu Zwolniony ani Unijny nie da się cofnąć przyciskiem, dlatego symulację warto uruchamiać na dokumencie przeznaczonym do pokazu. Wynik widać w kolejce razem z hashem i statusem. W rejestrze dokumentów przy dokumencie są także przyciski symulacji zgłoszenia i zwolnienia towaru.
Agencja w module i agent w opisywanym wdrożeniu
Strona o agencie celnym w WMS opisuje inne rozwiązanie: okno agenta, w którym człowiek wpisuje numer DSK i zatwierdza dokument. W module Dozór celny agencja jest wpisem w kartotece, a wynik jej pracy przychodzi komunikatem do kolejki importu. Nie ma okna agenta ani numeru wpisywanego ręcznie przez agencję.
Rano kierownik zaczyna 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. Przykład z wymyślonymi danymi: Agencja Przykładowa przysłała zwolnienie dla dokumentu 26PLEXAMPLE000001A, ale indeks ART-A nie istnieje w kartotece Klienta Testowego. Komunikat ma status Błąd, kierownik dopisuje indeks i używa przycisku Ponów, a partie zmieniają status na Zwolniony.
Czego moduł nie robi
Moduł Dozór celny jest dostępny w środowisku demonstracyjnym platformy StudioSystem ST 26, a wdrożenie następuje po uzgodnieniu zakresu; nie jest to produkt wdrożony u klientów.
- Odbiór przez API. W demo nie ma punktu API przyjmującego komunikaty, jest symulacja i plik JSON w tym samym kontrakcie.
- Integracja z agencją. Nie ma gotowej integracji z konkretną agencją celną; kontrakt pliku lub API wymaga uzgodnienia.
- Zgłoszenia celne. Moduł ich nie składa, tylko odbiera wynik, i nie zastępuje systemu celnego.
- Zdjęcie blokady. Komunikat o zwolnieniu nie zdejmuje blokady ręcznej: partia zostaje bez zmian, a komunikat dostaje status Częściowy.
Typy dokumentów celnych w komunikacie opisuje artykuł o dokumentach T1, DSK i MRN, a rolę agencji w pojęciach - hasło agencja celna w słowniku.