Nieprawidłowy numer referencyjny JPK — co to oznacza i jak uniknąć błędów?

Co oznacza nieprawidłowy numer referencyjny JPK?

Kod statusu 300 oznacza, że Ministerstwo Finansów nie potrafi rozpoznać przesłanego numeru referencyjnego pliku JPK. To wskazuje na problem z identyfikacją dokumentu, niekoniecznie z jego zawartością. Przyczyn może być kilka:

• literówka,
• brak fragmentu numeru,
• błędne wklejenie do formularza UPO,
• zastosowanie niewłaściwego formatu identyfikatora (np. pomyłka w NIP albo PESEL).

Numer uznaje się za nieprawidłowy także wtedy, gdy:

• zawiera zbędne spacje,
• brakuje w nim znaków,
• zmieniono prefiks.

Skutki takiej pomyłki są istotne — system nie przypisze ani nie odnajdzie pliku w Rejestrze wysłanych dokumentów, przez co nie będzie możliwe dalsze przetwarzanie na serwerze MF. Aby naprawić sytuację, sprawdź numer w UPO oraz w systemie, z którego wysyłasz pliki (np. fillUp lub oprogramowanie ERP). Porównaj cały ciąg znaków, zwracając uwagę na NIP/PESEL i ewentualne spacje. Jeżeli znajdziesz błąd, popraw numer referencyjny w swoim systemie i wyślij plik ponownie. Gdy problem będzie się powtarzał, skontaktuj się z dostawcą oprogramowania lub zajrzyj do dokumentacji Ministerstwa Finansów, aby upewnić się co do prawidłowego formatu identyfikatora.

Dlaczego numer referencyjny może być nieprawidłowy?

Duplikacja numeru referencyjnego pojawia się, gdy ten sam identyfikator trafia do systemu wielokrotnie — wówczas Ministerstwo Finansów uznaje przesyłkę za duplikat i ją odrzuca. Częstą przyczyną jest błędne użycie formularza UPO: na przykład wklejenie UPO przeznaczonego do VAT-7 zamiast tego do JPK powoduje brak powiązania pliku z właściwym rejestrem. Problemy mogą też wynikać z korzystania ze starego oprogramowania, które nie spełnia obecnych wymagań MF — brak aktualizacji często prowadzi do błędów przy generowaniu numerów i podpisów.

Zmiana certyfikatu klucza publicznego po stronie MF albo użycie nieodpowiedniego certyfikatu również skutkuje błędami podpisu, np. gdy certyfikat jest nieważny, odwołany lub pochodzi od nieobsługiwanego dostawcy. Nieprawidłowe kodowanie znaków w XML (np. brak UTF-8) lub błędny format pliku łamią walidację schematu i uniemożliwiają rozpoznanie numeru referencyjnego. Podobny efekt daje zaszyfrowanie pliku przy użyciu niewłaściwego certyfikatu — serwer nie będzie w stanie odszyfrować zawartości.

Problemy z sesją przesyłania, takie jak timeouty czy przerwane połączenie, mogą prowadzić do częściowego zapisu metadanych i w konsekwencji do błędnego numeru referencyjnego. System może też zwracać kody z grup 3xx/4xx (np. 407 lub 412), które zwykle wskazują na duplikację lub na techniczne problemy związane z certyfikatem, formatem albo kodowaniem.

Aby rozwiązać te kwestie:

• użyj właściwego UPO do JPK,
• zaktualizuj oprogramowanie do najnowszej wersji,
• sprawdź ważność oraz wystawcę certyfikatu,
• upewnij się, że XML ma poprawne kodowanie (UTF-8).

W przypadku duplikatu wyślij plik ponownie z nowym numerem referencyjnym.

Jak sprawdzić status wysłanego pliku JPK?

Po pomyślnym wysłaniu pliku otrzymuje on status 200 — to oznacza, że przetwarzanie zakończyło się poprawnie i wygenerowano UPO. Status 100 informuje natomiast, że przetwarzanie nadal trwa. Pozostałe kody sygnalizują różne problemy techniczne lub walidacyjne.

