Chorwackie przepisy dotyczące e-faktur z 2026 roku zmuszają programistów PHP do ponownego opracowania walidacji – plik Schematron wydany przez urząd skarbowy opiera się na XSLT 2.0, podczas gdy dominujący silnik XSLT w PHP obsługuje jedynie XSLT 1.0. Skutek: większość aplikacji księgowych nie jest w stanie przeprowadzić 62 obowiązkowych kontroli reguł biznesowych bez obejścia problemu, a odrzucona faktura może zatrzymać przepływy pieniężne w relacjach B2B.
Dlaczego ta bariera techniczna jest istotna
Od 1 stycznia 2026 r. każda transakcja B2B w Chorwacji musi być wymieniana jako e-Račun zgodny z 62 specyficznymi regułami walidacji. Urząd Skarbowy publikuje te reguły w formie pliku Schematron – jest to w istocie arkusz stylów XSLT 2.0, który flaguje naruszenia. Wbudowana w PHP biblioteka libxslt, która napędza popularne narzędzie xsltproc oraz większość pakietów Composer, implementuje jedynie XSLT 1.0. Bez wsparcia dla XSLT 2.0 nie można zastosować Schematronu, co oznacza, że system fakturowy oparty na PHP będzie albo generował faktury odrzucane przez portal podatkowy, albo będzie musiał korzystać z innego języka lub usługi.
Trzy ścieżki, którymi mogą podążyć programiści
| Opcja | Na czym polega | Praktyczne wady |
|---|---|---|
| Rozszerzenie SaxonC PECL | Instalacja procesora Saxon-C jako natywnego rozszerzenia PHP, a następnie bezpośrednie wywołanie Schematronu. | Rozszerzenie nie jest częścią typowego przepływu pracy Composer; budowanie i wdrażanie natywnych binariów na różnych serwerach zwiększa złożoność. |
| Zewnętrzna usługa walidacji | Wysłanie pliku XML do usługi webowej, która uruchomi Schematron w Twoim imieniu. | Każda faktura zależy teraz od opóźnień sieciowych i dostępności usługi; tymczasowa awaria może całkowicie zablokować fakturowanie. |
| Ponowna implementacja reguł w PHP | Przetłumaczenie 62 stwierdzeń Schematron na natywny kod PHP. | Wymaga początkowego wysiłku, ale po zakodowaniu walidator działa lokalnie, czysto integruje się z dowolnym stosem PHP i eliminuje zależności zewnętrzne. |
Ukryta logika, która myli proste implementacje
Naiwne tłumaczenie Schematronu może wciąż pomijać subtelną semantykę. Weźmy pod uwagę regułę HR-BR-4: „Termin płatności musi istnieć, jeśli kwota do zapłaty jest większa od zera”. Schematron definiuje zmienną, która mnoży kwotę faktury przez –1 w przypadku not kredytowych. W surowym formacie XML nota kredytowa wykazuje kwotę dodatnią, ale zmienna zmienia jej znak na ujemny, przez co warunek „większa od zera” staje się fałszywy. Jeśli walidator odczyta jedynie tekst stwierdzenia, odrzuci każdą notę kredytową.
Lekcja jest jasna: przeczytaj definicje zmiennych w Schematronie przed zakodowaniem odpowiadającego im warunku w PHP. Ten sam schemat pojawia się w kilku innych regułach, gdzie operacje arytmetyczne lub manipulacje ciągami znaków są ukryte za zmienną $.
Typowe przyczyny odrzuceń
Nawet przy poprawnie zakodowanych regułach, programiści często przeoczają elementy faktury, które system podatkowy traktuje jako błędy krytyczne:
- Brak danych operatora – każda faktura musi zawierać pełną nazwę operatora oraz numer OIB (chorwacki numer identyfikacji osobistej). Pozostawienie któregokolwiek z tych pól pustym skutkuje natychmiastowym odrzuceniem.
- Puste znaczniki XML – znaczniki takie jak
<cbc:Note></cbc:Note>powodują awarię walidatora. Usunięcie pustych elementów lub wypełnienie ich tekstem zastępczym rozwiązuje problem. - Nieprawidłowe kody KPD – kod Klasifikacija proizvoda i usluga (KPD) musi składać się z co najmniej sześciu cyfr. Krótsze kody są oznaczane jako błędne.
- Nieprawidłowe daty – każda faktura datowana przed 1 stycznia 2026 r. nie spełnia reguły obowiązkowej daty, niezależnie od pozostałej poprawności.
Pułapki testowania
Urząd Skarbowy publikuje przykładowe pliki e-Račun dla programistów. Przykłady te nadal zawierają daty z 2025 roku oraz numery OIB, które nie przejdą walidacji według zestawu reguł na rok 2026. Traktowanie ich jako jedynego źródła prawdy daje fałszywe poczucie zgodności. Przyjmij oficjalne próbki jedynie jako podstawowe sprawdzenie poprawności parsera, a następnie uruchom własny zestaw reguł na realistycznych danych generowanych przez Twoją aplikację.
Rozwiązanie wyłącznie w PHP, które jest już dostępne
Jeden z programistów zdecydował się na pełną reimplementację, pakując wszystkie 62 reguły walidacji jako bibliotekę możliwą do zainstalowania przez Composera w projektach Laravel. Biblioteka obsługuje arytmetykę, zakresy zmiennych oraz sprawdzenia przypadków brzegowych, które ukrywa Schematron, co pozwala na walidację faktur całkowicie w środowisku uruchomieniowym PHP. Dzięki wyeliminowaniu XSLT 2.0 i zewnętrznych wywołań, pakiet oferuje deterministyczną ścieżkę do zapewnienia zgodności o niskich opóźnieniach.
Kod źródłowy oraz instrukcja użycia są dostępne w publicznym repozytorium autora (link podany w oryginalnym poście).
Co dalej
- Walidatory PHP napędzane przez społeczność – w miarę jak coraz więcej programistów przyjmuje podejście oparte na reimplementacji, należy spodziewać się forków i rozszerzeń dodających zestawy testowe (unit-test fixtures), wsparcie dla innych frameworków lub poprawki wydajnościowe.
Podsumowanie
Chorwacki nakaz dotyczący e-faktur w 2026 roku zmusza programistów PHP do zmierzenia się z niedopasowaniem między nowoczesnym standardem XSLT 2.0 Schematron a przestarzałym silnikiem XSLT 1.0 tego języka. Przetłumaczenie 62 reguł biznesowych na natywny kod PHP, monitorowanie logiki ukrytych zmiennych oraz unikanie typowych pułapek XML pozwala na prowadzenie fakturowania wewnątrz firmy, pomaga uniknąć awarii związanych z siecią i przygotowuje oprogramowanie księgowe do sprawnego oraz zgodnego z przepisami wdrożenia, gdy nadejdzie termin.