Biuletyn – opis usług interfejsu niewizualnego

Wersja podsystemu: ECS 4.00.000

Zrealizowano interfejs na potrzeby automatyzacji komunikacji z systemem od strony podmiotów, przy założeniach:

1 Komunikacja z interfejsem będzie odbywa się w wykorzystaniem webservices.

2 Do wszystkich komunikatów wymienianych z podmiotami dodano opcjonalny atrybut PlacowkaPodmiotu - identyfikator pobierania informacji zwrotnych.

3 Dostępne metody webservice dla podmiotów:

1. acceptDocument – wysłanie dokumentu do systemu ECS

2. getAcceptDocumentStatus – pobranie wyniku wysłanie dokumentu PWK1/PWK2

3. getDocuments – pobranie listy dokumentów

4. getLostDocuments(nr_paczki) – pobranie „zgubionej paczki dokumentów”

Opis interfejsu niewizualnego dla podmiotów udostępnianego przez system ECS.

Oprócz graficznego interfejsu WWW dla podmiotów, system ECS udostępnia interfejs niewizualny, umożliwiający automatyczną komunikację z aplikacjami podmiotów.

Za pomocą tego interfejsu dowolny system informatyczny, wykorzystywany przez podmiot, będzie mógł automatycznie przesyłać dokumenty XML do systemu ECS i odbierać komunikaty, utworzone w systemie ECS i przeznaczone dla tego podmiotu.

Założenia wstępne:

System ECS udostępnia aplikacjom podmiotów interfejs niewizualny FromTraderWebService, umożliwiający:

1. Przesłanie komunikatu XML IE507, IE514, IE515 oraz IE547 do systemu ECS;

2. Pobranie potwierdzenia odbioru / odrzucenia dokumentu w postaci komunikatów PWK1 lub PWK2;

3. Pobieranie z systemu ECS komunikatów informujących o stanie obsługi przesłanych zgłoszeń celnych.

Uprawnienia do komunikacji za pomocą interfejsu nabywa każdy reprezentant podmiotu zarejestrowany w PDR i posiadający login i hasło dostępu do systemów administracji celnej.

Interfejs jest udostępniony jako usługa webservice zabezpieczona za pomocą SSL. Każde żądanie wymaga autoryzacji HTTP typu Basic.

Autoryzacja polega na dodaniu nagłówka HTTP podczas wywołania SOAP. Treść nagłówka powinna zawierać login i hasło reprezentanta, zapisane w postaci: "Authorization: Basic username:password" w której 'username:password' jest zakodowane za pomocą Base64. Cała transmisja zabezpieczona jest poprzez SSL, więc nie ma możliwości odczytu tak przesłanego nagłówka autoryzującego.

Interfejs zakłada wykorzystanie atrybutu @PlacowkaPodmiotu, dodanego do struktury komunikatów IE507, IE514, IE515 lub IE547, w celu rozdzielenia komunikatów zwrotnych między różne oddziały podmiotu. Sposób komunikacji aplikacji podmiotu z systemem ECS może być „sterowany” danymi dokumentu XML przekazywanymi do ECS:

1 Podanie adresu e-mail (atrybut @EmailPodmiotu) spowoduje przesłanie komunikatów zwrotnych z ECS, dotyczących danej sprawy, pocztą elektroniczną na podany adres;

2 Podanie identyfikatora placówki podmiotu (@PlacowkaPodmiotu) spowoduje udostępnienie komunikatów zwrotnych za pośrednictwem interfejsu niewizualnego.

Obydwie ścieżki komunikacji z ECS mogą być wykorzystywane niezależnie. Identyfikacja tego samego komunikatu odebranego z dwóch różnych interfejsów następuje w oparciu o wartość atrybutu @NrWlasny.

Metody interfejsu FromTraderWebService:

acceptDocument

Opis

Metoda umożliwiająca przekazanie dokumentu (z ewentualnymi załącznikami) z aplikacji podmiotu do systemu ECS. Przed zapisem dokumentu w systemie ECS weryfikowane są uprawnienia reprezentanta przekazującego dokument, analogicznie, jak podczas przesyłania dokumentu pocztą elektroniczną.

Przesyłane żądanie przyjęcia dokumentu w postaci komunikatu AcceptDocument może zawierać tylko jeden dokument XML IE507, IE514, IE515 lub IE547.

Tin podawany w AcceptDocument/@tin powinien być zgodny z TIN-em podmiotu zgłaszającego w załączonym komunikacie IE (np. ZgłaszającyPrzedstawiciel/@TIN dla IE515, Przedstawiający/@TIN dla IE507).

