VOS: platforma shqiptare e fiskalizimit dhe e kontabilitetit

Sfida: një faturë nuk është e vlefshme derisa ta thotë Administrata Tatimore

Ligji shqiptar detyron çdo tatimpagues ta transmetojë çdo faturë te Administrata Tatimore në çastin që lëshohet. Fatura nuk është ligjërisht e vlefshme derisa Platforma Qendrore e Faturave të kthejë kodet e saj. Në praktikë një biznes nuk mund thjesht të printojë një kupon: i duhet një certifikatë dixhitale e kualifikuar, një program që ndërton saktësisht XML-in që kërkon autoriteti, një nënshkrim dixhital XML dhe një lidhje aktive, e gjitha brenda sekondash nga momenti që klienti paguan. Çdo lloj dokumenti ka rregullat e veta, arkat duhet të regjistrohen si pajisje dhe të hapen e mbyllen çdo ditë, dhe kur lidhja bie faturat duhet prapëseprapë të lëshohen e më pas të rakordohen brenda një afati ligjor. Veç kësaj, librat duhen mbajtur gjithsesi. Portali falas i qeverisë mbulon minimumin për tatimpaguesit më të vegjël dhe lë të pazgjidhur kontabilitetin, rastin me disa biznese dhe çdo integrim me sistemet e vetë biznesit. Ajo hapësirë është produkti.

Specifikimi që zbaton VOS është ai i vetë autoritetit, i ndjekur përmes nëntë rishikimeve të publikuara. VOS e shpjegon procesin që automatizon te si funksionon fiskalizimi në Shqipëri.

• Regjistrim në kohë reale te Administrata Tatimore para se fatura të jetë ligjërisht e vlefshme
• Një certifikatë dixhitale e kualifikuar për çdo biznes, e marrë, e ngarkuar dhe e rinovuar
• Katër lloje dokumentesh të ndryshme, secili me skemën dhe rregullat e veta
• Arka të regjistruara si pajisje, të hapura e të mbyllura çdo ditë, me lëvizjet e parave të regjistruara
• Një afat ligjor për të rakorduar faturat e lëshuara ndërkohë që lidhja ishte e ndërprerë
• Një specifikim teknik që autoriteti e ka rishikuar nëntë herë deri tani

Zgjidhja jonë: shtatë sipërfaqe, nga banaku te libri i kontabilistit

VOS është një platformë e vetme e shpërndarë në shtatë hoste publike. Paneli i klientit është vendi ku biznesi vepron vërtet: një panel arke, një ekran fature e shpejtë për shpejtësi në banak dhe flukse të plota për çdo lloj dokumenti që përcakton ligji. Këto janë fatura e thjeshtë që merr konsumatori, fatura elektronike që shkëmbehet mes bizneseve, fleta shoqëruese që udhëton bashkë me mallin, dhe vetëfaturimi. Krahas tyre qëndrojnë menaxhimi i arkave, inventari dhe magazinat, blerjet dhe llogaritë e operatorëve. Portali i kontabilitetit është gjysma më e madhe dhe pjesa me më pak konkurrencë në tregun shqiptar: plani kombëtar i llogarive në shtatë klasat e tij ligjore, një ditar me partidë të dyfishtë që nuk regjistron derisa të dalë barazimi, mbyllja e periudhave mujore, rakordimi bankar me një asistent importi CSV, Libri i Blerjeve dhe Libri i Shitjeve, dhe një katalog me 42 raporte në 11 seksione. Kontabilisti punon për të gjithë klientët nga një vend i vetëm. Rreth këtyre dyve qëndrojnë një konsolë administrimi, një API REST e dokumentuar, një faqe dokumentacioni e shkruar shqip, një demo publike pa regjistrim, dhe një aplikacion celular që shton bllokim biometrik, njoftime push dhe skanim me kamerë në vend që të rishkruajë ndërfaqen.

Tre llojet e dokumenteve të fiskalizuara jepen te faqja e zgjidhjeve të VOS, dhe ana e kontabilistit te portali i kontabilitetit për kontabilistët.

