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
Środowiska KSeF:
- Testowe: https://ksef-test.mf.gov.pl
- Demo: https://ksef-demo.mf.gov.pl
- Produkcyjne: https://ksef.mf.gov.plSkonfiguruj 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 poleci do produkcyjnego KSeF, waliduj XML po swojej stronie - to redukuje rejecty, koszt supportu i "pilne" poprawki pod presją czasu. NaprawKSeF udostępnia publiczne REST API z walidacją XSD-lite, regułami biznesowymi FA(3) i opcjonalną pełną walidacją XSD przez libxml-wasm (per-org flag strict_xsd_enabled). Krok 1: Wygeneruj klucz API w /dashboard/api-keys (format nk_live_*, 30 sekund). Krok 2: Z poziomu ERP (lub middleware integracyjnego) wywołaj POST /api/v1/validate przed każdą wysyłką do KSeF. Krok 3: Obsłuż response - errors[] zawiera kod, message, line i ścieżkę XPath każdego problemu. SDK TypeScript: npm install @naprawksef/sdk SDK PHP: composer require naprawksef/sdk OpenAPI 3.1: https://naprawksef.pl/openapi.json
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):
{
"is_valid": true,
"errors": [],
"warnings": [
{ "code": "KSEF-W-001", "message": "...", "xpath": "/Faktura/Fa/P_22" }
],
"strict_xsd_applied": false
}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: - invoice.validated - walidacja XML zakończona (sukces lub błąd) - invoice.failed - walidacja zwróciła błędy strukturalne - correction.created - wygenerowana została korekta FA(3) - correction.ready - korekta przeszła walidację i jest gotowa do wysyłki Konfiguracja w /dashboard/webhooks. Każdy webhook ma signing secret (X-NK-Signature), automatic retry z exponential backoff i 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 === 'invoice.validated') {
// event.data.is_valid, event.data.errors, event.data.warnings
}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ń URL KSeF na produkcyjny (https://ksef.mf.gov.pl) 4. Uruchom integrację w trybie pilotażowym (kilka faktur) 5. Monitoruj webhooks i dashboard /platform-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 automatycznie dostajesz credit w Stripe na następną fakturę, bez konieczności zgłaszania.
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ą