taxmachine.pl

e-Deklaracje — wysyłka deklaracji podatkowych do MF

Generowanie XML, podpis (kwalifikowany lub dane autoryzujące), wysyłka do bramki Ministerstwa Finansów i pobranie UPO dla deklaracji VAT, PIT i CIT.

Opublikowano

Moduł e-Deklaracje odpowiada za pełen cykl elektronicznej wysyłki formularzy podatkowych do systemu e-Deklaracje Ministerstwa Finansów: zbudowanie pliku XML z danych formularza, walidację zgodności ze schematem XSD, dołączenie podpisu (kwalifikowanego lub w postaci danych autoryzujących), przesłanie do bramki MF przez SOAP 1.2 i pobranie Urzędowego Poświadczenia Odbioru (UPO).

Co potrafi (TL;DR)

  • Buduje plik XML deklaracji bezpośrednio z danych wprowadzonych w formularzu.
  • Podpisuje XAdES-BES — algorytmem SHA-1 lub SHA-256 (RSA), w postaci kanonicznej C14N.
  • Obsługuje dwie metody autoryzacji: certyfikat kwalifikowany z magazynu Windows oraz dane autoryzujące (NIP/PESEL + przychód za rok N−2).
  • Wysyła do bramki produkcyjnej bramka.e-deklaracje.mf.gov.pl przez SOAP — z podpisem, bez podpisu, oraz z załącznikami (dla deklaracji CIT z dokumentami finansowymi).
  • Pobiera UPO osobnym żądaniem i archiwizuje je razem z deklaracją w bazie programu.
  • Obsługuje masową wysyłkę wielu zaznaczonych deklaracji w jednym oknie.
  • Pokazuje treść zwracaną przez bramkę MF w postaci kodu statusu i opisu, z dedykowanymi komunikatami dla najczęstszych błędów.

Wspierane deklaracje

Lista wynika ze schematów XSD dołączonych do programu (katalog ed/). Każda pozycja może występować w wielu wzorach (numer w nawiasie oznacza wersję wzoru z Ministerstwa Finansów), program automatycznie dobiera odpowiedni szablon XML dla wzoru zapisanego w dokumencie.

Deklaracje VAT

  • VAT-7 (do wzoru 20), VAT-7K (do wzoru 14), VAT-7D (do wzoru 8)
  • VAT-8 (do wzoru 12), VAT-9M (do wzoru 11), VAT-12 (do wzoru 4)
  • VAT-10 (do wzoru 7), VAT-11 (do wzoru 7), VAT-23 (do wzoru 3)
  • VAT-26 (wzór 2), VAT-27 / VAT-27K (do wzoru 2)
  • VAT-UE / VAT-UEK (do wzoru 5)
  • VAT-R (do wzoru 18), VAT-Z (do wzoru 6)
  • VAT-ZD, VAT-ZT, VAT-ZZ — zawiadomienia i wnioski VAT

Zeznania roczne PIT (osoby fizyczne)

  • PIT-28 (do wzoru 27), PIT-28/A, PIT-28/B
  • PIT-36 (do wzoru 32), PIT-36L (do wzoru 21), PIT-36S / PIT-36LS
  • PIT-37 (do wzoru 31)
  • PIT-38 (do wzoru 18)
  • PIT-39 (do wzoru 12)

Załączniki PIT

  • PIT/O, PIT/D, PIT/M, PIT/B, PIT/BR, PIT/IP, PIT/DS, PIT/Z, PIT/ZG, PIT/UZ, PIT/WZ, PIT/WZR, PIT-2K, PIT/SE, PIT/MIT, PIT/NZI, PIT/PM, PIT/TP, PIT/WOT

Deklaracje płatnicze i informacje PIT

  • PIT-11 (do wzoru 29) — informacja o przychodach
  • PIT-4R (do wzoru 13), PIT-8AR (do wzoru 14) — deklaracje roczne płatnika
  • PIT-8C (do wzoru 13), PIT-R (do wzoru 22)
  • PIT-16A (do wzoru 13), PIT-19A (do wzoru 11) — karta podatkowa i podatek tonażowy
  • PIT-OP (do wzoru 3) — oświadczenie 1% / 1,5%
  • PIT-40 (do wzoru 22), PIT-6 (do wzoru 11)

CIT

  • CIT-8 (do wzoru 34), CIT-8/O, CIT-8AB
  • CIT/D, CIT/BR, CIT/ST, CIT/M, CIT/TP, CIT/WZ

