Vodič za programere kroz API za fiskalizaciju

API za fiskalizaciju omogućava poslovnom softveru da razgovara direktno sa poreskom upravom. Kad trgovac izda fakturu, aplikacija je šalje državi i dobija odgovor za nekoliko sekundi. Ukratko, papirni trag je sada živi tok podataka.

Mnoge države su krenule tim putem u posljednjih deset godina. Vlade traže podatke u realnom vremenu, manje prevara i brže provjere. Zato su se obaveze razvojnog tima proširile. Poreski propisi više nisu posao zadnje kancelarije. Oni sada stoje u putanji koda svake prodaje.

Povezano: Gradite ovo u svom proizvodu? Pogledajte naš vodič API za fiskalizaciju i saznajte šta takav interfejs jeste i šta traži živa postavka.

Šta radi API za fiskalizaciju

API je kapija između dva sistema. API za fiskalizaciju usmjerava tu kapiju ka poreskoj upravi. Aplikacija pakuje fakturu, potpisuje je i šalje. Država onda provjerava račun, poresku stopu i broj fakture. Ako je sve u redu, vraća fiskalni identifikator.

Taj identifikator je dio pravne evidencije. Vaša aplikacija mora da ga sačuva i odštampa na računu. Ako provjera ne prođe, API umjesto toga vraća kod greške. Dobar softver taj kod pretvara u jasne riječi na koje kasir može da reaguje.

Sa kase tok izgleda jednostavno. Ispod njega, međutim, mnogo toga mora da bude tačno. Na primjer, aplikacija mora da pročita pravu poresku stopu, oblikuje poruku po specifikaciji, dokaže svoj identitet i pažljivo protumači svaki odgovor.

Zašto je ovo važno za softverske timove

Neki timovi još uvijek gledaju na poreski posao kao na računovodstvenu sitnicu. U stvarnosti, API za fiskalizaciju sada stoji na kritičnoj putanji prihoda. Neuspio poziv može da zaustavi prodaju. Isto tako, istekli sertifikat može da zaustavi naplatu na cijeloj lokaciji.

Zbog toga planirajte fiskalni dio dok crtate arhitekturu. Naknadno kalemljenje vodi u krhak kod. Zahtjevi se takođe mijenjaju. Države dodaju polja, pooštravaju specifikacije i dižu ljestvicu na kriptografiji. Kod zato mora da se prilagodi bez ponovnog pisanja.

Kako faktura putuje kroz API

Prvo, korisnik kreira fakturu u aplikaciji. Stavke, cijene, poreske kategorije i podaci o kupcu dolaze iz baze.

Drugo, aplikacija sama provjerava te podatke. Poreski broj koji nedostaje ili pogrešan zbir treba da ispliva prije nego što poziv krene. Rana provjera smanjuje uzaludne zahtjeve i pomaže operateru da brzo ispravi grešku.

Zatim aplikacija oblikuje poruku. Stariji državni portali očekuju XML. Noviji primaju i JSON. Struktura mora da odgovara objavljenoj specifikaciji, jer mali propust znači odbijanje.

Onda dolazi dokaz identiteta. Zavisno od države, to može da bude ključ, token, potpisani sertifikat ili uzajamni TLS. OAuth 2.0 je osnova mnogih tokova sa tokenima.

Na kraju, poreska uprava pokreće svoju provjeru i odgovara. Prolaz donosi fiskalni identifikator. Pad donosi kod greške koji morate da zapišete i prikažete.

Tehnologija koju ćete sresti

REST je pravilo na novijim sistemima za fiskalizaciju. Oslanja se na obične HTTP glagole, pa zato dobro pristaje oblaku i mobilnom radu. XML je ipak i dalje čest, jer su mnogi poreski portali nastali prije nego što je JSON pobijedio.

Kriptografija je jednako važna. Neki sistemi traže potpisani heš na svakom zahtjevu, što dokazuje da se poruka nije mijenjala na putu. Dalje, sav saobraćaj treba da ide preko HTTPS sa aktuelnom verzijom protokola TLS.

Nikad ne držite pristupne podatke u kodu ili u zajedničkom fajlu sa podešavanjima. Koristite upravljani trezor tajni. To čini rotaciju ključeva lakom i drži štetu u malom krugu. OWASP Top Ten pokriva ove rizike detaljnije.

Greške i ponovni pokušaji

Nijedan API nije stalno dostupan, pa ni API za fiskalizaciju nije izuzetak. Poreski portali imaju prozore za održavanje. Veze padaju. Loši podaci prolaze. Dobar softver računa na sva tri slučaja.

Prvo, podijelite padove u dvije grupe. Istek vremena ili status 503 traje kratko, pa je ponovni pokušaj sa odgodom pravo rješenje. Odbijen poreski broj nije takav, jer to samo operater može da ispravi.

Drugo, bilježite dovoljno da se cijeli poziv može rekonstruisati. Identifikator zahtjeva, vrijeme, statusni kod i broj pokušaja su dovoljni. Podatke o kupcima ipak držite van tih zapisa.

Treće, obavijestite čovjeka kad se padovi ponavljaju. Rano upozorenje sprečava da mala greška preraste u izgubljen dan trgovine.

Zaustavite duple fakture

Zamislite ovaj slučaj. Aplikacija šalje fakturu. Država je upisuje. Onda veza pada prije nego što odgovor stigne. Bez zaštite, aplikacija će poslati istu fakturu dva puta.

Zbog toga mnogi servisi koji nude API za fiskalizaciju primaju ključ idempotentnosti. Isti ključ daje jedan zapis, koliko god puta pozvali. HTTP specifikacija propisuje koje metode je bezbjedno ponoviti.

