La regola croata sulle fatture elettroniche del 2026 costringe gli sviluppatori PHP a reinventare la validazione – il file Schematron dell'autorità fiscale si basa su XSLT 2.0, ma il motore XSLT dominante in PHP supporta solo XSLT 1.0. Il risultato: la maggior parte delle app di contabilità non può eseguire i 62 controlli obbligatori sulle regole di business senza un workaround, e una fattura rifiutata può bloccare il flusso di cassa B2B.
Perché l'ostacolo tecnico è importante
Dal 1° gennaio 2026, ogni transazione B2B in Croazia dovrà essere scambiata come un e-Račun conforme a 62 specifiche regole di validazione. L'Amministrazione Finanziaria pubblica tali regole sotto forma di file Schematron – essenzialmente un foglio di stile XSLT 2.0 che segnala le violazioni. La libreria integrata di PHP libxslt, che alimenta il popolare xsltproc e la maggior parte dei pacchetti Composer, implementa solo XSLT 1.0. Senza il supporto a XSLT 2.0, lo Schematron non può essere applicato, il che significa che un sistema di fatturazione basato su PHP produrrà fatture che il portale fiscale rifiuterà oppure dovrà ricorrere a un altro linguaggio o servizio esterno.
Tre strade percorribili dagli sviluppatori
| Opzione | Cosa comporta | Svantaggi pratici |
|---|---|---|
| Estensione PECL SaxonC | Installare il processore Saxon-C come estensione PHP nativa, quindi invocare direttamente lo Schematron. | L'estensione non fa parte del tipico flusso di lavoro di Composer; la compilazione e l'implementazione di binari nativi su server diversi aggiunge complessità. |
| Servizio di validazione esterno | Inviare l'XML a un web service che esegue lo Schematron per tuo conto. | Ogni fattura dipende ora dalla latenza di rete e dalla disponibilità del servizio; un'interruzione temporanea può bloccare completamente la fatturazione. |
| Re-implementare le regole in PHP | Tradurre le 62 asserzioni dello Schematron in codice PHP nativo. | Richiede uno sforzo iniziale, ma una volta codificato, il validatore gira localmente, si integra perfettamente con qualsiasi stack PHP ed elimina le dipendenze esterne. |
La logica nascosta che inganna le implementazioni semplici
Una traduzione ingenua dello Schematron può comunque trascurare sottili semantiche. Si prenda come esempio la regola HR-BR-4: "Deve esistere una data di scadenza se l'importo pagabile è superiore a zero". Lo Schematron definisce una variabile che moltiplica l'importo della fattura per –1 per le note di credito. In un XML grezzo, una nota di credito mostra un importo positivo, ma la variabile lo inverte in negativo, rendendo falsa la condizione "maggiore di zero". Se il validatore legge solo il testo dell'asserzione, rifiuterà ogni nota di credito.
La lezione è chiara: leggi le definizioni delle variabili nello Schematron prima di codificare la corrispondente condizione PHP. Lo stesso schema appare in diverse altre regole in cui manipolazioni aritmetiche o di stringhe si nascondono dietro una variabile $.
Comuni motivi di rifiuto
Anche con regole codificate correttamente, gli sviluppatori spesso trascurano elementi della fattura che il sistema fiscale tratta come errori fatali:
- Dettagli dell'operatore mancanti – ogni fattura deve contenere il nome completo dell'operatore e l'OIB (numero di identificazione personale croato). Lasciare vuoto uno qualsiasi di questi campi provoca un rifiuto immediato.
- Tag XML vuoti – tag come
<cbc:Note></cbc:Note>causano il crash del validatore. Rimuovere gli elementi vuoti o popolarli con una stringa segnaposto risolve il problema. - Codici KPD errati – il codice Klasifikacija proizvoda i usluga (KPD) deve avere almeno sei cifre. I codici troppo brevi vengono segnalati come malformati.
- Date non valide – qualsiasi fattura con data precedente al 1° gennaio 2026 fallisce la regola della data obbligatoria, indipendentemente dalla correttezza degli altri dati.
Trappole nei test
L'Amministrazione Finanziaria pubblica file e-Račun di esempio per gli sviluppatori. Quegli esempi contengono ancora date del 2025 e OIB che non superano il set di regole del 2026. Usarli come unica fonte di verità dà un falso senso di conformità. Considera i campioni ufficiali solo come un controllo di integrità del parser, quindi esegui la tua suite di controllo delle regole su dati realistici generati dalla tua applicazione.
La soluzione solo PHP già disponibile sul mercato
Uno sviluppatore ha portato a termine la strada della re-implementazione, confezionando tutte le 62 regole di validazione in una libreria installabile tramite Composer per progetti Laravel. La libreria gestisce l'aritmetica, lo scope delle variabili e i controlli sui casi limite che lo Schematron nasconde, consentendo la validazione delle fatture interamente all'interno dell'ambiente di runtime PHP. Eliminando XSLT 2.0 e le chiamate esterne, il pacchetto offre un percorso deterministico e a bassa latenza verso la conformità.
Il codice sorgente e la guida all'uso sono disponibili nel repository pubblico dell'autore (il link è fornito nel post originale).
Cosa monitorare in seguito
- Validatori PHP guidati dalla community – man mano che sempre più sviluppatori adottano l'approccio della reimplementazione, aspettatevi fork ed estensioni che aggiungano fixture per i test unitari, il supporto per altri framework o ottimizzazioni delle prestazioni.
In sintesi
L'obbligo di fatturazione elettronica della Croazia per il 2026 costringe gli sviluppatori PHP ad affrontare una discrepanza tra un moderno Schematron XSLT 2.0 e il motore legacy XSLT 1.0 del linguaggio. Tradurre le 62 regole di business in PHP nativo, monitorare la logica delle variabili nascoste ed evitare le comuni insidie dell'XML permette di gestire la fatturazione internamente, evita guasti legati alla rete e prepara i software di contabilità per un rilascio fluido e conforme quando arriverà la scadenza.