Jak oswoić KSeF? Studium przypadku automatu w PHP, który pobiera faktury za Ciebie.

PrzezKinga Maleszewska

Wprowadzenie Krajowego Systemu e-Faktur (KSeF) to jedna z największych cyfrowych rewolucji dla polskich firm. Z jednej strony – krok w przyszłość. Z drugiej – nowe, potężne wyzwanie. Wyobraź sobie konieczność ręcznego pobierania i archiwizowania setek faktur sprzedażowych i zakupowych każdego miesiąca. To proces nie tylko żmudny, ale i obarczony ogromnym ryzykiem błędu, który w księgowości może być kosztowny.

Właśnie z takim wyzwaniem zgłosił się do mnie jeden z klientów. Potrzebował niezawodnego sposobu, by zdjąć z siebie ten nowy, uciążliwy obowiązek. Moim zadaniem było stworzenie cichego i niezawodnego pracownika – w pełni zautomatyzowanego narzędzia w PHP, które mogłoby cyklicznie, bez żadnej ingerencji człowieka, łączyć się z KSeF i archiwizować wszystkie dokumenty.

Wyzwanie architektoniczne: Elastyczność to podstawa

  • Najciekawszym problemem do rozwiązania nie była sama komunikacja z API, ale zapewnienie elastyczności. System musiał działać dla różnych firm, z których jedne chciały używać prostszego w obsłudze tokenu API, a inne – bardziej bezpiecznej, oficjalnej pieczęci elektronicznej (certyfikatu .p12).

    Zamiast pisać dwa oddzielne programy lub tworzyć skomplikowaną logikę warunkową, postawiłam na sprawdzone, eleganckie rozwiązanie architektoniczne – wzorzec projektowy Fabryki (Factory Pattern). Stworzyłam jedną inteligentną „fabrykę”, która czyta plik konfiguracyjny i na jego podstawie sama „produkuje” i zwraca idealnie skonfigurowanego klienta API – albo z tokenem, albo z certyfikatem. Takie podejście sprawiło, że kod jest czysty, a dodanie kolejnej metody uwierzytelniania w przyszłości będzie banalnie proste.

Serce automatu: Kod, który buduje właściwe połączenie

Całość oparłam o nowoczesny stos technologiczny w PHP 8.1+, z Composerem do zarządzania zależnościami i biblioteką n1ebieski/ksef-php-client jako fundamentem komunikacji. Kluczem jest jednak wspomniana „fabryka”. Poniższy fragment kodu pokazuje, jak na podstawie jednego ustawienia w konfiguracji, funkcja dynamicznie buduje klienta gotowego do pracy.


use N1ebieski\KSEFClient\Resources\ClientResource;
use N1ebieski\KSEFClient\ClientBuilder;
use N1ebieski\KSEFClient\ValueObjects\Mode;

function createKsefClient(string $nip): ClientResource
{
    // ... (ustawienie trybu: Test, Demo, Produkcja) ...

    $clientBuilder = (new ClientBuilder())
        ->withMode($mode)
        ->withNIP($nip);
    
    // Kluczowy moment: sprawdzam wybraną metodę uwierzytelniania
    $authType = strtolower($_ENV['KSEF_AUTH_TYPE'] ?? 'token');

    // "Fabryka" decyduje, jak zbudować obiekt klienta
    if ($authType === 'certificate') {
        $clientBuilder->withCertificatePath(
            $_ENV['PATH_TO_CERTIFICATE'],
            $_ENV['CERTIFICATE_PASSPHRASE']
        );
    } else {
        $clientBuilder->withApiToken($_ENV['KSEF_TOKEN']);
    }
    
    return $clientBuilder->build();
}

Efekt: Odzyskany czas i 100% pewności

Najważniejszy rezultat działania tego narzędzia to transformacja stresującego obowiązku w niewidoczny, w pełni automatyczny proces. Zamiast godzin spędzonych na ręcznym pobieraniu faktur, klient zyskał pewność, że wszystkie dokumenty są archiwizowane na czas i bezbłędnie.

To bezpośrednio przekłada się na oszczędność zasobów – czasu i pieniędzy. Zespół, który wcześniej musiał pilnować faktur, może teraz skupić się na zadaniach, które przynoszą realną wartość biznesową. System gwarantuje 100% kompletność danych, co jest bezcenne dla procesów księgowych i raportowych.

Ten projekt to dowód na to, że moim celem jest dostarczanie nie tylko działającego kodu, ale przemyślanych, niezawodnych i elastycznych narzędzi. Koncentracja na czystej architekturze i dobrej konfiguracji zaowocowała rozwiązaniem, które jest gotowe do wdrożenia w każdej firmie zmagającej się z wyzwaniami KSeF.

Twoja firma zmaga się z nowymi wymaganiami, które generują powtarzalną, ręczną pracę? Potrzebujesz zautomatyzować procesy związane z KSeF lub innymi systemami, aby odzyskać cenny czas?

Skontaktuj się ze mną, a wspólnie znajdziemy rozwiązanie dopasowane do Twoich potrzeb.

Zapraszam do kontaktu

Podobne wpisy