Jak oswoić KSeF?

Wyzwanie

Krajowy System e-Faktur (KSeF) to jedna z największych cyfrowych rewolucji dla polskich firm. Z jednej strony krok w przyszłość, z drugiej – nowe wyzwanie: ręczne pobieranie i archiwizowanie setek faktur każdego miesiąca. Żmudne i obarczone ryzykiem błędu, który w księgowości bywa kosztowny.

Był jeszcze drugi haczyk. Integrację z KSeF oferowały gotowe programy księgowe – ale żeby z niej skorzystać, trzeba było taki program kupić i wpiąć się w cudzy ekosystem. A ten klient miał własne systemy, dopasowane pod siebie. Nie chciał przepłacać za kolejne oprogramowanie tylko po to, żeby mieć jedną funkcję. Moim zadaniem było zbudowanie integracji wprost pod jego środowisko – cichego, automatycznego „pracownika” w PHP, który cyklicznie łączy się z KSeF i archiwizuje dokumenty tam, gdzie firma naprawdę ich potrzebuje.

Co zrobiłam

Najciekawszym problemem nie była sama komunikacja z API, ale elastyczność. Narzędzie musiało działać dla różnych konfiguracji: jedne firmy wolą prostszy token API, inne bezpieczniejszą pieczęć elektroniczną (certyfikat .p12).

Zamiast pisać dwa osobne programy albo gmatwać się w logice warunkowej, sięgnęłam po elegancki wzorzec projektowy – Fabrykę (Factory Pattern). Jedna inteligentna „fabryka” czyta plik konfiguracyjny i sama „produkuje” idealnie skonfigurowanego klienta API – z tokenem albo z certyfikatem. Kod jest czysty, a dodanie kolejnej metody uwierzytelniania w przyszłości będzie banalnie proste.

Całość oparłam o nowoczesny stos PHP 8.1+, z Composerem i biblioteką n1ebieski/ksef-php-client jako fundamentem komunikacji:

use N1ebieskiKSEFClientResourcesClientResource;
use N1ebieskiKSEFClientClientBuilder;

function createKsefClient(string $nip): ClientResource
{
    $clientBuilder = (new ClientBuilder())
        ->withMode($mode)
        ->withNIP($nip);
    // Fabryka sprawdza wybraną metodę uwierzytelniania
    $authType = strtolower($_ENV['KSEF_AUTH_TYPE'] ?? 'token');
    if ($authType === 'certificate') {
        $clientBuilder->withCertificatePath(
            $_ENV['PATH_TO_CERTIFICATE'],
            $_ENV['CERTIFICATE_PASSPHRASE']
        );
    } else {
        $clientBuilder->withApiToken($_ENV['KSEF_TOKEN']);
    }
    return $clientBuilder->build();
}

Efekt

Stresujący obowiązek zamienił się w niewidoczny, automatyczny proces. Zamiast godzin ręcznego pobierania faktur – pewność, że wszystkie dokumenty są archiwizowane na czas, bezbłędnie i w firmowych systemach, a nie w cudzym programie. System gwarantuje 100% kompletności danych, co jest bezcenne dla księgowości i raportów.

Najważniejsze: firma nie musiała kupować kolejnego oprogramowania tylko po to, żeby spełnić jeden wymóg. Dostała integrację skrojoną pod swoje środowisko – tańszą w utrzymaniu i w pełni pod jej kontrolą. Bo czasem najlepsze rozwiązanie to nie kolejny gotowy program, ale narzędzie dopasowane dokładnie do tego, co już masz.