Zwracany w odpowiedzi komunikat AcceptDocumentResult zwiera unikalny identyfikator żądania (atrybut @token), umożliwiający pobranie wyniku odbioru dokumentu przez system ECS (patrz metoda (getAcceptDocumentStatus).

Parametry

Dokument XML AcceptDocument, o strukturze zdefiniowanej w „DTI.AcceptDocument_v1-0.xsd”

Typ wyniku

Dokument XML AcceptDocumentResult , o strukturze zdefiniowanej w „DTI.AcceptDocumentResult_v1-0.xsd”

getAcceptDocumentStatus

Opis

Metoda umożliwiająca pobranie wyniku odbioru dokumentu, przesłanego do systemu ECS z użyciem metody „acceptDocument”. Identyfikacja dokumentu, którego dotyczy zapytanie, odbywa się poprzez podanie w komunikacie GetAcceptDocumentStatus następujących danych:

·1 · identyfikatora, zwróconego w AcceptDocumentResult\@token w atrybucie @token;

·2 · numeru TIN, który został uprzednio przesłany w komunikacie AcceptDocument w atrybucie @tin.

Zwracana odpowiedź zawiera treść komunikatu PWK1 lub PWK2.

Jeżeli odpowiedź nie zawiera komunikatu PWK (atrybut @resultCode ma wartość 0, to znacza, że system ECS nie zakończył jeszcze przetwarzania dla przesłanego dokumentu.

Parametry

Dokument XML GetAcceptDocumentStatus o strukturze zdefiniowanej w „DTI.GetAcceptDocumentStatus_v1-0.xsd”.

Typ wyniku

Dokument XML GetAcceptDocumentStatusResult o strukturze zdefiniowanej w „DTI.GetAcceptDocumentStatusResult_v1-0.xsd”. Zawiera komunikat PWK1 lub PWK2.

getDocuments

Opis

Metoda umożliwiająca pobranie paczki komunikatów XML, utworzonych w systemie ECS i przeznaczonych dla Podmiotu.

Zapytanie wymaga podania TIN-u i kodu placówki podmiotu zapytującego w komunikacie GetDocuments.

Zasadniczo funkcja zwraca tylko komunikaty dotychczas niepobrane - komunikaty przekazane Podmiotowi są znakowane w systemie ECS i pomijane przy ponownym przetwarzaniu żądania. W szczególnym przypadku metoda może zwrócić kilkukrotnie ten sam komunikat – wówczas, gdy w systemie ECS zostanie wydane dla niego polecenie „Wyślij ponownie”.

Kod wyniku zapytania jest zwracany w atrybucie @resultCode komunikatu GetDocumentsResult:

"0" - brak dokumentów do pobrania,

"1" - zwrócono paczkę wszystkich dostępnych dokumentów,

"2" - zwrócono paczkę dokumentów ale ilość została ograniczona - pozostały jeszcze dokumenty do pobrania.

Wartość ujemna - oznacza błąd (patrz „Tabela kodów błędów dla atrybutu resultCode”).

W przypadku, gdy @resultCode ma wartość „1” lub „2” , atrybut @PackageNumber w komunikacie GetDocumentsResult zawiera numer kolejny paczki w postaci: identyfikator placówki Podmiotu (atrybut @PlacowkaPodmiotu komunikatu IExxx, inicjującego sprawę) / numer kolejny.

Numer ten może być wykorzystany do kontroli poprawności komunikacji z systemem ECS lub w celu ponownego pobrania dokumentów (patrz metoda getLostDocuments). Jeżeli w numeracji wystąpi luka, to może to oznaczać „zagubienie” paczki komunikatów np. wskutek zerwania połączenia. W takim przypadku należy ponownie „zapytać” system ECS o brakującą paczkę za pomocą metody getLostDocuments.

Interfejs niewizualny posiada ograniczenie dotyczące częstotliwości obsługi żądań getDocuments od jednego Podmiotu. Sprawdzaniu podlega czas, jaki upłynął od ostatniego odebranego żądania. Jeżeli okres ten jest krótszy od zadanego, to komunikaty z ECS nie są zwracane (@resultCode ma wartość 0). Długość interwału czasowego jest definiowana przez administratorów systemu ECS.

Ograniczenie dopuszczalnego odstępu czasowego pomiędzy żądaniami getDocuments nie dotyczy sytuacji, gdy poprzednia odpowiedź nie zwróciła wszystkich dokumentów (gdy (@resultCode ma wartość 2).

Parametry

Dokument XML GetDocuments o strukturze zdefiniowanej w „DTI.GetDocuments_v1-0.xsd”

Typ wyniku

Dokument XML GetDocumentsResult o strukturze zdefiniowanej w „DTI.GetLostDocumentsResult_v1-0.xsd”

getLostDocuments

Opis

Metoda pozwalająca na ponowne pobrania przez aplikację podmiotu "zagubionej" paczki dokumentów, na podstawie jej numeru tj. atrybutu //GetDocumentsResult/@ packageNumber zwróconego z systemu ECS w wyniku wywołania metody getDocuments .

Ponowne pobranie może być konieczne w przypadku niepoprawnego odebrania lub „zagubienia” paczki np. wskutek zerwania połączenia internetowego.

Kod wyniku zapytania jest zwracany w atrybucie @resultCode komunikatu GetLostDocumentsResult:

"0" - brak paczki o podanym numerze lub paczka nie jest już dostępna do pobrania,

"1" - zwrócono paczkę dokumentów.

Wartość ujemna oznacza błąd (patrz " Tabela kodów błędów dla atrybutu resultCode").

Parametry

Dokument XML GetLostDocument o strukturze zdefiniowanej w „DTI.GetLostDocuments_v1-0.xsd”.

Typ wyniku

Dokument XML GetLostDocumentsResult o strukturze zdefiniowanej w „DTI.GetLostDocumentsResult_v1-0.xsd”

Tabela kodów błędów dla atrybutu resultCode:

resultCode	Znaczenie
-10	Niepoprawny parametr wywołania operacji
-11	System chwilowo nie potrafił wykonać żądania (spróbuj później)
-12	Błąd wewnętrzny systemu wykonanie operacji niemożliwe.
-20	Błąd autoryzacji – nazwa użytkownika lub hasło jest niepoprawne
-21	Błąd autoryzacji – brak uprawnień do wykonania operacji dla danego TIN
-22	Błąd autoryzacji – hasło wygasło (wymaga zmiany)
-23	Błąd autoryzacji – konto zablokowane