Średniozaawansowany25 minIntegracja

Migracja istniejących faktur do KSeF

Jak bezpiecznie przenieść historyczne faktury do Krajowego Systemu e-Faktur (schemat FA(3) obowiązujący od 2026), z wykorzystaniem REST API NaprawKSeF do walidacji wsadowej i autofix typowych błędów konwersji.

4321 wyświetleń1567 ukończonych1400 pomocne

Przed rozpoczęciem

Dostęp do archiwalnych faktur w formacie elektronicznym
Token autoryzacyjny KSeF
Zrozumienie wymagań prawnych dotyczących archiwizacji
Klucz API NaprawKSeF (format nk_live_*) z /dashboard/api-keys - dla walidacji wsadowej i autofix

Potrzebne narzędzia

System do konwersji faktur na XML FA(3)NaprawKSeF REST API + SDK TypeScript lub PHP (walidacja, autofix)Token KSeF

Kroki (7)

Zrozum wymogi prawne

WAŻNE: Nie wszystkie historyczne faktury muszą być migrowane do KSeF! - KSeF dotyczy NOWYCH faktur od daty obowiązku - Archiwalne faktury zachowują ważność w dotychczasowej formie - Migracja może być wymagana dla faktur korygowanych Skonsultuj się z księgowością przed migracją.

Oczekiwany rezultatWiesz, które faktury wymagają migracji.

Zinwentaryzuj faktury do migracji

Stwórz listę faktur wymagających migracji: - Faktury wymagające korekty - Faktury w trakcie procesowania - Faktury zgodnie z polityką firmy

Oczekiwany rezultatMasz kompletną listę faktur do migracji.

Przygotuj narzędzia konwersji

Wybierz metodę konwersji: - Automatyczna przez ERP (jeśli wspiera schemat FA(3)) - Dedykowane narzędzie do konwersji - Ręczna konwersja (dla małej liczby faktur) - Jeśli ERP konwertuje do starszego schematu (FA(1), FA(2)), użyj REST API NaprawKSeF do walidacji - błędy strukturalne wyjdą na warstwie pre-flight i nie trafią do produkcyjnego KSeF.

Oczekiwany rezultatMasz działające narzędzie do konwersji.

Skonwertuj faktury na format XML FA(3)

Przekształć faktury do formatu XML zgodnego ze schematem FA(3) - obowiązujący od 2026 roku wariant dla KSeF 2.0. Upewnij się, że wszystkie wymagane pola są wypełnione.

Struktura wymaganego XML FA(3):
<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza
      kodSystemowy="FA (3)"
      wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
  </Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>
    <FaWiersze>...</FaWiersze>
    <Platnosc>...</Platnosc>
  </Fa>
</Faktura>

Oczekiwany rezultatFaktury są skonwertowane do XML FA(3).

Zwaliduj skonwertowane XML wsadowo przez REST API

Zamiast walidować plik po pliku w UI walidatora, przy migracji wsadowej wywołaj REST API NaprawKSeF z poziomu skryptu migracyjnego - każda faktura przechodzi przez ten sam walidator XSD-lite plus reguły biznesowe FA(3). Jeśli organizacja ma włączone strict_xsd_enabled, dochodzi pełny libxml-wasm XSD pass. Dla typowych błędów konwersji (NIP malformed, brak P_22, niezgodność walut) wywołaj POST /api/v1/autofix - zwróci poprawioną wersję XML z listą zastosowanych poprawek. Pełna dokumentacja błędów: https://naprawksef.pl/errors. Pamiętaj o rate-limicie planu Pro/API (header X-RateLimit-Remaining w response) i o użyciu Idempotency-Key dla każdej faktury - bezpieczne retry przy timeoutach sieciowych.

# Walidacja wsadowa w pętli (bash + curl):
for xml in /tmp/migration/*.xml; do
  curl -X POST https://api.naprawksef.pl/api/v1/validate \
    -H "Authorization: Bearer $NK_API_KEY" \
    -H "Content-Type: application/xml" \
    -H "Idempotency-Key: migration-$(basename $xml .xml)" \
    --data-binary @"$xml" \
    -o "$xml.result.json"
done

# Autofix dla plików z błędami strukturalnymi:
curl -X POST https://api.naprawksef.pl/api/v1/autofix \
  -H "Authorization: Bearer $NK_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @broken.xml \
  -o fixed.xml

Oczekiwany rezultatWszystkie pliki XML przechodzą walidację - bądź zostały poprawione przez autofix.

Jeśli coś poszło nie takJeśli endpoint zwraca 429 - przekroczyłeś rate limit planu, header Retry-After mówi po jakim czasie ponowić. Rozłóż walidację w czasie albo zwiększ plan w /dashboard/billing.

Wyślij faktury partiami

Nie wysyłaj wszystkich faktur naraz! Podziel na partie: - Zacznij od kilku faktur testowych - Zwiększaj partię stopniowo - Monitoruj odpowiedzi KSeF - Rób przerwy między partiami Opcjonalnie: subskrybuj webhook invoice.validated z NaprawKSeF, żeby asynchronicznie reagować na wynik walidacji bez pollingu.

Zalecany rozmiar partii:
- Start: 5-10 faktur
- Po weryfikacji: 50-100 faktur
- Stabilna praca: max 500 faktur/partia

Przerwa między partiami: min 5 sekund
Rate limit NaprawKSeF (plan Pro/API): patrz /dashboard/api-keys i header X-RateLimit-Limit

Oczekiwany rezultatFaktury są wysyłane kontrolowanie, bez przeciążenia API.

Zweryfikuj i zachowaj potwierdzenia

Po każdej partii: - Pobierz UPO dla każdej faktury - Zweryfikuj poprawność danych w KSeF - Zapisz mapowanie: stary numer → numer KSeF - Zachowaj logi operacji (rate limit response headers, audit trail z NaprawKSeF dashboardu)

Oczekiwany rezultatWszystkie potwierdzenia są zapisane i zweryfikowane.

Ukończyłeś playbook?

Oznacz jako ukończony i podziel się opinią