• Panel klienti: arkë, faturë e shpejtë dhe një fluks i plotë për çdo lloj dokumenti
• Fatura e thjeshtë, fatura elektronike, fleta shoqëruese dhe vetëfaturimi, secila me skemën e vet
• Portal kontabiliteti: plani kombëtar i llogarive, partidë e dyfishtë, mbyllje periudhash, rakordim
• Libri i Blerjeve dhe Libri i Shitjeve, plus 42 raporte në 11 seksione
• Konsolë administrimi, API REST, dokumentacion shqip dhe demo publike
• Aplikacion celular me bllokim biometrik, njoftime push dhe skanim me kamerë

Teknologjia dhe arkitektura: si fiskalizohet vërtet një faturë

Teknologjia është një monorepo me Yarn workspaces mbi Turborepo: një API në Fastify dhe TypeScript, PostgreSQL përmes Prisma me Redis për cache dhe kufizim kërkesash, aplikacione web në Next.js dhe React, një faqe marketingu Vite e parandërtuar, dokumentacion në Docusaurus dhe një guaskë celulare Expo, në punë mbi k3s pas Traefik dhe Cloudflare. Fiskalizimi i një fature ka gjashtë hapa. Certifikata PKCS#12 e biznesit ngarkohet dhe numri i identifikimit tatimor lexohet nga vetë certifikata, jo nga çfarë shkruan përdoruesi. Kodi i brendshëm i faturës ndërtohet nga një varg kanonik me lëshuesin, kohën, numrin e faturës, njësinë e biznesit, kodin e arkës, kodin e programit dhe totalin, i merret digest-i, nënshkruhet me çelësin privat të biznesit dhe hash-ohet; kodi dhe nënshkrimi i tij dalin nga një kalim i vetëm nënshkrimi, kështu që të dy nuk mund të shkëputen kurrë. Dokumenti i kërkesës ndërtohet sipas skemës së autoritetit dhe i mban të gjitha shumat në qindarka leku, kështu që vlera pa tatim plus TVSH-ja jep saktësisht totalin. Kërkesa nënshkruhet me nënshkrim dixhital XML, shkëmbehet me Platformën Qendrore të Faturave përmes mutual TLS, dhe kërkesa e përgjigjja e nënshkruara arkivohen në një tabelë të vetën për ruajtjen që kërkon ligji, ndarë nga rreshti i faturës që ngarkesat e mëdha të mos rëndojnë kërkesat e zakonshme. Zbatohen pesëmbëdhjetë veprime të ndryshme me Administratën Tatimore në katër shërbime web të ndryshme shtetërore, dhe faturat elektronike gjenerohen gjithashtu si UBL 2.1 sipas standardit europian EN 16931.

Sipërfaqja e integrimit është e dokumentuar publikisht, në shqip, te faqja e dokumentacionit të VOS.

• API në Fastify dhe TypeScript, PostgreSQL përmes Prisma, Redis, Next.js dhe React, k3s
• Certifikata ngarkohet nga PKCS#12, NIPT-i lexohet nga certifikata, kurrë nga inputi
• Kodi i faturës dhe nënshkrimi dalin nga një kalim i vetëm, kështu nuk shkëputen dot
• Të gjitha shumat në qindarka leku, kështu që llogaritja e TVSH-së del saktësisht
• Nënshkrim dixhital XML dhe mutual TLS drejt Platformës Qendrore të Faturave
• Pesëmbëdhjetë veprime me Administratën Tatimore në katër shërbime web shtetërore

Çfarë dorëzuam: gjerësi dhe thellësi, dhe një platformë që është në punë

