Jak program wysyła zgłoszenia do PUESC: usługa sieciowa, WS-Security i podpis XAdES
Jak działa kanał usługi sieciowej PUESC, czym są UPP i NPP, jak program dopasowuje odpowiedzi do zgłoszeń i kiedy potrzebny jest podpis XAdES.
Większość osób zna PUESC z przeglądarki: logowanie, formularz, wgranie pliku XML, a potem sprawdzanie skrzynki. Ten sam portal udostępnia też kanał usługi sieciowej, przez który program może wysyłać dokumenty i odbierać odpowiedzi bez Twojego udziału. Tak działa ClearRoute. Poniżej opisujemy, co dzieje się po kliknięciu „Wyślij”.
Kanał usługi sieciowej w skrócie
Usługa sieciowa PUESC to interfejs SOAP. Program komunikuje się z nim trzema rodzajami operacji:
- wysłanie dokumentu: program przekazuje komunikat XML, np. zgłoszenie przywozowe ZC415 albo zgłoszenie SENT-100,
- pobranie następnego dokumentu: program odbiera z Twojej skrzynki kolejną odpowiedź,
- pobranie listy dokumentów: program sprawdza, co czeka w skrzynce.
Istnieją dwa środowiska: testowe i produkcyjne. Testowe służy do sprawdzenia, czy komunikaty przechodzą walidację, zanim cokolwiek trafi do urzędu naprawdę. W ClearRoute przełączasz je w ustawieniach kanału, a aktualne środowisko jest cały czas widoczne na górnym pasku.
Logowanie: WS-Security zamiast formularza
Przy usłudze sieciowej nie ma okna logowania. Każde wywołanie zawiera nagłówek WS-Security z loginem i skrótem hasła (UsernameToken). Hasło nie jest przesyłane otwartym tekstem: skrót powstaje z losowej wartości jednorazowej, znacznika czasu i hasła. Dlatego zegar komputera powinien być ustawiony poprawnie, bo zbyt duża różnica czasu kończy się odrzuceniem wywołania.
W programie wpisujesz login i hasło do usługi sieciowej raz. Są szyfrowane mechanizmem systemu Windows i nie opuszczają Twojego komputera inaczej niż w wywołaniach do PUESC.
UPP i NPP: pierwsza odpowiedź na każdy dokument
Po wysłaniu dokumentu PUESC odpowiada poświadczeniem:
- UPP, czyli urzędowe poświadczenie przedłożenia: dokument dotarł i został przyjęty do dalszej obsługi,
- NPP, czyli negatywne poświadczenie przedłożenia: dokument odrzucono, najczęściej z powodu błędu struktury XML albo podpisu. NPP zawiera opis przyczyny.
UPP nie oznacza jeszcze, że zgłoszenie zostało przyjęte przez system docelowy. Właściwe odpowiedzi przychodzą później, na przykład w imporcie ZC428 z numerem MRN, PW429 o zwolnieniu towaru i ZC429 z poświadczonym zgłoszeniem.
Skąd program wie, do którego zgłoszenia pasuje odpowiedź
Odpowiedzi trafiają do jednej skrzynki, niezależnie od tego, ile zgłoszeń wysłałeś. ClearRoute pobiera je co kilka minut i dopasowuje do zgłoszeń po identyfikatorach, które łączą komunikaty: numerze referencyjnym przesyłki, numerze własnym LRN, numerze MRN albo numerze referencyjnym SENT. Każda odpowiedź ląduje w historii właściwego zgłoszenia razem z pełnym XML.
| Wysyłasz | Wraca |
|---|---|
| ZC415 (AIS/IMPORT PLUS) | UPP, ZC428 (MRN), PW429, ZC429, ZCX91 |
| CC515C (AES/ECS2 PLUS) | UPP, CC528C (MRN), CC529C, CC599C |
| CC015C (NCTS2 PLUS) | UPP, CC028C (MRN), CC029C |
| SENT-100 | UPP, numer referencyjny i klucze |
Kiedy potrzebny jest podpis XAdES
Część komunikatów musi być podpisana elektronicznie. ClearRoute podpisuje dokument w formacie XAdES (podpis otoczony, osadzony w XML) certyfikatem z pliku .p12 lub .pfx. Podpis włączasz osobno dla każdego systemu: SENT, AIS, AES i NCTS, bo wymagania mogą się różnić.
Przed pierwszą wysyłką produkcyjną wyślij każdy rodzaj komunikatu w środowisku testowym. Jeżeli podpis jest niepoprawny albo certyfikat nie jest powiązany z Twoim kontem, dostaniesz NPP z opisem błędu, a nie odrzucone zgłoszenie w urzędzie.
Co przygotować przed podłączeniem
- Konto firmy w PUESC z dostępem do usługi sieciowej i do systemów, których używasz.
- Login i hasło do usługi sieciowej.
- Certyfikat .p12 lub .pfx, jeżeli komunikaty muszą być podpisane.
- Dane firmy i numer EORI wpisane w programie.
W ClearRoute po wpisaniu danych klikasz „Pobierz WSDL i sprawdź połączenie”. Program pobiera opis usługi, ustawia przestrzenie nazw i potwierdza, że logowanie działa.
Najczęstsze pytania
Czy przez usługę sieciową wysyłam to samo, co przez przeglądarkę?
Tak. To te same komunikaty XML i te same systemy. Zmienia się tylko kanał: zamiast ręcznego wgrywania program wysyła i odbiera dokumenty sam.
Czym różni się UPP od przyjęcia zgłoszenia?
UPP potwierdza, że dokument dotarł do PUESC i przeszedł wstępną kontrolę. Przyjęcie zgłoszenia i nadanie MRN to osobna odpowiedź systemu docelowego, np. ZC428 w AIS/IMPORT PLUS.
Dlaczego dostaję NPP?
Najczęstsze przyczyny to błąd struktury XML, brak wymaganego pola, niepoprawny podpis albo certyfikat niepowiązany z kontem. Opis przyczyny jest w treści NPP.
Czy mogę testować bez ryzyka?
Tak. Środowisko testowe PUESC przyjmuje te same komunikaty, ale nie wywołuje skutków prawnych. Zalecamy sprawdzić w nim każdy rodzaj zgłoszenia.