1. Wyloguj się z systemu
2. Wyczyść cookies (domena *.gov.pl)
3. Zaloguj się ponownie przez Profil Zaufany
4. Sprawdź czy dane organizacji są aktualne
5. Wygeneruj nowy token API (jeśli używasz)

Błąd: "Brak uprawnień do operacji"

🔍 Przyczyny:

Nieprawidłowe przypisanie ról w organizacji
Osoba nie jest zarejestrowana jako upoważniona
Błędny NIP w danych autoryzacji

🛠️ Rozwiązanie:

1. Sprawdź role w Profilu Zaufanym
2. Weryfikuj czy jesteś wpisany jako reprezentant firmy
3. Skontaktuj się z administratorem organizacji
4. W razie potrzeby złóż wniosek o nadanie uprawnień

2. Błędy walidacji danych

Błąd: "Nieprawidłowy format NIP"

🔍 Najczęstsze przyczyny:

NIP z myślnikami (123-456-78-90)
NIP krajów UE w złym formacie
Literówki w numerze
Przestarzały NIP (firma nieaktywna)

🛠️ Rozwiązanie:

✅ Prawidłowy format: 1234567890 (tylko cyfry)
❌ Błędne formaty: 
   - 123-456-78-90 (z myślnikami)
   - 123 456 78 90 (ze spacjami)
   - PL1234567890 (z prefiksem kraju)

🔧 Narzędzie weryfikacji:

function validateNIP(nip) {
    // Usuń wszystkie znaki oprócz cyfr
    nip = nip.replace(/[^0-9]/g, '');
    
    // Sprawdź długość
    if (nip.length !== 10) return false;
    
    // Sprawdź sumę kontrolną
    const weights = [6, 5, 7, 2, 3, 4, 5, 6, 7];
    let sum = 0;
    
    for (let i = 0; i < 9; i++) {
        sum += parseInt(nip[i]) * weights[i];
    }
    
    return (sum % 11) === parseInt(nip[9]);
}

Błąd: "Nieprawidłowa stawka VAT"

🔍 Dozwolone stawki VAT w Polsce:

23% (standardowa)
8% (obniżona)
5% (obniżona)
0% (eksport, WDT)
zw. (zwolniona)
np. (nie podlega)

🛠️ Częste błędy:

❌ Błędne: 0.23 (format dziesiętny)
✅ Prawidłowe: 23 (format procentowy)

❌ Błędne: VAT 23%
✅ Prawidłowe: 23

Błąd: "Nieprawidłowy format daty"

🛠️ Wymagany format ISO 8601:

✅ Prawidłowe: 2025-01-15
❌ Błędne: 15.01.2025
❌ Błędne: 15/01/2025
❌ Błędne: 2025/01/15

3. Problemy techniczne

Błąd: "Timeout połączenia"

🔍 Przyczyny:

Wolne połączenie internetowe
Przeciążenie serwerów KSeF
Firewall blokuje połączenia
Problemy z DNS

🛠️ Diagnostyka połączenia:

# Test ping do serwerów KSeF
ping ksef.podatki.gov.pl

# Test traceroute
tracert ksef.podatki.gov.pl

# Test prędkości
speedtest-cli

# Sprawdź DNS
nslookup ksef.podatki.gov.pl

🛠️ Rozwiązania:

Sprawdź połączenie internetowe (min. 5 Mbps)
Zmień DNS na 8.8.8.8 lub 1.1.1.1
Wyłącz VPN jeśli używasz
Sprawdź firewall - porty 80, 443 muszą być otwarte
Spróbuj z innej lokalizacji (hotspot, inna sieć)

Błąd: "SSL Certificate Error"

🛠️ Rozwiązanie:

1. Sprawdź datę i czas w systemie
2. Zaktualizuj przeglądarkę do najnowszej wersji
3. Wyczyść certyfikaty SSL w przeglądarce
4. Sprawdź czy firma nie blokuje certyfikatów gov.pl
5. Spróbuj z innego urządzenia

4. Błędy integracji API

Błąd: "Invalid API Key"

🔍 Przyczyny:

Błędny klucz API
Klucz wygasł
Nieprawidłowy header autoryzacji
Klucz dla błędnego środowiska (test vs prod)

🛠️ Rozwiązanie:

# Prawidłowy header
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

# Test połączenia
curl -X GET "https://ksef.podatki.gov.pl/api/online/Session/Status" \
     -H "Authorization: Bearer YOUR_TOKEN"

Błąd: "Rate Limit Exceeded"

🔍 Limity API KSeF:

100 żądań/minutę na klucz API
1000 żądań/godzinę na organizację
10,000 żądań/dzień na klucz

🛠️ Implementacja retry mechanizmu:

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()
    
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
    )
    
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("http://", adapter)
    session.mount("https://", adapter)
    
    return session

