Ostatnia aktualizacja: 2026-10-07
- Model pośredni odpowiada przede wszystkim na presję terminu, ograniczone zasoby IT i potrzebę obsługi wielu systemów źródłowych.
- Integracja bezpośrednia lepiej pasuje do organizacji, która chce samodzielnie utrzymywać konektor i reagować na zmiany API.
- Przed wyborem pośrednika trzeba ocenić między innymi obsługiwane funkcje, statusy dokumentów, certyfikaty, tryby szczególne, SLA i możliwość migracji.
Definicja: Pośrednie API do KSeF to warstwa dostawcy między systemem firmy a oficjalnym API KSeF. W wielu usługach może ona przejąć część komunikacji technicznej, mapowania danych i walidacji, ale dokładny zakres odpowiedzialności zależy od konkretnej usługi.[9]
Pośrednie API i integracja bezpośrednia: gdzie przebiega różnica
W integracji bezpośredniej system firmy komunikuje się z oficjalnym API KSeF. Organizacja utrzymuje więc własny konektor i odpowiada za jego dopasowanie do procesów. W modelu pośrednim między systemem źródłowym a KSeF działa usługa dostawcy: system firmy przekazuje dane do jej API, a ona realizuje uzgodnioną część komunikacji z KSeF.
Oficjalne API KSeF wymaga uwierzytelnienia przed dostępem do chronionych zasobów.[1] Pośrednik może przejąć część technicznej obsługi tego połączenia, jednak nie należy zakładać, że każda usługa obejmuje ten sam zakres. Jedna może ograniczać się do przekazywania komunikatów, inna może również mapować dane, wykonywać walidację i obsługiwać część odpowiedzi systemu.
Pośredniego API nie należy utożsamiać z każdym programem mającym funkcję KSeF. Istotne jest to, czy dostawca pełni rolę bramy integracyjnej i które obowiązki rzeczywiście przejmuje. Na początku projektu dobrze jest rozpisać osobno odpowiedzialność firmy, pośrednika i KSeF za dostęp, dane, błędy, statusy oraz utrzymanie komunikacji.
Co firma utrzymuje przy bezpośredniej integracji z KSeF
Bezpośrednia integracja nie kończy się na przekazaniu danych faktury. Trzeba objąć procesem dostęp do API, przygotowanie danych zgodnych z wymaganą strukturą, analizę odpowiedzi, monitorowanie statusu oraz obsługę scenariuszy zwykłych i wyjątkowych.
Dostęp, uprawnienia i komunikacja z API
Własny konektor musi działać w ramach odpowiednio skonfigurowanego dostępu do KSeF. Firma powinna ustalić, kto zarządza uprawnieniami i uwierzytelnianiem oraz jak proces ma działać po zmianie konfiguracji. Pośrednik może obsługiwać część techniczną, lecz firma nadal odpowiada za dane, konfigurację uprawnień i działanie procesu po swojej stronie. Dokładny podział obowiązków wynika z architektury oraz umowy.[3]
Dane faktury, walidacja i obsługa odpowiedzi
KSeF 2.0 wykorzystuje strukturę FA(3), dlatego dane z systemu księgowego, ERP, sklepu lub platformy sprzedażowej trzeba właściwie odwzorować. Walidacja techniczna pomaga wykryć problemy ze strukturą, ale nie zastępuje kontroli poprawności danych biznesowych. Integracja powinna również odpowiednio obsłużyć wynik operacji, w tym błąd walidacji lub odrzucenie dokumentu.[5]
Plan nie powinien ograniczać się do faktur sprzedażowych. Musi uwzględniać także odbieranie faktur, jeśli proces firmy tego wymaga.[2] Oznacza to potrzebę określenia, do którego systemu mają trafiać odebrane dokumenty i jak będą powiązane z dalszą obsługą po stronie organizacji.
Statusy, odbiór dokumentów oraz scenariusze szczególne
System firmy powinien odróżniać przyjęcie danych przez własną aplikację lub pośrednika od wyniku operacji w KSeF. W procesie trzeba przewidzieć sprawdzanie statusów, ponowienie wysyłki oraz weryfikację, czy dokument uzyskał oczekiwany rezultat w KSeF.
Zakres integracji może obejmować także tryby szczególne i certyfikaty KSeF. Funkcje takie jak offline24 należy rozpatrywać zgodnie z potrzebami konkretnego procesu, ponieważ nie każda firma wykorzystuje wszystkie tryby w takim samym zakresie.[4] Przy wyborze pośrednika trzeba więc sprawdzić nie tylko podstawową wysyłkę, lecz także obsługę wymaganych certyfikatów, ponowień i statusów dokumentów.[6]
Kiedy pośrednie API ma więcej sensu niż własny konektor
Pośrednie API warto rozważyć wtedy, gdy ważniejsze od pełnej kontroli nad konektorem są szybkość wdrożenia, ograniczenie prac utrzymaniowych i ujednolicenie integracji. Jest to rekomendacja warunkowa: o wyborze powinny współdecydować wolumen, wymagania bezpieczeństwa, liczba systemów, koszty oraz zapisy umowy.[8]
Sygnały, że warstwa pośrednia będzie pomocna
- Zespół nie chce samodzielnie utrzymywać komunikacji z KSeF i reagować na zmiany po stronie API.
- Organizacja musi połączyć kilka systemów źródłowych i potrzebuje jednej warstwy komunikacyjnej.
- Termin projektu ogranicza możliwość zaprojektowania, wdrożenia i przetestowania własnego konektora.
- Firma chce przekazać dostawcy uzgodnioną część mapowania, walidacji i obsługi komunikatów.
Gdy przedmiotem projektu jest integracja KSeF z systemem erp, warstwa pośrednia może ujednolicić sposób przekazywania danych. Nie przesądza to jednak o wyborze: trzeba jeszcze ocenić zakres usługi, wymagania bezpieczeństwa i możliwość utrzymania alternatywnego rozwiązania.
Kiedy własna integracja może być uzasadniona
Bezpośrednia integracja jest bardziej uzasadniona, gdy organizacja świadomie chce utrzymywać cały konektor i ma do tego zasoby.[7] Taki model może odpowiadać firmie, która chce zachować kontrolę nad architekturą i jest przygotowana do samodzielnej obsługi zmian. Sama skala przedsiębiorstwa nie jest jednak wystarczającym kryterium.
| Kryterium | Sygnał na korzyść pośredniego API | Sygnał na korzyść integracji bezpośredniej |
|---|---|---|
| Zespół i utrzymanie | Ograniczone zasoby do stałego utrzymywania konektora | Zespół gotowy odpowiadać za cały konektor |
| Termin | Potrzeba ograniczenia zakresu własnych prac wdrożeniowych | Czas na zaprojektowanie i przetestowanie własnego rozwiązania |
| Liczba systemów | Potrzeba ujednolicenia komunikacji kilku źródeł | Istniejąca architektura integracyjna obsługująca te źródła |
| Kontrola architektury | Akceptacja uzgodnionej warstwy dostawcy | Potrzeba samodzielnego kontrolowania całego połączenia |
| Zmiany i utrzymanie | Przekazanie części prac technicznych pośrednikowi | Gotowość do samodzielnego reagowania na zmiany API |
| Zależność od dostawcy | Akceptowalne warunki eksportu, migracji i SLA | Brak akceptacji dla zależności od zewnętrznej bramy |
Pośrednik może zmniejszyć zakres kodu utrzymywanego przez firmę, ale przenosi część ryzyka na relację z dostawcą. Nie da się stwierdzić przewagi jednego modelu bez analizy architektury, umowy i całkowitego kosztu obejmującego nie tylko uruchomienie, lecz także utrzymanie, zmiany i ewentualną migrację. Właściwy dla firmy termin obowiązku KSeF również wymaga ponownego sprawdzenia przed wdrożeniem.
Czego pośrednie API nie rozwiązuje i jak ocenić dostawcę
Pośrednik nie przejmuje automatycznie całej odpowiedzialności za proces fakturowania. Firma nadal musi kontrolować dane biznesowe, uprawnienia, konfigurację swoich systemów oraz sposób postępowania w razie błędu. Umowa i projekt architektury powinny jednoznacznie wskazywać, za co odpowiada każda strona.
Odpowiedzialność za dane i dostęp do KSeF
Dostawca może przeprowadzić walidację techniczną albo mapowanie danych, ale nie oznacza to automatycznego wykrywania wszystkich błędów biznesowych. Trzeba ustalić, gdzie odbywa się kontrola danych, kto zarządza dostępem oraz jakie informacje są przechowywane w usłudze pośredniej.
Dostępność, incydenty i obsługa błędów
SLA dostawcy opisuje działanie jego usługi, a nie dostępność samego KSeF. Ocena oferty powinna zatem objąć sposób rozróżniania awarii pośrednika, problemu w systemie firmy i niedostępności KSeF. Istotne są również zasady kolejkowania operacji, ponawiania wysyłki, raportowania błędów i przekazywania statusów.
Migracja, eksport danych i zależność od dostawcy
Warstwa pośrednia staje się częścią krytycznego procesu, dlatego trzeba ocenić możliwość zakończenia współpracy. Sama dostępność API nie gwarantuje łatwego przeniesienia integracji. Znaczenie mają format eksportu, dostęp do historii operacji, dokumentacja mapowania i zasady odzyskania danych.
- Zakres funkcji: czy usługa obsługuje wysyłkę, odbiór, statusy, odrzucenia i ponowienia wymagane w procesie firmy?
- FA(3) i mapowanie: kto odpowiada za odwzorowanie danych i aktualizację reguł?
- Certyfikaty i tryby szczególne: czy rozwiązanie obsługuje scenariusze rzeczywiście potrzebne organizacji?
- Uprawnienia: gdzie są konfigurowane i kto kontroluje dostęp?
- SLA i incydenty: jak dostawca zgłasza awarie, przekazuje informacje i obsługuje zaległe operacje?
- Statusy: czy można odróżnić przyjęcie danych przez pośrednika od wyniku w KSeF?
- Dane: jaki jest zakres ich przechowywania oraz możliwość eksportu?
- Migracja: jak wygląda przejście do własnego konektora albo innego usługodawcy?
Jak podjąć decyzję i zweryfikować ją w pilotażu
Ostatecznego wyboru nie da się uczciwie dokonać bez danych o systemach źródłowych, procesach, zasobach IT, wymaganiach bezpieczeństwa, wolumenie oraz warunkach konkretnej oferty. Nie istnieje też uniwersalny próg, od którego jeden model staje się bardziej opłacalny.
Pilotaż powinien obejmować zarówno zwykły przepływ dokumentu, jak i sytuacje wyjątkowe. Jego celem nie jest jedynie potwierdzenie, że można wysłać fakturę, lecz sprawdzenie całego procesu, podziału odpowiedzialności i dostępności potrzebnych informacji.
- Spisz procesy i systemy źródłowe. Ustal, skąd pochodzą dane, gdzie mają trafiać odebrane dokumenty i kto odpowiada za ich poprawność.
- Przypisz odpowiedzialność. Rozdziel zadania między firmę, dostawcę i KSeF, uwzględniając dostęp, mapowanie, błędy, statusy i utrzymanie.
- Przetestuj podstawowy przepływ. Zweryfikuj wysyłkę, odbiór oraz dostępność statusu dokumentu.
- Wywołaj scenariusze błędne. Sprawdź reakcję na niepoprawne dane, odrzucenie i potrzebę ponowienia operacji.
- Sprawdź wymagane tryby szczególne. Testuj certyfikaty i offline24 wyłącznie wtedy, gdy są częścią procesu organizacji.
- Zweryfikuj możliwość wyjścia. Wykonaj próbny eksport danych i oceń, czy dokumentacja pozwala przenieść integrację.
- Oceń działanie operacyjne. Monitoruj kompletność statusów, liczbę błędów oraz czas potrzebny na obsługę wyjątków.
Po pilotażu decyzja powinna wynikać z tego, który model pozostawia akceptowalny zakres odpowiedzialności i ryzyka. Przed pełnym wdrożeniem trzeba ponownie zweryfikować aktualne terminy oraz wymagania KSeF, ponieważ dokumentacja i zasady systemu mogą podlegać zmianom.
Źródła
- KSeF API (PR) – dokumentacja, Ministerstwo Finansów.
- Zakres obowiązkowego KSeF, Ministerstwo Finansów.
- Pytania i odpowiedzi KSeF 2.0, Ministerstwo Finansów.
- Certyfikaty KSeF, Ministerstwo Finansów.
- Podręcznik KSeF 2.0, część II: Wystawianie i otrzymywanie faktur, Ministerstwo Finansów.
- Integratorzy IT, Ministerstwo Finansów.
- KSeF przez API – kiedy własna integracja ma sens, CodeCollab.
- Modele integracji: bezpośrednio z KSeF czy przez dostawcę?, KiedyKSeF.pl.
- Integracja z API KSeF – jak to działa i jak wdrożyć ją w swojej firmie, KSeF Service.
+Artykuł Sponsorowany+