Takođe upišite lokalni zapis prije svakog poziva. Onda aplikacija može sama sebe da pita da li je tu fakturu već poslala. Pažljivo vođenje stanja čuva i trgovca i njegove kupce od zabune.

Brzina i obim

Prodavnica sa dvadeset faktura dnevno nema mnogo brige. Lanac sa hiljadama faktura na sat je sasvim drugi slučaj.

Ne blokirajte kasu udaljenim pozivom ako propisi dozvoljavaju kasnije prijavljivanje. Umjesto toga, gurnite svaku fakturu u red poruka. Pozadinski radnici onda obrađuju pozive nezavisno.

Ovo drži aplikaciju brzom i smiruje je pod opterećenjem. Štaviše, ako portal padne, red čuva posao dok se portal ne vrati. Dodavanje radnika je jeftinije od prepravke.

Pratite i vrijeme odziva. Latencija koja raste upozorava vas na nevolju mnogo prije nego što to uradi korisnik.

ERP i kasa sistemi

ERP već drži najveći dio onoga što poreska uprava traži. Podaci o kupcima, cijene, kategorije PDV-a i uslovi plaćanja žive tamo. Fiskalni korak zato treba da čita te podatke, umjesto da ih udvaja.

Zastarjeli podaci su uobičajen uzrok odbijanja. Na primjer, držite poreske stope i evidenciju kupaca usklađene kroz sve module. Ovdje pomaže dizajn vođen događajima, jer aplikacija reaguje kad se faktura pojavi umjesto da je stalno traži.

Trgovcima treba brzina na kasi. Rad bez veze je takođe važan, gdje lokalni propisi to dozvoljavaju. Pokažite zaposlenima koje su prodaje prošle, a koje još čekaju. Onda sinhronizujte red čim se veza vrati.

Pravila se razlikuju po državama

Jedna integracija neće pokriti svako tržište, jer je API za fiskalizaciju nacionalna tvorevina. Neke države odobre fakturu prije nego što je kupac vidi. Druge je primaju poslije prodaje, u zadatom roku za prijavu.

Numeracija faktura se takođe razlikuje. Jedna država traži jedan neprekidan niz. Druga dozvoljava niz po prodavnici ili po kasi. Obračun poreza se isto razlikuje, pa držite stope i pravila zaokruživanja u podešavanjima, nikad u kodu.

Iznad svega, držite logiku po državi u zasebnom modulu. Onda novo tržište znači novi modul, a ne prepisivanje jezgra.

Testirajte prije puštanja u rad

Većina poreskih organa vodi testno okruženje koje odslikava živi servis. Koristite ga temeljno. Čista faktura je samo jedan slučaj.

Testirajte i pogrešne poreske brojeve, istekle sertifikate, duple pozive, istek vremena i prekinute veze. Automatski testovi onda čuvaju to ponašanje na svakom izdanju. Pokrivenost regresijom postaje još važnija kako aplikacija raste.

Kako Square Software može da pomogne

Square Software gradi poslovni softver po mjeri, a fiskalne integracije radimo u Albaniji. Van Albanije prodajemo opšti softverski rad: veb, mobilne aplikacije, ERP i kasa rješenja, te podršku timu.

Projektujemo za dugi rok. U praksi to znači jasne granice modula, pažljivo rukovanje pristupnim podacima, red poruka gdje ga opterećenje traži i testove koji drže fiskalnu putanju iskrenom kako se pravila mijenjaju.

Želite drugi par očiju na svom fiskalnom toku? Javite se timu ili pročitajte kako uklapamo fiskalna pravila u softver po mjeri.

Šta slijedi

Prijava u realnom vremenu se širi, pa će API za fiskalizaciju stići na još tržišta. Vladama odgovara brzina i čist revizorski trag. Isto tako, firmama odgovara manje ručnog posla.

Platforme u oblaku će nositi veći dio tereta. Štaviše, pametnija provjera može da uhvati čudne fakture prije nego što uopšte stignu do države. Vremenom će naplata, zalihe i poreska prijava stajati u jednom povezanom toku.

Timovi koji danas grade savitljiv softver najlakše će podnijeti sjutrašnja pravila. Mali moduli, disciplinovana bezbjednost i solidan rad na API-ju ostaju temelj.

Česta pitanja

Šta je API za fiskalizaciju? To je interfejs koji omogućava poslovnom softveru da prijavi fakturu poreskoj upravi i dobije pravno valjan odgovor.

Kome treba? Prodavnicama, restoranima, hotelima, klinikama i svakoj firmi sa ERP ili kasa sistemom na tržištu sa prijavom u realnom vremenu.

Da li je API za fiskalizaciju isti u svakoj državi? Nije. Svaka država propisuje svoju specifikaciju, svoja pravila identiteta i svoj format fakture. Zato uvijek pročitajte lokalnu dokumentaciju.

Zašto je bezbjednost toliko važna? Zato što fakture nose novac i podatke o kupcima. Slabi pristupni podaci ili nezaštićen saobraćaj ugrožavaju oboje.

Da li API za fiskalizaciju pristaje uz ERP? Da. Većina ERP, računovodstvenih i kasa platformi ga danas ugrađuje da smanji ručnu prijavu.

Treba vam pomoć oko fiskalnog rješenja u Albaniji? Square gradi i održava API za fiskalizaciju za kase, ERP i SaaS proizvode u Albaniji. Pogledajte šta taj rad obuhvata ili javite se timu.