VOS: piattaforma albanese di fiscalizzazione e contabilità

La sfida: una fattura non è valida finché non lo dice l'amministrazione fiscale

La legge albanese obbliga ogni contribuente a trasmettere ciascuna fattura all'amministrazione fiscale nel momento in cui viene emessa. La fattura non è legalmente valida finché il sistema centrale delle fatture non restituisce i suoi codici. In pratica un'azienda non può semplicemente stampare una ricevuta: servono un certificato digitale qualificato, un software che costruisca esattamente l'XML previsto, una firma digitale XML e una connessione attiva, il tutto in pochi secondi dal pagamento del cliente. Ogni tipo di documento ha regole proprie, i registratori di cassa vanno registrati come dispositivi e aperti e chiusi ogni giorno, e quando la connessione cade le fatture vanno comunque emesse e poi riconciliate entro un termine di legge. In parallelo, la contabilità va comunque tenuta. Il portale pubblico gratuito copre il minimo per i contribuenti più piccoli e lascia irrisolti la contabilità, il caso multi-azienda e qualsiasi integrazione con i sistemi propri dell'azienda. Quel vuoto è il prodotto.

La specifica implementata da VOS è quella dell'autorità stessa, seguita attraverso nove revisioni pubblicate. VOS spiega il processo che automatizza in come funziona la fiscalizzazione in Albania.

• Registrazione in tempo reale presso l'amministrazione fiscale prima che la fattura sia valida
• Un certificato digitale qualificato per azienda, da ottenere, caricare e rinnovare
• Quattro tipi di documento distinti, ciascuno con schema e regole proprie
• Registratori di cassa registrati come dispositivi, aperti e chiusi ogni giorno, con i movimenti di cassa tracciati
• Un termine di legge per riconciliare le fatture emesse mentre la connessione era assente
• Una specifica tecnica che l'autorità ha già rivisto nove volte

La nostra soluzione: sette superfici, dal banco al libro giornale del commercialista

VOS è un'unica piattaforma distribuita su sette host pubblici. La dashboard cliente è il posto in cui un'azienda opera davvero: un pannello punto cassa, una schermata di fattura rapida per la velocità al banco e flussi completi per ogni tipo di documento previsto dalla legge. Sono la fatura e thjeshtë, la fattura semplice che riceve un consumatore; la fatura elektronike, la fattura elettronica scambiata tra aziende; la fleta shoqëruese, il documento di trasporto che accompagna la merce; e l'autofatturazione. Accanto ci sono la gestione dei registratori di cassa, magazzino e giacenze, gli acquisti e gli account operatore. Il portale di contabilità è la metà più grande e la parte con meno concorrenza sul mercato albanese: il piano dei conti nazionale nelle sue sette classi di legge, un libro giornale in partita doppia che non registra finché non quadra, il blocco dei periodi mensili, la riconciliazione bancaria con procedura guidata di import CSV, i registri acquisti e vendite di legge e un catalogo di 42 report su 11 sezioni. Il commercialista lavora su tutti i clienti da un unico posto. Attorno a questi due ci sono una console di amministrazione, una API REST documentata, un sito di documentazione scritto in albanese, una demo pubblica senza registrazione e un'app mobile che aggiunge blocco biometrico, notifiche push e scansione con fotocamera invece di riscrivere l'interfaccia.

I tre tipi di documento fiscalizzati sono descritti in la pagina soluzioni di VOS, e il lato commercialista in il portale di contabilità per commercialisti.

• Dashboard cliente: punto cassa, fattura rapida e un flusso completo per tipo di documento
• Fatura e thjeshtë, fatura elektronike, fleta shoqëruese e autofatturazione, ognuna con il proprio schema
• Portale contabilità: piano dei conti nazionale, partita doppia, blocco periodi, riconciliazione
• Registri acquisti e vendite di legge, più 42 report su 11 sezioni
• Console di amministrazione, API REST, documentazione in albanese e demo pubblica
• App mobile con blocco biometrico, notifiche push e scansione con fotocamera

Tecnologia e architettura: come una fattura viene davvero fiscalizzata

Lo stack è un monorepo Yarn workspaces su Turborepo: API in Fastify e TypeScript, PostgreSQL tramite Prisma con Redis per cache e rate limiting, app web Next.js e React, sito marketing Vite prerenderizzato, documentazione Docusaurus e guscio mobile Expo, in esercizio su k3s dietro Traefik e Cloudflare. Fiscalizzare una fattura richiede sei passaggi. Il certificato PKCS#12 dell'azienda viene caricato e l'identificativo fiscale letto dal certificato stesso, non dall'input dell'utente. Il codice interno della fattura si costruisce da una stringa canonica di emittente, timestamp, numero fattura, unità operativa, codice registratore, codice software e totale, se ne calcola il digest, si firma con la chiave privata dell'azienda e si applica l'hash; codice e firma escono da un'unica passata di firma, così non possono mai divergere. Il documento di richiesta segue lo schema dell'autorità e tiene ogni importo in centesimi di lek, così imponibile più imposta fa esattamente il totale. La richiesta viene firmata con firma digitale XML, scambiata con il sistema centrale in mutual TLS, e richiesta e risposta firmate vengono archiviate in una tabella dedicata per la conservazione prevista dalla legge, separata dalla riga della fattura così i payload pesanti non appesantiscono le query ordinarie. Sono implementate quindici operazioni distinte verso l'autorità fiscale su quattro diversi servizi web governativi, e le fatture elettroniche sono inoltre generate in UBL 2.1 secondo lo standard europeo EN 16931.