Aby sprawdzić status wysłanego JPK, możesz skorzystać z kilku źródeł. Zacznij od systemu wysyłającego (np. fillUp lub oprogramowania ERP): sprawdź lokalne logi transmisji oraz komunikaty zwrotne i odszukaj numer referencyjny oraz kod odpowiedzi. Przejrzyj też rejestr wysłanych dokumentów, wyszukując po numerze referencyjnym, NIP/PESEL lub dacie przesyłki. Dodatkowo pobierz formularz UPO z Ministerstwa Finansów i porównaj numer referencyjny z wpisem w rejestrze.

Najważniejsze kody i ich znaczenie:

• 200 — przetwarzanie zakończone poprawnie, wygenerowano UPO,
• 100 — przetwarzanie w toku,
• 300 — nieprawidłowy numer referencyjny,
• 401 — dokument niezgodny ze schematem XSD,
• 404 — nieważny certyfikat,
• 407 — duplikat,
• 408 — błędy uniemożliwiające przetworzenie,
• 411 — identyczna deklaracja VAT już złożona,
• 419/420 — problemy z danymi autoryzującymi lub upoważnieniem.

Przy sprawdzaniu statusu warto wykonać kilka prostych kroków:

• Pobierz i zachowaj UPO oraz formularz UPO — to podstawowy dowód wysyłki,
• Jeśli wystąpi błąd, zapisz komunikaty SOAP i kody błędów, które pomogą w analizie,
• Porównaj numer referencyjny we wszystkich miejscach: w UPO, w rejestrze wysłanych dokumentów i w lokalnym systemie — błędne spacje, brak fragmentów lub zmieniony prefiks często prowadzą do statusu 300,
• W przypadku kodów 401 i 404 sprawdź walidację XML i ważność używanego certyfikatu,
• Przy statusie 407 upewnij się, że nie doszło do wysłania duplikatu.

Archiwizuj UPO oraz komunikaty Ministerstwa jako dowód i podstawę do dalszej analizy. Jeżeli wykryjesz błąd, popraw numer referencyjny i wyślij plik ponownie. Jeśli problem będzie się powtarzał, zaktualizuj oprogramowanie lub skonsultuj zapisy SOAP z dostawcą systemu.

Jak porównać numer referencyjny z UPO?

Aby sprawdzić numer referencyjny w UPO (PDF lub XML) przypisany do konkretnej wysyłki, postępuj według poniższych wskazówek:

1. Kopiuj i wklej — zamiast przepisywać, użyj funkcji kopiuj/wklej, aby zminimalizować ryzyko literówek. Porównaj skopiowany numer z zapisem w Rejestrze wysłanych dokumentów, fillUp lub w systemie ERP.
2. Sprawdź znak po znaku — zwróć uwagę na prefiksy, zera wiodące i znaki kontrolne. Oceń zarówno długość ciągu, jak i każdy poszczególny znak, aby wychwycić drobne różnice.
3. Skontroluj formatowanie — usuń niewidoczne spacje i znaki nowej linii oraz upewnij się, że plik PDF nie obcina końcówek numeru. Sprawdź też kodowanie (np. UTF-8) i wyeliminuj nietypowe znaki.
4. Zweryfikuj typ UPO — upewnij się, że dokument odnosi się do JPK_V7, a nie do deklaracji VAT (UPO VAT-7 ma inny kontekst i inne znaczenie).
5. Przeanalizuj komunikaty — sprawdź logi transmisji, raporty Ministerstwa oraz kody SOAP, gdy numer z UPO nie zgadza się z rejestrem. Tego typu różnice mogą wskazywać na przypisanie innego identyfikatora lub duplikat.
6. Wprowadź korekty — jeśli błąd się potwierdzi, zaktualizuj wpis w Rejestrze wysłanych dokumentów lub skontaktuj się z pomocą techniczną dostawcy oprogramowania albo z urzędem skarbowym.

Dodatkowa uwaga: przy podejrzeniu błędnego numeru NIP lub PESEL porównaj pola identyfikacyjne w UPO i w systemie źródłowym. Najczęstsze przyczyny błędów to kopiowanie fragmentów numeru, zmiana prefiksu lub problemy podczas wysyłki — analiza komunikatów Ministerstwa zwykle ujawnia źródło problemu.

Co oznaczają kody statusu 300 i 407?

Kod 300 oznacza, że podany numer referencyjny nie figuruje w Rejestrze wysłanych dokumentów lub został wprowadzony nieprawidłowo. Najczęściej winne są:

