Wybierz pytanie
-
Błąd w dokumencie zbiorczym
Dokument zbiorczy w formacie XML stanowi integralną całość i jeżeli błędna jest jedna z jego sekcji (np. dane dot. jednego z podatników) - to cały dokument zbiorczy zostanie odrzucony (status „401 – Weryfikacja negatywna - dokument niezgodny ze schematem xsd"). -
Status przesłanego do UBD dokumentu
Zwracany status przetwarzania dla dokumentu odrzuconego po weryfikacji zawiera kod błędu i słowny opis przyczyny błędu.Dla weryfikacji zgodności danych XML ze wzorem XSD opis może zawierać również krótkie informacje techniczne, które pochodzą bezpośrednio z aplikacji weryfikującej (parser). Dla dokumentu zbiorczego zwracany opis błędu może zawierać jedynie informację o pierwszym wystąpieniu błędu w danych XML.
Istnieją bezpłatne narzędzia, które pozwalają na samodzielną walidację przygotowanych danych XML ze wzorem XSD dokumentu elektronicznego
-
Czy można zaimportować do formularza PDF dane XML, które zawierają kilkadziesiąt PIT-11, aby wysłać je przez UBD?
Nie.Na portalu nie ma interaktywnych formularzy PDF, które dotyczyłyby wzorów deklaracji wielopozycyjnych tj. PIT-11Z, PIT-8CZ i PIT-RZ. Do dokumentów interaktywnych PDF (w tym PIT-11) można importować z pliku XML dane wyłącznie dla pojedynczych dokumentów.
-
Gdzie znajdują się dostępne opisy mechanizmów, które umożliwiają transfer danych i przesłanie do UBD, przykłady użycia kodu, ewentualnie biblioteki do zaimplementowania we własnym oprogramowaniu
Opis WSDL usługi Web Services został stworzony z zachowaniem standardów w sposób jednoznacznie opisujący udostępnioną usługę. Jest on poprawnie interpretowany przez edytory WSDL i pozwala, wykorzystując dostępne narzędzia programistyczne, na przygotowanie poprawnej implementacji klienta usługi Web Services.Szczegółowe informacje techniczne dotyczące działania UBD zostały zawarte w specyfikacjach Wejścia-Wyjścia dostępnych w zakładce Dokumentacja IT. Pozwalają one na przygotowanie przez firmy IT własnych rozwiązań, które pozwalają na wysłanie dokumentu XML i odebranie zwrotnego komunikatu (status, UPO).
Ministerstwo Finansów nie wskazuje metod, zastosowań, narzędzi i rozwiązań programistycznych, stąd też nie publikuje przykładów implementacji rozwiązania dla Web Services.
-
Podpis dokumentów wysyłanych do UBD
Dla dokumentów elektronicznych składanych do UBD wymagane jest ich podpisanie za pomocą:- kwalifikowanego podpisu elektronicznego (certyfikaty wydane przez jedno z 5 polskich centrów certyfikacji elektronicznej),
- "dane autoryzujące" (podpis elektroniczny, które zapewnia autentyczność deklaracji i podań oparty na danych autoryzujących) przez płatnika będącego osobą fizyczną.
-
Wysyłanie dokumentów do UBD
Podpisany dokument elektroniczny PIT-11Z, PIT-8CZ (obowiązywał do rozliczenia za rok 2016), PIT-RZ może być wysłany do systemu e-Deklaracje jedynie przez bramkę UBD (usługa Web Services).Środowisko produkcyjne WS UBD.
Udostępnione zostało również środowisko testowe UBD, które pozwala na sprawdzenie własnych rozwiązań i testową wysyłkę deklaracji wielopozycyjnych.
-
Dostęp do bramek usługi Web Services systemu e-Deklaracje
Ministerstwo Finansów udostępnia bramki Web Services systemu e-Deklaracje, które umożliwiają składanie dokumentów drogą elektroniczną: -
Wymagania techniczne - dostęp do UBD
Szczegółowe informacje na temat wymagań technicznych zostały przedstawione w Specyfikacjach Wejścia Wyjścia opublikowanych w zakładce Dokumentacja IT. -
Korzystanie ze środowiska testowego UBD
Aby skorzystać ze środowiska testowego UBD nie są konieczne żadne dodatkowe działania ze strony użytkownika (użyty certyfikat SSL/TLS jest automatycznie rozpoznawany w systemach Windows). -
Poprawność wysyłanych do UBD dokumentów - zgodność ze wzorem
Opublikowane w Repozytorium CRD na platformie ePUAP wzory pozwalają na samodzielne przygotowanie na ich podstawie danych w formacie XML. -
Dedykowany program dla płatników
Ministerstwo Finansów nie planuje udostępniania specjalnej aplikacji dla płatników, którzy chcąc skorzystać z wysyłki dokumentów zbiorczych (wielopozycyjnych PIT-11Z, PIT-8CZ, PIT-RZ).Opublikowane materiały (specyfikacja wejścia-wyjścia, wzory zbiorczych dokumentów elektronicznych XSD dla płatników w repozytorium CRD ePUAP – oraz na stronie www.podatki.gov.pl oraz udostępnione środowisko testowe nowej bramki UBD pozwalają na przygotowanie zbiorczego dokumentu (PIT-11Z, PIT-8CZ, PIT-RZ, PIT-40Z) i wysłanie go do bramki testowej lub produkcyjnej usługi Web Services.
Ponadto funkcjonujące dotychczas rozwiązanie dla składania pojedynczych dokumentów – również przez płatników – stanowi uzupełnienie i alternatywę dla nowej bramki UBD.
-
Przykładowe pliki do wysyłania na UBD
Ministerstwo Finansów nie publikuje przykładowych plików XML dla wzorów XSD dokumentów elektronicznych.Przykłady dokumentów zamieszczone są w opublikowanych specyfikacjach wejścia-wyjścia dostępnych w zakładce Dokumentacja IT.
-
Działanie UBD - aplikacja www, czy aplikacja instalowana na komputerze
UBD działa jako udostępnione usługi Web Services (bramki testowe i produkcyjne).Dokumenty przesyłane do systemu przez aplikacje własne podatników (wywołanie odpowiednich operacji usług WS) muszą być w formacie XML, z kodowaniem znaków UTF-8 i opatrzone podpisem elektronicznym (kwalifikowanym lub danymi autoryzującymi).
-
Bramka UBD a bramka e-Deklaracje
Obie bramki (usługi Web Services) stanowią składniki jednego systemu e-Deklaracje i przesłane dokumenty elektroniczne podatnika po zakończonej pozytywnie weryfikacji zawsze trafiają do urzędu skarbowego wskazanego w złożonym dokumencie elektronicznym. -
Czy dokumenty wysyłane przez bramkę UBD podpisane podpisem elektronicznym są wysyłane analogicznie jak przez bramkę e-Deklaracje
Tak.Dokumenty elektroniczne składane do systemu e-Deklaracje muszą być podpisane, co jest jednym z warunków na ich poprawną weryfikację.
Szczegóły zostały zamieszczone w specyfikacjach wejścia-wyjścia dostępnych w zakładce Dokumentacja IT.
-
Wzór XSD dla UPO
Schemat XSD dla UPO jest możliwy do pobrania w Tabeli struktur dokumentów XML - plik "Potwierdzenie_v6-0.xsd" - dostępnej w zakładce Dokumentacja IT.Urzędowe Poświadczenie Odbioru jest wystawiane dla jednego, konkretnego, złożonego do systemu e-Deklaracje dokumentu elektronicznego.
-
Kolejność działań dla przygotowania dokumentów XML składanych przez bramkę e-Deklaracje
- Przygotowanie poprawnego dokumentu XML, zgodnego ze wzorem XSD (opublikowanym w Repozytorium CRD ePUAP dostępnym pod adresem crd.gov.pl).
- Podpisanie dokumentu podpisem elektronicznym w formacie XAdES lub PKCS#7
Podczas wykonywania operacji podpisu w aplikacji do podpisu zalecane jest wybranie formatu podpisu XAdES. Konieczne może być również zaznaczenie opcji:
- "Zapisz podpisywane dane razem z podpisem",
- "Podpis zgodny z eDeklaracje",
- "Nie koduj danych XML'owych do Base64".
- Zakodowanie algorytmem base64Binary podpisanego dokumentu XML.
- Wysłanie na bramkę (wywołanie odpowiedniej operacji usługi Web Services).
- Sprawdzenie statusu przetwarzania przedłożonego dokumentu XML i dla statusu "200" pobranie UPO.
Pkt c. nie zawsze musi być wykonany, gdyż program, który wysyła dane XML może sam automatycznie je kodować wykorzystując mechanizm MTOM - wymaga to sprawdzenia, gdyż podwójne zakodowanie danych spowoduje błąd (kod „408") i odrzucenie dokumentu.
Postępowanie zgodnie z w/w punktami pozwoli na poprawne przejście procedury przygotowania i wysłania dokumentu.
-
UPO
Dla dokumentu elektronicznego poprawnie zweryfikowanego należy pobrać Urzędowe Poświadczenie Odbioru (UPO), które stanowi dowód i potwierdzenie terminowego złożenia deklaracji. -
Format kwalifikowanego podpisu elektronicznego
Bramka UBD obsługuje dokumenty elektroniczne z kwalifikowanym podpisem elektronicznym w formacie PKCS#7 oraz XAdES (zalecany format podpisu) profil enveloped lub enveloping. -
Status błędu „409” dla dokumentów składanych do UBD
W przypadku pojawienia się komunikatu błędu o statusie „409" należy zweryfikować kolejność działań dla dokumentu zbiorczego.Prawidłowa kolejność dla przygotowania i przesłania zbiorczych dokumentów:
- poprawny XML
- archiwizacja do ZIP
- podpisanie w formacie XAdES
- zakodowanie do base64Binary
- wysłanie na bramkę UBD
- sprawdzenie statusu
- dla statusu „200" pobranie UPO
lub
dla statusu błędu poprawienie danych i ponowne przesłanie (pkt 5).
-
Wersja SOAP
Informacje o wersji SOAP znajdują się w definicji WSDL Specyfikacji Wejścia – Wyjścia dostępnej w zakładce Dokumentacja IT.Usługa Web Services systemu e-Deklaracje obsługuje obie wersje SOAP 1.1 i 1.2.
-
Protokół SOAP powinien być Microsoftowy, czy może być od innego dostawcy np. Oracle?
Format komunikatu musi być zgodny ze specyfikacją standardu SOAP opublikowaną na stronach W3C.Aby przetestować komunikację do usługi Web Services należy zapoznać się z materiałami na stronach organizacji W3C i skorzystanie np. z rozwiązania soapUI, które pozwala m.in. na testy wysyłki, analizę WSDL i wyświetlenie szczegółów operacji dla usług Web Services bramek środowisk testowych i produkcyjnych systemu e-Deklaracje.
-
Pliki WSDL, XSD usług Web Services
Tworząc własne rozwiązania informatyczne, które obejmuje wywołanie usługi Web Services polecamy bezpośrednie odwołanie się do adresu usługi, co pozwoli uniknąć błędów i przekłamań wynikających np. z kopiowania WSDL z dokumentacji. -
Status „408” - przyczyny
Status „408" może wskazywać m.in. na:- nieobsługiwany format podpisu np. XAdES detached (podczas podpisywania tworzone są 2 pliki),
- nieprawidłową zawartość w elementach dokumentu np. brak identyfikatorów podatkowych, kodu US, kodowanie inne niż UTF-8,
- nieprawidłową strukturę pliku XML.
-
Zbiorczy dokument - maksymalny dopuszczalny rozmiar dokumentu wysyłanego do UBD
Dokument zbiorczy to jeden dokument XML, który zawiera sekcję powtarzalną. Schemat XSD (wzór) zawiera ograniczenie sekcji powtarzalnej do 20.000 pozycji. -
Podpis elektroniczny pod dokumentem zbiorczym
Wszystkie dokumenty elektroniczne składane do systemu e-Deklaracje muszą być opatrzone podpisem elektronicznym: kwalifikowanym podpisem elektronicznego lub "danymi autoryzującymi" (podpisem elektronicznym zapewniającym autentyczność deklaracji i podań opartym na danych autoryzujących).Jeden dokument oznacza jeden podpis – składany tylko pod całym dokumentem, również zbiorczym (podpisywany jest zzipowany zbiorczy PIT-11Z czy PIT-8CZ).
-
Status przyjęcia / weryfikacji dokumentu zbiorczego - w odniesieniu do wszystkich formularzy czy całego dokumentu zbiorczego
W przypadku błędu weryfikacji dokumentu zbiorczego zwrócony komunikat zawiera ogólną informację o wystąpieniu błędu np. pierwsze wystąpienie błędu.Weryfikacja poprawności danych powinna być wykonana przed ich wysłaniem do produkcyjnej UBD. Udostępnione środowisko testowe pozwala na sprawdzenie przyjętych rozwiązań.
Opublikowane w zakładce Dokumentacja IT specyfikacje wejścia-wyjścia powinny pomóc w przygotowaniu dokumentów XML i rozwiązań komunikujących się z usługą WS bramki UBD.
-
Wystąpienie błędu w którymkolwiek z formularzy w dokumencie zbiorczym - konieczność wysyłania jeszcze raz całego dokumentu
Błąd podczas weryfikacji dokumentu zbiorczego skutkuje odrzuceniem go w całości z błędem z grupy "4xx" i koniecznością poprawy oraz ponownej wysyłki. -
Identyfikator złożonego dokumentu zbiorczego (numer referencyjny)
Otrzymany numer referencyjny dotyczy całego dokumentu zbiorczego i wszystkich danych w sekcji wielopozycyjnej. -
Dokumenty obsługiwane przez UBD od 01.01.2015 r.
Za pośrednictwem UBD istnieje możliwość przesyłania dokumentów zbiorczych:- PIT-11Z,
- PIT-8CZ,
- PIT-RZ,
- PIT-40Z (obowiązywał do rozliczenia za rok 2016).
-
Dokumenty składane do bramki UBD – wersje schematu (wzór XSD)
Bramka testowa UBD pozwala na składanie dokumentów zbiorczych oraz pojedynczych dokumentów (jedynie w celu przygotowania rozwiązań docelowych) zawsze zgodnych z przygotowanymi wzorami XSD.Od 01.01.2015 r. bramka produkcyjna UBD przyjmuje tylko dokumenty zbiorcze.
-
Struktura pliku XML
- Struktura plików XML (pojedynczych) jest taka sama dla wszystkich bramek Web Services systemu e-Deklaracje (środowiska testowe i produkcyjne).
- Dokumenty zbiorcze są obsługiwane jedynie przez bramkę testową i produkcyjną UBD.
- Przygotowane dokumenty XML muszą być zgodne z opublikowanymi wzorami XSD (schema)
- Dokumenty zbiorcze są przed podpisaniem kompresowane (format zip algorytm kompresji deflate).
- Wymagany podpis elektroniczny kwalifikowany ma taki sam format (zalecany XAdES envelope/enveloping).
- Struktura podpisu danymi autoryzującymi dla bramki UBD zawiera szersze informacje m.in. skrót kryptograficzny.
-
Problem z połączeniem z testową UBD
Bramka testowa UBD jest dostępna na stronie test-UBD.W przypadku błędu połączenia należy zweryfikować, czy w oknie przeglądarki po podaniu adresu https://test-ubd.mf.gov.pl/uslugi/dokumenty?wsdl wyświetli się opis WSDL usługi (dane w formacie XML). Brak opisu może wskazywać na błędne skonfigurowanie zabezpieczeń sieciowych np. proxy czy firewall.
-
Certyfikaty SSL usługi WS UBD
Bramki UBD korzystają z certyfikatów wystawionych przez centrum certyfikacji będące wśród zaufanych wystawców w systemach Windows (GeoTrust SSL CA) stąd użytkownik nie powinien otrzymywać komunikatu błędu dla bezpiecznego połączenia (SSL/TLS). -
Proces przygotowania i wysyłki pojedynczych dokumentów elektronicznych
UBD produkcyjna przyjmuje tylko dokumenty zbiorcze.
Proces przygotowania i wysyłki dokumentów elektronicznych pojedynczych do testowej bramki UBD nie różni się od aktualnie realizowanej procedury.
Kolejność działań jest następująca:
- przygotowanie uporządkowanej leksykograficznie kanonicznej postaci pliku XML zgodnego ze schemą XSD
- podpisanie go podpisem elektronicznym w formacie XAdES profil envelope/enveloping.
- zakodowanie podpisanego pliku XML algorytmem base64Binary (nie wykonywać w przypadku automatycznego kodowania w procesie wysyłki - pkt 4).
- wysłanie danych na bramkę (w komunikacie SOAP 1.1 lub 1.2).
- otrzymanie zwrotnego statusu przetwarzania dokumentu ( kod statusu „301").
- ponowne wywołanie usługi w celu sprawdzenia statusu przetwarzania:
- w przypadku otrzymania statusu z grupy "400" poprawienie danych XML i ponowne przesłanie,
- w przypadku otrzymania statusu "302" ponowne sprawdzenie statusu po czasie min. 2 h,
- w przypadku statusu "200" pobranie UPO.
- prezentacja UPO (zapisanie, wydruk) i zakończenie procedury wysyłki.
-
Proces przygotowania i wysyłki dokumentów elektronicznych zbiorczych do UBD
Proces przygotowania i wysyłki dokumentów elektronicznych zbiorczych do UBD różni się od dotychczasowego sposobu wysyłania dokumentów jedynie dodaniem kompresji ZIP.Kolejność działań jest następująca:
- przygotowanie uporządkowanej leksykograficznie kanonicznej postaci pliku XML zgodnego ze schemą XSD.
- kompresja danych XML do postaci ZIP.
- podpisanie go podpisem elektronicznym w formacie XAdES profil envelope/enveloping;d zakodowanie podpisanego pliku XML algorytmem base64Binary (nie wykonywać w przypadku automatycznego kodowania w procesie wysyłki - ppkt 5)
- wysłanie danych na bramkę (w komunikacie SOAP 1.1 lub 1.2).
- otrzymanie zwrotnego statusu przetwarzania dokumentu (kod stausu „301").
- ponowne wywołanie usługi w celu sprawdzenia statusu przetwarzania:
- w przypadku otrzymania statusu z grupy "400" poprawienie danych XML i ponowne przesłanie,
- w przypadku otrzymania statusu "302" ponowne sprawdzenie statusu po czasie min. 2 h,
- w przypadku statusu "200" pobranie UPO.
- prezentacja UPO (zapisanie, wydruk) i zakończenie procedury wysyłki.
-
Testowa bramka WS UBD – testowanie rozwiązań przez podmioty końcowe
Bramka testowa UBD jest udostępniana dla wszystkich obecnych i przyszłych użytkowników systemu e-Deklaracje.Szczególnie zachęcamy twórców oprogramowania przeznaczonego do przekazywania dokumentów elektronicznych do jej wykorzystywania w celu testowania własnych rozwiązań. Ministerstwo Finansów nie udostępnia aplikacji wysyłających dokumenty do systemu testowego.
-
Testowanie wysyłki zbiorczego PIT
Ministerstwo Finansów nie udostępnia programu umożliwiającego przesyłanie dokumentów na testową bramkę UBD.Szczegółowe informacje dotyczące zasad wymiany informacji pomiędzy środowiskiem testowym UBD, a oprogramowaniem interfejsowym zawiera specyfikacja We-Wy UBD - środowisko testowe dostępna w zakładce Dokumentacja IT.
-
Błąd o statusie „408” podczas wysyłania PIT-11 pojedynczego na bramkę UBD
Od 01.01.2015 r. bramka produkcyjna UBD przyjmuje tylko dokumenty zbiorcze. -
Przyjmowane dokumenty przez UBD
Testowa bramka UBD przyjmuje wszystkie aktualne dokumenty pojedyncze oraz testowe zbiorcze.Bramka UBD produkcyjna od 1 stycznia 2015 r. przyjmuje jedynie dokumenty zbiorcze.
-
Pozycja kod urzędu w bloku TNaglowek dokumentów elektronicznych wysyłanych dla UBD
Element nagłówka <tns:KodUrzedu>0000</tns:KodUrzedu> w przypadku testowych dokumentów zbiorczych zawsze powinien mieć wartość "0000". -
Wysyłanie korekt formularzy do UBD
Korekta zawsze dotyczy pojedynczego dokumentu i może zawierać załącznik ORD-ZU. Nie jest możliwe złożenie korekty dla dokumentu zbiorczego do UBD.Schematy dokumentów zbiorczych nie przewidują składania korekt.Korekta danych dotyczących konkretnego podatnika z dokumentu zbiorczego PIT-11Z możliwa jest poprzez złożenie korekty PIT-11 na dotychczasowych zasadach do bramki e-Deklaracje.
-
Poprawna struktura nazwy pliku składanego do UBD
Nazwa tworzonego pliku XML z danymi deklaracji nie ma znaczenia dla bramki UBD (przesyłana jest treść a nie plik). -
Pola obowiązkowe i słownikowe w PIT-11, PIT-8C z danymi adresowymi (np. ulica, nr domu, poczta, powiat)
Informacja na temat danych adresowych dla polskiego adresu podatnika:
<etd:AdresPol>
<etd:KodKraju>PL</etd:KodKraju>
<etd:Wojewodztwo>WYMAGANE</etd:Wojewodztwo>
<etd:Powiat>WYMAGANE</etd:Powiat>
<etd:Gmina>WYMAGANE</etd:Gmina>
<etd:Ulica>OPCJONALNE</etd:Ulica>
<etd:NrDomu>WYMAGANE</etd:NrDomu>
<etd:NrLokalu>OPCJONALNE</etd:NrLokalu>
<etd:Miejscowosc>WYMAGANE</etd:Miejscowosc>
<etd:KodPocztowy>WYMAGANE</etd:KodPocztowy>
<etd:Poczta>WYMAGANE</etd:Poczta>
</etd:AdresPol>
Tylko kod kraju jest elementem słownikowym. Plik schemy można znaleźć w zakładce Struktury dokumentów XML. -
Błąd w dokumencie zbiorczym wysyłanym do UBD
Bramka UBD w sytuacji stwierdzenia błędu w dokumencie zbiorczym odrzuca cały dokument. -
Weryfikacja dokumentu zbiorczego wysyłanego do UBD
Weryfikacja dokumentu zbiorczego obejmuje sprawdzenie m.in.:- poprawności kodowania base64Binary,
- poprawności, formatu i ważności podpisu elektronicznego,
- formatu spakowanych danych ZIP,
- zgodności XML ze schemą XSD,
- unikalności (duplikat) danych dla całego dokumentu,
- unikalności danych dla podatnika z sekcji dokumentu zbiorczego.