Pytania i odpowiedzi

Potrzebujesz więcej informacji na temat Uniwersalnej Bramki Dokumentów? Zobacz odpowiedzi na najczęściej zadawane pytania

13.07.2023

Wybierz pytanie


  1. 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").


  2. 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


  3. 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.


  4. 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.


  5. 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ą.


  6. 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.


  7. Ministerstwo Finansów udostępnia bramki Web Services systemu e-Deklaracje, które umożliwiają składanie dokumentów drogą elektroniczną:


  8. Szczegółowe informacje na temat wymagań technicznych zostały przedstawione w Specyfikacjach Wejścia Wyjścia opublikowanych w zakładce Dokumentacja IT.


  9. 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).


  10. Opublikowane w Repozytorium CRD na platformie ePUAP wzory pozwalają na samodzielne przygotowanie na ich podstawie danych w formacie XML.


  11. 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.


  12. 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.


  13. 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).


  14. 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.


  15. 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.


  16. 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.


    1. Przygotowanie poprawnego dokumentu XML, zgodnego ze wzorem XSD (opublikowanym w Repozytorium CRD ePUAP dostępnym pod adresem crd.gov.pl).
    2. 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".
    3. Zakodowanie algorytmem base64Binary podpisanego dokumentu XML.
    4. Wysłanie na bramkę (wywołanie odpowiedniej operacji usługi Web Services).
    5. 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.


  18. 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.


  19. Bramka UBD obsługuje dokumenty elektroniczne z kwalifikowanym podpisem elektronicznym w formacie PKCS#7 oraz XAdES (zalecany format podpisu) profil enveloped lub enveloping.


  20. 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:

    1. poprawny XML
    2. archiwizacja do ZIP
    3. podpisanie w formacie XAdES
    4. zakodowanie do base64Binary
    5. wysłanie na bramkę UBD
    6. sprawdzenie statusu
    7. dla statusu „200" pobranie UPO
      lub
      dla statusu błędu poprawienie danych i ponowne przesłanie (pkt 5).


  21. 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.


  22. 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.


  23. 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.


  24. 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.


  25. Dokument zbiorczy to jeden dokument XML, który zawiera sekcję powtarzalną. Schemat XSD (wzór) zawiera ograniczenie sekcji powtarzalnej do 20.000 pozycji.


  26. 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).


  27. 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.


  28. 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.


  29. Otrzymany numer referencyjny dotyczy całego dokumentu zbiorczego i wszystkich danych w sekcji wielopozycyjnej.


  30. 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).


  31. 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.

    1. Struktura plików XML (pojedynczych) jest taka sama dla wszystkich bramek Web Services systemu e-Deklaracje (środowiska testowe i produkcyjne).
    2. Dokumenty zbiorcze są obsługiwane jedynie przez bramkę testową i produkcyjną UBD.
    3. Przygotowane dokumenty XML muszą być zgodne z opublikowanymi wzorami XSD (schema)
    4. Dokumenty zbiorcze są przed podpisaniem kompresowane (format zip algorytm kompresji deflate).
    5. Wymagany podpis elektroniczny kwalifikowany ma taki sam format (zalecany XAdES envelope/enveloping).
    6. Struktura podpisu danymi autoryzującymi dla bramki UBD zawiera szersze informacje m.in. skrót kryptograficzny.


  33. 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.


  34. 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).


  35. 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:

    1. przygotowanie uporządkowanej leksykograficznie kanonicznej postaci pliku XML zgodnego ze schemą XSD
    2. podpisanie go podpisem elektronicznym w formacie XAdES profil envelope/enveloping.
    3. zakodowanie podpisanego pliku XML algorytmem base64Binary (nie wykonywać w przypadku automatycznego kodowania w procesie wysyłki - pkt 4).
    4. wysłanie danych na bramkę (w komunikacie SOAP 1.1 lub 1.2).
    5. otrzymanie zwrotnego statusu przetwarzania dokumentu ( kod statusu „301").
    6. 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.
    7. prezentacja UPO (zapisanie, wydruk) i zakończenie procedury wysyłki.


  36. 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:

    1. przygotowanie uporządkowanej leksykograficznie kanonicznej postaci pliku XML zgodnego ze schemą XSD.
    2. kompresja danych XML do postaci ZIP.
    3. 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)
    4. wysłanie danych na bramkę (w komunikacie SOAP 1.1 lub 1.2).
    5. otrzymanie zwrotnego statusu przetwarzania dokumentu (kod stausu „301").
    6. 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.
    7. prezentacja UPO (zapisanie, wydruk) i zakończenie procedury wysyłki.


  37. 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.


  38. 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.


  39. Od 01.01.2015 r. bramka produkcyjna UBD przyjmuje tylko dokumenty zbiorcze.


  40. Testowa bramka UBD przyjmuje wszystkie aktualne dokumenty pojedyncze oraz testowe zbiorcze.

    Bramka UBD produkcyjna od 1 stycznia 2015 r. przyjmuje jedynie dokumenty zbiorcze.


  41. Element nagłówka <tns:KodUrzedu>0000</tns:KodUrzedu> w przypadku testowych dokumentów zbiorczych zawsze powinien mieć wartość "0000".


  42. 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.


  43. Nazwa tworzonego pliku XML z danymi deklaracji nie ma znaczenia dla bramki UBD (przesyłana jest treść a nie plik).

  44. 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.


  45. Bramka UBD w sytuacji stwierdzenia błędu w dokumencie zbiorczym odrzuca cały dokument.


  46. 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.

 

Pobierz PDF
Opublikowano: 25.04.2019
Zmodyfikowano: 13.07.2023
Opracowanie: Redakcja Portalu Podatkowego