• literówki,
• brak fragmentu numeru,
• niepotrzebne spacje,
• zmieniony prefiks,
• użycie niewłaściwego UPO.

Przy sprawdzaniu statusu upewnij się, że numer w UPO zgadza się z tym w lokalnym rejestrze — skopiowanie wartości zamiast ręcznego wpisywania często eliminuje błąd. Gdy problem nadal występuje, przejrzyj logi transmisji (SOAP), sprawdź kodowanie XML i ważność certyfikatu, a następnie ponów wyszukiwanie statusu dokumentu.

Kod 407 informuje o duplikacie — ten sam numer referencyjny został już zarejestrowany, więc kolejna przesyłka została odrzucona. Przyczyny to m.in.:

• wielokrotne wysłanie pliku po timeoutach,
• ponowne użycie UPO,
• błędne generowanie numeru przez oprogramowanie.

Sprawdź Rejestr wysłanych dokumentów, aby ustalić, czy wcześniejsza przesyłka ma status 200 (przetworzone) lub inny kod. Jeśli dokument już istnieje, nie wysyłaj duplikatu: wykonaj korektę albo wygeneruj nowy numer referencyjny. W razie wątpliwości porównaj sumy kontrolne plików oraz daty/timestampy z wpisami w rejestrze, a przy potwierdzonym duplikacie skontaktuj się z dostawcą oprogramowania.

Kiedy występuje błąd po ręcznym dodaniu do Rejestru?

Błąd pojawiający się przy ręcznym dodawaniu dokumentów do Rejestru najczęściej wynika z niezgodności danych z UPO lub wpisami w systemie Ministerstwa. Najczęstsze problemy to:

• nieprawidłowy numer referencyjny (status 300),
• duplikat dokumentu (błąd 407),
• literówki w NIP/PESEL,
• brakujące lub dodatkowe znaki,
• niepotrzebne spacje,
• zmieniony prefiks numeru.

Równie często zdarza się błędnie wskazany typ dokumentu (np. przypisanie UPO VAT-7 zamiast JPK_V7) albo niepoprawny format daty (niezgodny z RRRR-MM-DD). Inny częsty powód to złe kodowanie pliku — wszystko inne niż UTF-8 może wywołać błędy. Uwaga na wklejanie z PDF: niewidoczne znaki, końcówki linii czy ukryte spacje przeniesione przy kopiowaniu potrafią spowodować odrzucenie wpisu. Problemy z uprawnieniami — brak aktualnego upoważnienia lub niezgodność danych autoryzacyjnych — mogą z kolei skutkować błędem 420 podczas weryfikacji. Pamiętaj też, że użycie już istniejącego numeru referencyjnego wygeneruje duplikat, nawet gdy treść pliku będzie inna niż w pierwotnym zgłoszeniu.

Aby zmniejszyć ryzyko błędów przy ręcznym dodawaniu do Rejestru, wykonaj proste kontrole:

• porównaj cały ciąg numeru referencyjnego z oryginalnym UPO,
• sprawdź pole identyfikacyjne (NIP/PESEL) znak po znaku,
• zweryfikuj typ dokumentu i format daty,
• przeszukaj Rejestr pod kątem duplikatów.

Zapisuj UPO i logi SOAP — przydadzą się jako dowód i do późniejszej weryfikacji.

Czy można skorygować wysłany dokument JPK?

Korektę składa się zawsze w przypadku błędu merytorycznego lub technicznego. Proces obejmuje kilka istotnych kroków, które warto wykonać po kolei:

1. przygotuj poprawny plik XML zgodny ze schematem XSD,
2. przed wysyłką zweryfikuj go lokalnie — wykonaj walidację XSD, by wychwycić błędy struktury,
3. dokument podpisz wymaganym podpisem elektronicznym: e‑podpisem, podpisem kwalifikowanym lub Profilem Zaufanym, gdy to konieczne,
4. sprawdź ważność szyfrowania i certyfikatów oraz ich zgodność z wymaganiami Ministerstwa Finansów,
5. nadaj korekcie nowy, unikalny numer referencyjny, unikając duplikatów, i wyślij ją ponownie jako korektę JPK_V7 lub korektę formularza,
6. zachowaj UPO, logi SOAP oraz kopie pliku — będą one dowodem wysyłki i podstawą do późniejszej weryfikacji.

