Integracja systemu ERP z KSeF
Kompleksowy przewodnik integracji popularnych systemów ERP z Krajowym Systemem e-Faktur - z wykorzystaniem REST API NaprawKSeF jako pre-flight validation layer, gotowych presetów ERP (Trawers, Comarch Optima) i webhooks dla monitoringu.
Przed rozpoczęciem
- Dostęp administratora do systemu ERP
- Token autoryzacyjny KSeF (patrz: playbook generowania tokena)
- Środowisko testowe do weryfikacji integracji
- Klucz API NaprawKSeF (format nk_live_*) z /dashboard/api-keys - opcjonalnie, ale rekomendowane dla pre-flight validation
Potrzebne narzędzia
Kroki (13)
Zidentyfikuj możliwości integracji ERP
Sprawdź, czy Twój system ERP oferuje: - Wbudowany moduł KSeF (np. Comarch, Sage, SAP) - API do integracji zewnętrznej - Możliwość eksportu XML Skontaktuj się z dostawcą ERP w celu uzyskania dokumentacji.
Przygotuj środowisko testowe
Nigdy nie testuj integracji na produkcji! Przygotuj: - Kopię bazy ERP do testów - Token do środowiska testowego KSeF - Plan testów z różnymi scenariuszami
Bazowe adresy API KSeF 2.0:
- Testowe: https://api-test.ksef.mf.gov.pl/v2
- Demo: https://api-demo.ksef.mf.gov.pl/v2
- Produkcyjne: https://api.ksef.mf.gov.pl/v2Skonfiguruj połączenie z KSeF
W zależności od ERP, wprowadź: - URL środowiska KSeF - Token autoryzacyjny - Identyfikator podmiotu (NIP) - Certyfikat (jeśli wymagany)
Zmapuj pola faktur
Upewnij się, że wszystkie wymagane pola faktury KSeF są poprawnie mapowane z ERP: - Dane sprzedawcy i nabywcy - Pozycje faktury - Stawki VAT - Daty - Numery faktur Dla popularnych ERP (Trawers, Comarch Optima) NaprawKSeF udostępnia gotowe presety mapowań - patrz krok 6.
Wymagane pola w FA(3) (schemat KSeF 2026):
- <Podmiot1> - Sprzedawca
- <Podmiot2> - Nabywca
- <Fa> - Dane faktury
- <FaWiersze> - Pozycje
- <Platnosc> - Warunki płatności
Numer wariantu w nagłówku:
<KodFormularza>FA</KodFormularza>
<WariantFormularza>3</WariantFormularza>Skonfiguruj pre-flight walidację XML przez NaprawKSeF API
Zanim faktura trafi do produkcyjnego KSeF, wykonaj prewalidację XML. NaprawKSeF udostępnia REST API z kontrolą wybranych reguł FA(3) i opcjonalnym przebiegiem libxml. Repozytorium nie zawiera pełnego oficjalnego pakietu XSD, więc pozytywny wynik nie gwarantuje przyjęcia przez KSeF. Krok 1: Wygeneruj klucz API w /dashboard/api-keys. Krok 2: Wywołaj POST /api/v1/validate przed wysyłką. Krok 3: Obsłuż errors[] i potwierdź finalny XML pełnym oficjalnym XSD lub w środowisku KSeF 2.0.
curl -X POST https://api.naprawksef.pl/api/v1/validate \
-H "Authorization: Bearer nk_live_..." \
-H "Content-Type: application/xml" \
-H "Idempotency-Key: $(uuidgen)" \
--data-binary @faktura.xml
# Response (200 OK, bez pełnego XSD):
{
"data": {
"valid": false,
"preflight_ok": true,
"full_xsd_confirmed": false,
"readiness": "preflight_only_not_ready_to_send",
"issues": []
}
}Włącz preset ERP (Trawers, Comarch Optima lub własny)
Jeśli korzystasz z Trawers 7 (TRES) albo Comarch ERP Optima, NaprawKSeF udostępnia gotowe presety mapowań - bez konfiguracji po Twojej stronie. Preset tłumaczy wewnętrzne kody VAT ERP na wartości P_12 zgodne z FA(3) oraz pola JPK_V7M, plus obsługuje scenariusze specyficzne dla danego ERP (np. advance-jpk-reclassify dla Trawers). Dla integratorów innych ERP (Symfonia, Subiekt, Insert, custom) preset można dodać przez zgłoszenie - mapowania trafiają jako jeden seed do bazy, dostajesz dedykowany landing. Link do dokumentacji presetów: - Trawers: https://naprawksef.pl/integracja/trawers - Comarch Optima: https://naprawksef.pl/integracja/comarch - Zgłoś nowy preset: https://naprawksef.pl/integration-partners
# Użycie presetu w REST API (generator korekt FA(3)):
curl -X POST https://api.naprawksef.pl/api/v1/correction/build \
-H "Authorization: Bearer nk_live_..." \
-H "Content-Type: application/json" \
-d '{
"preset": "trawers-v7",
"source_xml": "<Faktura xmlns=...>...</Faktura>",
"scenario_id": "advance-jpk-reclassify",
"changes": [
{ "path": "Fa/FaWiersz/P_12", "new_value": "preset:vat:10" }
]
}'Przetestuj wysyłkę faktur
Wyślij testowe faktury do środowiska testowego KSeF: - Faktura standardowa - Faktura korygująca - Faktura z różnymi stawkami VAT - Faktura z załącznikami
Skonfiguruj pobieranie UPO
UPO (Urzędowe Poświadczenie Odbioru) jest dowodem wysłania faktury. Skonfiguruj automatyczne pobieranie i przechowywanie UPO.
// Przykład pobierania UPO
const upo = await ksefApi.getUPO(invoiceNumber);
await saveToDatabase(upo);
// UPO zawiera:
// - Numer referencyjny KSeF
// - Timestamp przyjęcia
// - Hash fakturySkonfiguruj obsługę faktur przychodzących
Jeśli ERP ma obsługiwać faktury zakupowe z KSeF: - Skonfiguruj automatyczne pobieranie - Zmapuj pola do systemu zakupowego - Ustaw workflow akceptacji
Ustaw monitoring i alerty (z webhooks NaprawKSeF)
Zamiast pollingu, skonfiguruj asynchroniczne webhooks NaprawKSeF - dostaniesz HMAC-signed event na swój endpoint za każdym razem gdy: - validation.completed - walidacja XML zakończona (payload zawiera is_valid, errors[], warnings[]; jeden event obsługuje zarówno sukces jak i błąd) - correction.created - wygenerowana została korekta FA(3) (payload: scenario_id, źródłowy numer, numer korekty) - quota.exceeded - przekroczyłeś miesięczny limit planu (good signal dla alertingu) - partner.trial_started / trial_ending_soon / trial_ended - lifecycle Magic Invite Trial dla integratorów Konfiguracja w /dashboard/webhooks. Każdy webhook ma signing secret (X-NK-Signature: t=<unix>,v1=<hex64>), retry z exponential backoff (do 6 prób), dashboard deliverability z replay one-click. SDK TS i PHP mają wbudowaną helper-funkcję do weryfikacji podpisu. Dodatkowo skonfiguruj alerty po stronie ERP/integracji o: - Błędach wysyłki do KSeF - Odrzuconych fakturach - Nowych fakturach przychodzących - Zbliżającym się wygaśnięciu tokena KSeF Monitoring uptime: użyj /api/v1/status?strict=1 (zwraca 503 jeśli platforma jest zdegradowana) w UptimeRobot / Better Stack / Pingdom. Pełen status: /status (publiczny dashboard).
// Weryfikacja podpisu webhook w Node (SDK TS):
import { verifyWebhookSignature } from '@naprawksef/sdk';
const valid = verifyWebhookSignature({
payload: rawBody,
signature: req.headers['x-nk-signature'],
secret: process.env.NK_WEBHOOK_SECRET,
});
if (!valid) return res.status(401).end();
const event = JSON.parse(rawBody);
if (event.type === 'validation.completed') {
// event.data.is_valid, event.data.errors, event.data.warnings
} else if (event.type === 'correction.created') {
// event.data.scenario_id, event.data.numer_korekty, event.data.delty
}Przeprowadź testy akceptacyjne
Przed uruchomieniem na produkcji: - Przetestuj wszystkie scenariusze użycia - Zweryfikuj poprawność danych w KSeF - Sprawdź wydajność przy większej liczbie faktur (NaprawKSeF planowo Pro/API obsługuje 1000+ req/min na klucz) - Potwierdź zgodność z księgowością - Sprawdź czy webhooks docierają i są poprawnie weryfikowane
Przejdź na produkcję
Po pomyślnych testach: 1. Wygeneruj produkcyjny klucz API NaprawKSeF (nk_live_*) w /dashboard/api-keys 2. Zmień token KSeF na produkcyjny 3. Zmień bazowy URL API KSeF 2.0 na produkcyjny (https://api.ksef.mf.gov.pl/v2) 4. Uruchom integrację w trybie pilotażowym (kilka faktur) 5. Monitoruj webhooks i dashboard /status przez pierwsze dni 6. Rozszerz na wszystkie faktury Uwaga: NaprawKSeF ma SLA 99.9% dla planów Pro/API - przy spadku poniżej w danym miesiącu kredyt serwisowy do kolejnej faktury jest wyliczany automatycznie z platform_health_checks i naliczany po weryfikacji miesięcznego raportu SLA, bez konieczności zgłaszania ticketu.
Udokumentuj i przeszkol zespół
Stwórz dokumentację: - Procedury operacyjne - Rozwiązywanie typowych problemów (link do https://naprawksef.pl/errors) - Kontakty eskalacyjne - Przyciski 'Replay webhook' i 'Rotate API key' w /dashboard Przeszkol zespół księgowości i IT. Dla integratorów wdrażających klientom końcowym: sprawdź Partner Program (https://naprawksef.pl/integration-partners) - revenue share, Magic Invite Trial dla klientów (14 dni Pro/API bez karty) i dedykowany SLA.
Ukończyłeś playbook?
Oznacz jako ukończony i podziel się opinią