Sistem za izdajo računov za slovenska mala podjetja
Samogostovano PHP orodje za izdajo računov, zgrajeno za slovenska mala podjetja — UPN QR kode, skladnost z DDV/VAT, dva PDF generatorja in dostava po e-pošti. Preizkušeno v realnih poslovnih knjigah in pri strankah.
Pregled
Ta sistem za izdajo računov sem zgradil za slovenska mala podjetja — tista, ki izdajo nekaj deset računov na leto, morajo ostati skladna s slovenskimi pravili DDV/VAT in želijo samogostovano orodje, ki ne pošilja podatkov domov in jih ne zaklene v SaaS naročnino.
V produkciji teče od leta 2024 in pokriva realne cikle izdajanja računov. Obseg je namerno ozek: ustvari račun, generiraj skladen PDF z UPN QR kodo, ki jo strankina banka lahko skenira, in ga pošlji po e-pošti. Vse je nastavljivo prek spletnega vmesnika brez ogrodja — čisti PHP 8, JSON flat-file hramba in REST API, ki mi omogoča izdajanje računov tudi iz CLI ali drugih orodij.
Najtežji del ni bil vmesnik — bila je natančna izvedba UPN QR kode. Standard predpisuje točno določen 19-poljni payload v kodiranju ISO-8859-2, namensko kodo GDSV, plačilni sklic SI00, izpeljan iz številke računa, in 3-mestno kontrolno številko, ki šteje dolžine vseh polj plus znake nove vrstice med njimi. Vsaka slovenska bančna aplikacija to strogo preverja. Implementiral sem tudi sosednjo UPN-QR mikrostoritev kot samostojni Node.js/Express generator QR, ki sledi istemu standardu — uporabno za druge integracije.
Arhitektura
Branje diagrama: Računi vstopajo prek brskalniškega vmesnika ali REST API (avtenticiranega z API ključem). Razred InvoiceGenerator ureja celoten podatkovni model — datume, opombe o oprostitvi DDV, popuste po postavkah in generiranje UPN QR payloada. PDF-je izrisuje TCPDF (primarni) s samodejnim fallbackom na mPDF; QR koda je vdelana neposredno. Dokončani računi se hranijo kot JSON flat-file datoteke v imeniku izven web roota, dostava e-pošte pa gre prek PHPMailer 6, ki podpira tri načine pošiljanja. Vse se postavi v produkcijo prek GitHub → cPanel SSH.
Predogled računa
Stilizirani predogled generiranega PDF-ja — trikolonska glava, tabela postavk s popusti po postavkah, opomba o oprostitvi DDV, UPN QR koda (skenira jo katera koli slovenska bančna aplikacija) in plačilni sklic SI00, izpeljan iz številke računa.
Majhno ne pomeni enostavno za pravilno izvedbo. Slovensko izdajanje računov ima resnične zakonske zahteve in vsak PDF, ki gre ven, je pravni dokument.
Šest stvari dostavljenih,
tri težke rešene.
Ključni prispevki
- Zasnoval in implementiral celoten sistem za izdajo računov od začetka — spletni vmesnik, REST API, PDF pipeline, dostava po e-pošti in podatkovni sloj.
- Implementiral slovenski standard UPN QR: 19 polj v ISO-8859-2, plačilni sklic SI00, namenska koda GDSV in 3-mestna kontrolna številka.
- Zgradil PDF pipeline z dvema generatorjema (TCPDF + mPDF) s samodejnim fallbackom in ločeno flex-free mPDF predlogo za združljivost.
- Povezal skladnost z DDV/VAT za dva režima: domača oprostitev za mala podjetja (94. člen ZDDV-1) in EU obrnjena davčna obveznost (44. člen Direktive 2006/112/ES).
- Spravil v produkcijo nastavljivo pošiljanje e-pošte — php_mail, sendmail in polni SMTP prek PHPMailer 6 — z Markdown predlogami sporočil in PDF priponko.
- Postavil CI/CD iz GitHub na cPanel VPS prek SSH deploy ključev; podatkovne datoteke živijo izven web roota in se asinhrono varnostno kopirajo v sosednji privatni repozitorij.
Rešeni izzivi
- Slovenski standard UPN QR je strog: 19 polj ločenih z novo vrstico, zneski v centih, zapolnjeni z ničlami do 11 mest, vsebina v ISO-8859-2 in 3-mestna kontrolna številka, ki šteje vse znake za novo vrstico. En bajt narobe in vsaka bančna aplikacija ga zavrne.
- TCPDF in mPDF se različno obnašata s flexbox HTML — mPDF ga preprosto ignorira. Vzdrževanje dveh variant predloge brez podvajanja poslovne logike je zahtevalo čisto ločitev med izrisom podatkov in postavitvijo.
- cPanel deljeno gostovanje postavlja tesne omejitve: ni ozadnih workerjev, ni Redisa, privzeto ni pisljivega sistemskega tempa. Asinhrono varnostno kopiranje uporablja proc_open z bypass_shell tako na Windows (dev) kot Linux (prod) poteh.
Kaj poganja stvari.
Sorodni projekti
Pripravljeni popraviti, zgraditi
ali skalirati?
30 minut, z mano osebno. Preberem vaš sistem kot dnevniško datoteko in povem, kaj bi naredil najprej. Brez prezentacij, brez prodajnega lijaka.
— Davor Majc, ustanovitelj, Numen