IFT i pozostałe

  • IFT-1 / IFT-1R (do wzoru 17), IFT-2 / IFT-2R (do wzoru 11)
  • NIP-2 (do wzoru 12), NIP-7, NIP-8, ZAP-3 (do wzoru 6)
  • PCC-3, ORD-ZU (uzasadnienie korekty)
  • DSF-1 (deklaracja o przychodach uzyskanych przez kontrolowane spółki zagraniczne)
  • SSE-R (specjalne strefy ekonomiczne), SPR/MT

Moduł e-Deklaracje nie wysyła deklaracji ZUS — dla ZUS używany jest osobny moduł z eksportem do KEDU dla programu Płatnik. Pliki JPK (JPK_V7, JPK_KR, JPK_FA itd.) przechodzą przez ten sam ekran wysyłki, ale po stronie bramki MF używają osobnej usługi e-dokumenty.mf.gov.pl/api/Storage — szczegóły w opisie modułu JPK.

Workflow wysyłki

  1. Utworzenie dokumentu — wybór typu deklaracji z węzła Dokumenty lub z menu. Formularz wypełniany ręcznie lub generowany automatycznie (np. PIT-11 z list płac, VAT-7 z ewidencji VAT).
  2. Generowanie XML — przycisk Wyślij otwiera okno wysyłki, które buduje XML dla konkretnej wersji wzoru. XML jest natychmiast pokazywany w podglądzie i można go zapisać do pliku (Zapisz e-deklarację).
  3. Wybór metody podpisu — przełącznik między Certyfikat kwalifikowany a Dane autoryzujące.
  4. Podpisanie — XML jest zamykany w strukturze XAdES-BES, kanonizowany (C14N) i podpisywany RSA-SHA256 (lub RSA-SHA1 w trybie zgodności).
  5. Wysyłka — SOAP 1.2 do https://bramka.e-deklaracje.mf.gov.pl/uslugi/dokumenty (lub osobnej operacji z załącznikami binarnymi — np. CIT z dokumentami finansowymi). Bramka zwraca numer referencyjny dokumentu (refId) oraz status wstępny.
  6. Pobranie UPO — przycisk Pobierz UPO wysyła żądanie z numerem referencyjnym. Jeśli przetwarzanie się zakończyło ze statusem 200, w odpowiedzi otrzymujemy XML UPO, który jest zapisywany w bazie razem z deklaracją (data otrzymania, treść poświadczenia).
  7. Archiwizacja — komplet danych (wysłany XML, status, opis statusu, refId, UPO, użyty certyfikat lub dane autoryzujące, kwota przychodu, data wysyłki, data odbioru UPO) zapisywany jest jako część rekordu raportu.

Podpisywanie deklaracji

Moduł obsługuje dwie metody autoryzacji dla e-deklaracji (dla samych JPK trzecią opcją jest Profil Zaufany).

Certyfikat kwalifikowany

  • Certyfikaty pobierane są z magazynu Windows i prezentowane na liście w oknie wysyłki.
  • Obsługiwany filtr Pokazuj tylko aktualne certyfikaty.
  • PIN podawany jest w polu formularza; opcja Zapamiętaj PIN — szyfrowany odpowiednio do danej sesji.
  • Można wymusić starszy algorytm SHA-1 dla zgodności z określonymi typami kart.
  • Bezpośredni skrót do menedżera certyfikatów systemu Windows (certmgr.msc) z przycisku Menedżer certyfikatów.

Dane autoryzujące (uproszczony podpis bez certyfikatu)

  • Stosowane dla zeznań rocznych osób fizycznych: PIT-37, PIT-36, PIT-36L, PIT-28, PIT-38, PIT-39 oraz wybranych formularzy płatniczych (PIT-11, PIT-OP).
  • Wymaga: NIP lub PESEL, imienia pierwszego, nazwiska, daty urodzenia oraz kwoty przychodu z zeznania za rok N−2 (np. dla deklaracji składanej w 2026 — przychód z PIT za 2024).
  • Dane są osadzane w wysyłanym dokumencie zgodnie ze standardem Ministerstwa Finansów dla podpisu danymi autoryzującymi, a wysyłka odbywa się w trybie bez podpisu kwalifikowanego.
  • Program ma funkcję Znajdź przychód — automatycznie wyszukuje kwotę z PIT za rok N−2 zapisany w bazie tego samego podatnika i podpowiada ją do pola autoryzacyjnego.
  • Wczytana kwota jest zapamiętywana między wysyłkami, więc kolejne deklaracje tego samego podatnika nie wymagają ponownego jej wpisywania.

Profil Zaufany — tylko JPK