Jeśli system zwróci kody takie jak 401, 412, 419 lub 404, usuń przyczynę odrzucenia: popraw XSD, szyfrowanie, dane uwierzytelniające lub certyfikat i spróbuj ponownie. W przypadku kodu 411, czyli gdy identyczna deklaracja JPK_V7 już istnieje, przygotuj odpowiednią dokumentację wyjaśniającą. Przed złożeniem korekty skoryguj także źródłowe ewidencje VAT. Dodatkowo upewnij się, że pełnomocnictwo oraz upoważnienie do podpisywania dokumentu są aktualne — ich brak może skutkować błędem 420. Przechowuj ewidencje VAT oraz dowody księgowe na wypadek kontroli podatkowej. W praktyce korzystaj z aktualnego oprogramowania do generowania JPK_V7, kopiuj numer referencyjny z UPO zamiast przepisywać go ręcznie i zawsze sprawdzaj kodowanie UTF‑8.

Jak uniknąć błędów numeru referencyjnego przy wysyłce?

Przed wysyłką wykonaj 10 kontroli, które pomogą zminimalizować ryzyko błędu numeru referencyjnego:

1. Sprawdź wersję oprogramowania. Zanotuj numer i datę aktualizacji u dostawcy (np. w fillUp lub ERP). Aktualizacje często usuwają problemy związane z certyfikatami i formatami, więc warto mieć to pod kontrolą.
2. Automatyzuj obsługę UPO. Unikaj ręcznego wpisywania danych — pobieraj i zapisuj potwierdzenia automatycznie; kopiowanie powinno być ostatecznością. Równocześnie archiwizuj UPO, komunikaty SOAP i logi sesji.
3. Waliduj XML lokalnie przed wysyłką. Użyj walidatora XSD (np. xmllint --noout --schema jpk_v7.xsd plik.xml) i sprawdź kodowanie pliku (echo -n | file -i plik.xml lub iconv -f utf-8 -t utf-8 plik.xml).
4. Zweryfikuj certyfikat publiczny. Sprawdź daty ważności i wystawcę (openssl x509 -noout -dates -in cert.pem). Gdy MF zmienia certyfikaty, konieczna jest aktualizacja konfiguracji po stronie integracji.
5. Kontroluj pola identyfikacyjne. NIP powinien mieć 10 cyfr, PESEL 11; porównaj każdy znak, usuń spacje i upewnij się, że pola nie zawierają nieprawidłowych zer wiodących.
6. Generuj unikalny numer referencyjny. Łącz datę/czas z UUID lub inkrementalnym ID i zapisuj mapowanie numer→hash pliku (sha256sum plik.xml). Hash ułatwi wykrywanie duplikatów dokumentów.
7. Sanityzuj ciągi tekstowe. Usuń niewidoczne znaki i nadmiarowe spacje, trimuj wartości i waliduj wzorcem (np. brak spacji, tylko dozwolone znaki alfanumeryczne). Sprawdź prefiksy i długość ciągu, a do testów użyj prostych poleceń (echo -n "numer" | wc -c).
8. Wprowadź retry z idempotencją. Przy timeoutach stosuj ponowne próby z nowym numerem lub z jednoznacznym tokenem idempotencyjnym, aby uniknąć zwrotów 407 (duplikat) lub innych niespójności.
9. Testuj w sandboxie. Przeprowadź próbne wysyłki i odczyt UPO w środowisku testowym; upewnij się, że statusy 200 i 100 są generowane zgodnie z oczekiwaniami przed wdrożeniem na produkcję.
10. Monitoruj i miej procedury obsługi błędów. Konfiguruj alerty na kody błędów (300, 407, 401, 404). W procedurze naprawczej: pobierz UPO, porównaj numer i NIP/PESEL, przeanalizuj logi SOAP i w razie potrzeby odtwórz przesyłkę z poprawnym numerem.

Dodatkowe wskazówki: wymuszaj UTF-8 przy eksporcie JPK, szyfruj plik właściwym certyfikatem i zapisuj znaczniki czasu transmisji. Przy integracji z ERP wdroż reguły wykrywania duplikatów oraz prawidłowego mapowania JPK_V7 względem deklaracji VAT. Stosowanie tych praktyk znacząco zmniejsza ryzyko błędów związanych z numerem referencyjnym oraz problemów typu 300 czy 407.