La superficie di integrazione è documentata pubblicamente, in albanese, in il sito di documentazione VOS.

• API Fastify e TypeScript, PostgreSQL via Prisma, Redis, Next.js e React, k3s
• Certificato caricato da PKCS#12, identificativo fiscale letto dal certificato, mai dall'input
• Codice fattura e firma prodotti in una sola passata, così non possono divergere
• Ogni importo in centesimi di lek, così i conti fiscali quadrano esattamente
• Firma digitale XML e mutual TLS verso il sistema centrale delle fatture
• Quindici operazioni verso il fisco su quattro servizi web governativi

Cosa abbiamo consegnato: ampiezza e profondità, e una piattaforma in esercizio

Qui di norma un case study riporta i dati di adozione. VOS non ne ha ancora da riportare, perché la diffusione commerciale non è iniziata, e preferiamo dirlo piuttosto che prendere in prestito un numero. Ciò che si può misurare è l'ampiezza e lo stato della cosa. Il repository contiene 312.209 righe di codice sorgente scritto a mano su 1.970 file, più altre 238.707 righe di test su 1.423 file; nell'API le righe di test eguagliano quasi esattamente quelle di sorgente. L'API dichiara 647 endpoint, di cui circa 607 raggiungibili. Il modello dati arriva a 98 modelli e 87 enum, con una multi-tenancy strutturale e non convenzionale: 69 modelli portano direttamente l'identificativo azienda, sostenuti da 98 indici composti. Sulla piattaforma ci sono 219 pagine, ossia 127 schermate applicative, 49 pagine marketing e 43 pagine di documentazione, queste ultime tutte in albanese. È stata costruita da tre persone in nove mesi attivi e 603 commit. Tutti e sette gli host sono attivi e sani, gli host applicativi restituiscono correttamente noindex e gli host storici del marchio precedente reindirizzano. La diffusione sta iniziando.

La piattaforma si può provare senza registrazione su la demo VOS dal vivo, e il prodotto stesso è su VOS, la piattaforma di fiscalizzazione, che pubblica anche strumenti gratuiti fra cui un calcolatore dell'imposta sul valore aggiunto albanese e un verificatore di fatture.

• 312.209 righe di sorgente scritto a mano, più 238.707 righe di test
• Circa 607 endpoint API raggiungibili sui 647 dichiarati, su 99 file di rotte
• 98 modelli dati e 87 enum, con la tenancy imposta strutturalmente da 98 indici composti
• 219 pagine: 127 schermate applicative, 49 pagine marketing, 43 di documentazione in albanese
• 603 commit in nove mesi attivi, da tre persone
• Sette host pubblici attivi e sani; la diffusione commerciale sta iniziando

Cosa dice questo case study sul lavorare con Square

Un dominio regolamentato punisce le abitudini che altrove passano, quindi la parte interessante di questo progetto non è l'elenco delle funzionalità ma come è stato tenuto corretto. Lo sviluppo guidato dai test è imposto dagli strumenti e non dalle policy: un hook blocca la scrittura di un nuovo file sorgente privo del test corrispondente, blocca su qualsiasi errore di lint nel workspace di competenza e blocca su un test fallito, e le regole interne rifiutano i test che non verificano nulla o che verificano un mock invece di un risultato. Ogni regola di lint di livello warning è promossa a errore; quando il lint è stato attivato sul backend, l'arretrato storico di 10.635 violazioni è stato congelato in una baseline che può solo ridursi, e oggi è a 6.135, in calo del 42 per cento. Sopprimere una regola richiede una motivazione scritta e l'approvazione del responsabile, e questo requisito è a sua volta imposto dalla macchina. Fatto ha una definizione: i pacchetti interessati passano lint, type check e test, la modifica è in esercizio, il deployment risulta sano, l'URL pubblico risponde 200, i test end-to-end passano e qualcuno ha aperto la pagina e l'ha guardata. Nel repository sono registrati circa quindici audit distinti su sicurezza, conformità legale rispetto alle norme, correttezza contabile, prontezza alla scala e contenuti. Se state comprando software che deve essere giusto e non semplicemente finito, è quel metodo di lavoro che state comprando.

• Sviluppo guidato dai test imposto da un hook, non da una policy: 15.418 test su 1.401 file
• Ogni warning di lint promosso a errore; arretrato congelato in calo del 42 per cento
• Sopprimere una regola richiede motivazione scritta e approvazione, imposte dalla macchina
• Una definizione scritta di fatto che finisce con un deployment sano e una persona che guarda la pagina
• Circa quindici audit registrati: sicurezza, legale, correttezza contabile, scala, contenuti
• La correttezza che il dominio impone: aritmetica esatta degli importi e tenancy imposta nel codice