Program zawiera kreator podpisu Profilem Zaufanym, który zapisuje plik metadanych, otwiera w przeglądarce https://moj.gov.pl/nforms/signer/upload?xFormsAppName=SIGNER i monitoruje katalog na podpisany plik. Ścieżka ta dostępna jest wyłącznie dla plików JPK — dla e-deklaracji opcja Profilu Zaufanego nie jest widoczna w oknie wysyłki.

Bramki MF i środowiska

Adresy używane przez program:

ŚrodowiskoURL bramki e-deklaracjiURL e-dokumenty (JPK)
Produkcjahttps://bramka.e-deklaracje.mf.gov.pl/uslugi/dokumentyhttps://e-dokumenty.mf.gov.pl/api/Storage
Testhttps://test-bramka.edeklaracje.gov.pl/uslugi/dokumentyhttps://test-e-dokumenty.mf.gov.pl/api/Storage

WSDL bramki produkcyjnej: https://bramka.e-deklaracje.mf.gov.pl/uslugi/dokumenty?wsdl. Schemat: https://bramka.e-deklaracje.mf.gov.pl/xsd.

W wydaniach produkcyjnych programu zawsze działa adres produkcyjny — środowisko testowe wykorzystywane jest wyłącznie wewnętrznie podczas rozwoju.

Statusy referencyjne

Bramka MF zwraca w odpowiedzi kod statusu i jego opis. Najczęstsze wartości obsługiwane przez program z dedykowanymi komunikatami:

StatusZnaczenie
100Błędny komunikat SOAP (chwilowy problem po stronie MF)
102Proszę o ponowne przesłanie żądania UPO
200Przetwarzanie zakończone poprawnie — UPO jest do pobrania
300Brak dokumentu w systemie (zły refId)
301-306Dokument w trakcie przetwarzania / weryfikacji podpisu
400Przetwarzanie zakończone błędem
401Dokument niezgodny ze schematem XSD
402Brak aktualnego pełnomocnictwa do podpisywania deklaracji
403Niepoprawny podpis
404-407Problemy z certyfikatem (nieważny / odwołany / nieprawidłowa ścieżka)
408Dokument zawiera błędy uniemożliwiające jego przetworzenie
411W systemie jest już złożony dokument z takim identyfikatorem
412Niezgodność danych autoryzujących z danymi w dokumencie
414Błąd w danych autoryzujących (np. nieprawidłowa kwota przychodu)
418Dla tego typu deklaracji wymagany jest podpis kwalifikowany
419Korekta bez zaznaczenia celu lub uzasadnienia

Dla błędów 412 i 414 program wyświetla rozszerzony komunikat z podpowiedzią — w szczególności sugeruje weryfikację kwoty przychodu za rok dwa lata wstecz. Pełna lista (60+ kodów) opisana jest w pomocy: Kody statusu e-deklaracji.

Korekty deklaracji

Korekta to ta sama deklaracja, w której pole Cel złożenia ustawiono na 2 — korekta. Dla większości deklaracji wymagane jest dołączenie załącznika ORD-ZU (uzasadnienie przyczyny korekty) — bramka MF odrzuca dokumenty bez ORD-ZU statusem 419.

Program zachowuje pełną historię wysyłek — każda kolejna korekta zapisywana jest jako osobny dokument w bazie, z własnym refId, UPO i statusem.

Wymagania techniczne

  • TLS 1.2 wymuszany jawnie dla wszystkich połączeń HTTPS z bramką (zarówno e-deklaracje, jak i JPK).
  • MSXML 6 — używany do operacji DOM (kanonizacja, walidacja struktury XML).
  • Magazyn certyfikatów Windows — certyfikaty kwalifikowane muszą być zainstalowane w bieżącym profilu użytkownika lub komputera.
  • Otwarte porty 443 do bramka.e-deklaracje.mf.gov.pl oraz e-dokumenty.mf.gov.pl (przy wysyłce JPK).
  • Sterowniki PKCS#11 / mini-driver karty kryptograficznej (dla podpisu kwalifikowanego z karty chipowej / tokenu USB).

Ograniczenia

  • Brak podpisu Profilem Zaufanym dla e-deklaracji — jest dostępny wyłącznie przy wysyłce plików JPK.
  • Dane autoryzujące ograniczone do osób fizycznych — bramka MF dla danego typu deklaracji może wymagać podpisu kwalifikowanego (status 418).
  • Niektóre starsze pola (np. PIT/Z, niektóre certyfikaty rezydencji) są blokowane przy wysyłce z komunikatem Pole "..." nie może być wypełnione przy wysyłaniu e-deklaracji — wymagają zerowania przed podpisaniem.
  • Nie ma wysyłki ZUS — KEDU eksportowane jest do programu Płatnika, który dalej wysyła zgłoszenia (zob. ZUS i Płatnik).

Powiązane