5. Problemy z certyfikatami

Błąd: "Certyfikat wygasł"

🛠️ Sprawdzenie ważności certyfikatu:

1. Otwórz https://ksef.podatki.gov.pl
2. Kliknij ikonę kłódki w pasku adresu
3. Sprawdź "Certificate" → "Valid until"
4. Jeśli wygasł - nie jest to problem po Twojej stronie

🛠️ Certyfikat kwalifikowany:

1. Sprawdź ważność w oprogramowaniu certyfikatu
2. Odnów certyfikat przed wygaśnięciem
3. Upewnij się że certyfikat jest zainstalowany poprawnie
4. Test podpisu elektronicznego

Diagnostyka problemów - checklist

Przed zgłoszeniem do supportu:

✅ Podstawowe informacje

Jaki dokładnie błąd występuje?
Kiedy po raz pierwszy wystąpił?
Czy powtarza się zawsze czy sporadycznie?
Kto i gdzie go napotyka?

✅ Informacje techniczne

Jaka przeglądarka i wersja?
Jaki system operacyjny?
Czy używasz oprogramowania firm trzecich?
Screenshot błędu
Log files (jeśli dostępne)

✅ Kroki reprodukcji

Opisz krok po kroku co robiłeś
Jakie dane wprowadzałeś?
W którym momencie wystąpił błąd?
Czy próbowałeś obejść problem?

Kontakt z pomocą techniczną

📞 Infolinia KSeF: 22 330 03 30

Godziny pracy: Pn-Pt 7:00-22:00, Sb-Nd 8:00-18:00

💬 Czat online: dostępny na https://ksef.podatki.gov.pl

🎫 System zgłoszeń: przez Portal KSeF → "Pomoc"

Przewodnik escalacji problemów

1️⃣ Poziom 1 - Self-service (0-30 min)

Sprawdź ten przewodnik
Przeczytaj FAQ na stronie MF
Spróbuj podstawowych rozwiązań

2️⃣ Poziom 2 - Support online (30 min - 4h)

Użyj czatu lub formularza na stronie
Dołącz screenshoty i logi
Opisz dokładnie problem

3️⃣ Poziom 3 - Telefon (4h - 24h)

Zadzwoń na infolinię
Przygotuj numer referencyjny z poziomu 2
Miej dostęp do systemu podczas rozmowy

4️⃣ Poziom 4 - Eskalacja (24h+)

Jeśli problem blokuje biznes
Przez opiekuna klienta (firmy duże)
Kierownik infolinii

Monitoring i prewencja

Narzędzia monitoringu KSeF

Status page: https://ksef.podatki.gov.pl

Sprawdź przed rozpoczęciem ważnych operacji
Subskrybuj alerty o niedostępności
Planuj operacje poza okna maintenance

Własny monitoring API:

import requests
import json
from datetime import datetime

def check_ksef_health():
    try:
        response = requests.get(
            "https://ksef.podatki.gov.pl/api/online/Session/Status",
            timeout=10
        )
        
        if response.status_code == 200:
            return {"status": "OK", "timestamp": datetime.now()}
        else:
            return {"status": "ERROR", "code": response.status_code}
            
    except Exception as e:
        return {"status": "ERROR", "error": str(e)}

Backup procedury

Plan B gdy KSeF nie działa:

Dokumentuj wszystkie operacje (Excel/PDF)
Wystawiaj faktury w systemie lokalnym
Synchronizuj gdy system wróci do działania
Informuj klientów o sytuacji
Miej kontakt do księgowej na telefon

Najlepsze praktyki

✅ Do's

Regularnie backupuj dane
Testuj w środowisku demo przed produkcją
Śledź komunikaty MF o aktualizacjach
Szkolić zespół z obsługi błędów
Dokumentuj wszystkie problemy

❌ Don'ts

Nie ignoruj błędów walidacji
Nie używaj starych tokenów API
Nie modyfikuj faktur po wysłaniu do KSeF
Nie pozostawiaj problemów na "później"
Nie polegaj tylko na jednej osobie

90% problemów z KSeF to błędy konfiguracji lub danych. Większość można rozwiązać w kilka minut mając odpowiednią wiedzę. Kluczem jest systematyczne podejście do diagnostyki i dokumentowanie rozwiązań.

Pamiętaj: Lepiej spytać o pomoc wcześnie niż tracić godziny na szukanie rozwiązania samemu!

Plan wdrożenia KSeF 2.0: Kluczowe daty i etapy przejścia na e-faktury

Poznaj szczegółowy plan wdrożenia KSeF 2.0 od września 2025 do lutego 2026. Sprawdź kluczowe terminy i przygotuj swoją firmę na obowiązkowe e-faktury.