Këtu një rast studimi zakonisht raporton përdorimin. VOS nuk ka ende çfarë të raportojë, sepse dalja komerciale nuk ka filluar, dhe preferojmë ta themi këtë sesa të huazojmë një shifër. Ajo që mund të matet është gjerësia dhe gjendja e gjësë. Depoja përmban 312,209 rreshta kod të shkruar me dorë në 1,970 skedarë, plus edhe 238,707 rreshta testesh në 1,423 skedarë; në API rreshtat e testeve janë thuajse saktësisht sa rreshtat e kodit. API deklaron 647 endpoint, nga të cilat rreth 607 janë të arritshme. Modeli i të dhënave shkon në 98 modele dhe 87 enum, me një ndarje mes bizneseve që është strukturore dhe jo thjesht marrëveshje: 69 modele e mbajnë identifikuesin e biznesit drejtpërdrejt, të mbështetur nga 98 indekse të përbëra. Në të gjithë platformën ka 219 faqe, konkretisht 127 ekrane aplikacioni, 49 faqe marketingu dhe 43 faqe dokumentacioni, këto të fundit të gjitha shqip. U ndërtua nga tre veta gjatë nëntë muajve aktivë dhe 603 commit-eve. Të shtatë hostet janë aktive dhe të shëndetshme, hostet e aplikacionit kthejnë siç duhet noindex, dhe hostet e vjetër të markës së mëparshme ridrejtojnë. Dalja në treg sapo po fillon.

Platforma mund të provohet pa regjistrim te demoja e drejtpërdrejtë e VOS, dhe vetë produkti ndodhet te VOS, platforma e fiskalizimit, e cila publikon edhe mjete falas si kalkulatori i TVSH-së dhe verifikimi i faturës.

• 312,209 rreshta kod i shkruar me dorë, plus 238,707 rreshta teste
• Rreth 607 endpoint API të arritshme nga 647 të deklaruara, në 99 skedarë rrugësh
• 98 modele të dhënash dhe 87 enum, me ndarjen mes bizneseve të siguruar nga 98 indekse të përbëra
• 219 faqe: 127 ekrane aplikacioni, 49 faqe marketingu, 43 faqe dokumentacioni shqip
• 603 commit gjatë nëntë muajve aktivë, nga tre veta
• Shtatë hoste publike aktive dhe të shëndetshme; dalja komerciale sapo po fillon

Çfarë thotë ky rast studimi për punën me Square

Një fushë e rregulluar me ligj i ndëshkon shprehitë që kalojnë gjetiu, prandaj pjesa interesante e këtij projekti nuk është lista e veçorive por mënyra si u mbajt i saktë. Zhvillimi i udhëhequr nga testet zbatohet nga mjetet dhe jo nga rregullorja: një hook e bllokon shkrimin e një skedari të ri kodi që nuk ka test përkatës, bllokon për çdo gabim lint në workspace-in përkatës dhe bllokon për një test që dështon, dhe rregullat e shtëpisë i refuzojnë testet që nuk verifikojnë asgjë ose që verifikojnë një mock në vend të një rezultati. Çdo rregull lint i nivelit warning ngrihet në gabim; kur lint-i u aktivizua për backend-in, borxhi historik prej 10,635 shkeljesh u ngri në një bazë që vetëm mund të zvogëlohet, dhe sot është 6,135, poshtë me 42 për qind. Heqja e një rregulli kërkon një arsye të shkruar dhe miratim të pronarit, dhe vetë ky kusht zbatohet nga makina. Fjala e mbaruar ka një përkufizim: paketat e prekura kalojnë lint, type check dhe teste, ndryshimi është në prodhim, deployment-i raportohet i shëndetshëm, URL-ja publike kthen 200, testet end-to-end kalojnë, dhe dikush e ka hapur faqen dhe e ka parë. Në depo janë të regjistruara rreth pesëmbëdhjetë auditime të veçanta: siguri, përputhshmëri ligjore me aktet, saktësi kontabël, gatishmëri për shkallë dhe përmbajtje. Nëse po blini software që duhet të jetë i saktë dhe jo thjesht i mbaruar, ajo metodë pune është ajo që po blini.

• Zhvillim i udhëhequr nga testet, i zbatuar nga një hook: 15,418 teste në 1,401 skedarë
• Çdo paralajmërim lint ngrihet në gabim; borxhi i ngrirë është poshtë me 42 për qind
• Heqja e një rregulli kërkon arsye të shkruar dhe miratim, të zbatuara nga makina
• Një përkufizim i shkruar i të mbaruarës që mbyllet me një deployment të shëndetshëm dhe një njeri që e sheh faqen
• Rreth pesëmbëdhjetë auditime të regjistruara: siguri, ligj, saktësi kontabël, shkallë, përmbajtje
• Saktësia që e detyron fusha: aritmetikë e saktë e shumave dhe ndarje bizneseve e zbatuar në kod