Udhëzuesi i zhvilluesit për API e fiskalizimit

API e fiskalizimit i lejon programet e biznesit të flasin drejtpërdrejt me administratën tatimore. Kur tregtari lëshon një faturë, aplikacioni ia dërgon shtetit dhe merr përgjigje brenda sekondash. Me pak fjalë, gjurma e letrës tani është një rrjedhë e drejtpërdrejtë të dhënash.

Shumë vende kanë ecur në këtë rrugë gjatë dhjetë viteve të fundit. Qeveritë kërkojnë të dhëna të drejtpërdrejta, më pak mashtrim dhe kontrolle më të shpejta. Si rrjedhojë, detyrat e një ekipi zhvillimi janë zgjeruar. Rregullat tatimore nuk janë më punë e zyrës së pasme. Përkundrazi, ato rrinë në rrugën e kodit të çdo shitjeje.

Të lidhura: Po e ndërtoni këtë brenda produktit tuaj? Shihni udhëzuesin tonë për API-n e fiskalizimit, që shpjegon çfarë është kjo ndërfaqe dhe çfarë kërkon një vënie në punë.

Çfarë bën API e fiskalizimit

Një API është një derë midis dy sistemeve. API e fiskalizimit e drejton këtë derë nga administrata tatimore. Aplikacioni e paketon faturën, e nënshkruan dhe e dërgon. Më pas shteti kontrollon llogaritë, normën e tatimit dhe numrin e faturës. Nëse gjithçka është në rregull, kthen një identifikues fiskal.

Ai identifikues është pjesë e regjistrit ligjor. Aplikacioni juaj duhet ta ruajë dhe ta shtypë në kupon. Nëse kontrolli dështon, API kthen një kod gabimi. Programet e mira e kthejnë atë kod në fjalë të thjeshta që arkëtari i kupton.

Nga banaku, rrjedha duket e thjeshtë. Nën të, megjithatë, shumë gjëra duhet të shkojnë mirë. Për shembull, aplikacioni duhet të lexojë normën e saktë të tatimit. Duhet ta formatojë ngarkesën sipas specifikimit, të vërtetojë identitetin e vet dhe ta lexojë me kujdes çdo përgjigje.

Pse ka rëndësi për ekipet e softuerit

Disa ekipe ende e trajtojnë punën tatimore si veçori kontabiliteti. Në fakt, API e fiskalizimit rri sot në rrugën kritike të të ardhurave. Një thirrje e dështuar mund ta ndalë një shitje. Po ashtu, një certifikatë e skaduar mund ta bllokojë faturimin për një pikë të tërë.

Prandaj planifikojeni punën fiskale që kur vizatoni arkitekturën. Ngjitja e saj më vonë sjell kod të brishtë. Edhe kërkesat lëvizin. Qeveritë shtojnë fusha, shtrëngojnë specifikimet dhe ngrenë nivelin e kriptografisë. Kështu kodi duhet të përshtatet pa u rishkruar.

Si lëviz një faturë përmes API-t

Së pari, përdoruesi krijon faturën në aplikacion. Rreshtat, çmimet, kategoritë e tatimit dhe të dhënat e klientit vijnë nga baza e të dhënave.

Së dyti, aplikacioni i vërteton vetë ato të dhëna. Numrat tatimorë që mungojnë ose totalet e gabuara duhet të dalin para se të niset thirrja. Vërtetimi i hershëm i ul kërkesat e humbura dhe e ndihmon operatorin t'i ndreqë shpejt gabimet.

Më pas, aplikacioni formon ngarkesën. Portalet e vjetra shtetërore presin XML. Ato më të rejat pranojnë edhe JSON. Struktura duhet të përputhet me specifikimin e botuar, sepse një gabim i vogël sjell refuzim.

Vjen radha e provës së identitetit. Sipas vendit, kjo mund të jetë një çelës API, një token, një certifikatë e nënshkruar ose TLS i ndërsjellë. OAuth 2.0 është baza e shumë rrjedhave me token.

Në fund, administrata tatimore kryen vërtetimin e vet dhe përgjigjet. Kalimi jep një identifikues fiskal. Dështimi jep një kod gabimi, të cilin duhet ta regjistroni dhe ta shfaqni.

Teknologjia që do të takoni

REST është norma te API e fiskalizimit më të reja. Mbështetet në folje të thjeshta HTTP, prandaj i shkon mirë punës në re dhe në celular. XML mbetet ende i zakonshëm, sepse shumë portale tatimore dolën para se të fitonte JSON.

Kriptografia ka po aq rëndësi. Disa sisteme kërkojnë një hash të nënshkruar në çdo kërkesë. Kjo provon se skedari nuk ndryshoi rrugës. Për më tepër, i gjithë trafiku duhet të udhëtojë mbi HTTPS me një version të tanishëm TLS.

Mos i mbani kurrë kredencialet në kod ose në një skedar konfigurimi të përbashkët. Përdorni një menaxher të sigurt sekretesh. Kjo e lehtëson rrotullimin e çelësave dhe e mban të vogël dëmin e mundshëm. OWASP Top Ten i trajton këto rreziqe më në thellësi.

Gabimet dhe riprovat

Asnjë API nuk punon gjithë kohën, as API e fiskalizimit. Portalet tatimore kanë dritare mirëmbajtjeje. Lidhjet bien. Të dhënat e gabuara kalojnë. Programet e mira i parashikojnë të tria.

Së pari, ndajini dështimet në dy grupe. Një kohë e mbaruar ose një 503 është kalimtare, prandaj riprova me pritje është zgjidhja e duhur. Një numër tatimor i refuzuar nuk është i tillë, sepse vetëm operatori mund ta ndreqë.

Së dyti, regjistroni aq sa të rindërtoni gjithë thirrjen. Mjaftojnë ID-ja e kërkesës, ora, kodi i statusit dhe numri i riprovave. Megjithatë, mos i fusni të dhënat e klientit në ato regjistra.

Së treti, njoftoni një person kur dështimet përsëriten. Paralajmërimi i hershëm e ndal një difekt të vogël të kthehet në një ditë tregtie të humbur.

Ndaloni faturat e dyfishta

Merrni këtë skenar. Aplikacioni dërgon një faturë. Shteti e regjistron. Më pas lidhja bie para se të mbërrijë përgjigjja. Pa mbrojtje, aplikacioni do ta dërgojë dy herë të njëjtën faturë.

Shumë API e fiskalizimit pranojnë për këtë arsye një çelës idempotence. I njëjti çelës jep një regjistrim të vetëm, sado herë ta thirrni. Specifikimi i HTTP tregon cilat metoda janë të sigurta për t'u përsëritur.

Shkruani gjithashtu një regjistrim vendor para çdo thirrjeje. Kështu aplikacioni pyet veten nëse e ka dërguar tashmë atë faturë. Menaxhimi i kujdesshëm i gjendjes e shpëton nga ngatërresa tregtarin dhe klientët e tij.

Shpejtësia dhe shkallëzimi

Një dyqan me njëzet fatura në ditë ka pak për t'u shqetësuar. Një zinxhir me mijëra fatura në orë është krejt rast tjetër.

Mos e bllokoni banakun për një thirrje të largët, nëse rregullat ju lejojnë të raportoni më vonë. Në vend të kësaj, shtyjeni çdo faturë në një radhë mesazhesh. Punëtorët në sfond i përpunojnë pastaj thirrjet veç e veç.

Kjo e mban aplikacionin të shpejtë dhe e qetëson nën ngarkesë. Për më tepër, nëse portali bie, radha e ruan punën derisa ai të kthehet. Shtimi i punëtorëve kushton më pak se një rindërtim.

Mbikëqyrni edhe kohët e përgjigjes. Vonesa që përkeqësohet ju paralajmëron për telashe shumë para se ta bëjë një përdorues.

Sistemet ERP dhe arkat

Një ERP e mban tashmë pjesën më të madhe të asaj që kërkon administrata tatimore. Të dhënat e blerësve, çmimet, kategoritë e TVSH-së dhe afatet rrinë aty. Kështu hapi fiskal duhet t'i lexojë ato të dhëna, në vend që t'i dyfishojë.

Të dhënat e vjetruara janë shkaku i zakonshëm i një refuzimi. Për shembull, mbajini normat e tatimit dhe të dhënat e klientëve të njësuara mes moduleve. Një dizajn i drejtuar nga ngjarjet ndihmon këtu, sepse aplikacioni reagon kur del një faturë, në vend që ta kërkojë atë vazhdimisht.

Tregtarëve u duhet shpejtësi te banaku. Ka rëndësi edhe puna jashtë linje, atje ku rregullat vendore e lejojnë. Tregojuni punonjësve cilat shitje kanë kaluar dhe cilat presin ende. Pastaj njësojeni radhën sapo të kthehet lidhja.

Rregullat ndryshojnë sipas vendit

Një integrim i vetëm nuk i mbulon të gjitha tregjet, sepse API e fiskalizimit janë krijime kombëtare. Disa vende e miratojnë faturën para se ta shohë klienti. Të tjera e marrin pas shitjes, brenda një afati raportimi.

Edhe numërimi i faturave ndryshon. Një vend do një varg të vetëm të pandërprerë. Një tjetër lejon një varg për çdo dyqan ose arkë. Ndryshon edhe llogaritja e tatimit, prandaj mbajini normat dhe rregullat e rrumbullakimit në konfigurim, kurrë në kod.

Mbi të gjitha, mbajeni logjikën e vendit në modulin e vet. Atëherë një treg i ri do të thotë një modul i ri, jo rishkrim i bërthamës.

Testoni para se ta hidhni në punë

Shumica e organeve tatimore mbajnë një mjedis prove që pasqyron shërbimin e vërtetë. Përdoreni pa kursim. Një faturë e pastër është vetëm një rast.

Provoni edhe numra tatimorë të gabuar, certifikata të skaduara, thirrje të dyfishta, kohë të mbaruara dhe lidhje të rëna. Testet e automatizuara e mbrojnë pastaj atë sjellje në çdo version. Për më tepër, mbulimi ndaj regresit merr peshë sa më shumë rritet aplikacioni.

Si mund të ndihmojë Square Software

Square Software ndërton programe biznesi të porositura dhe merr përsipër punë integrimi fiskal në Shqipëri. Jashtë Shqipërisë shesim punë të përgjithshme softueri: ueb, celular, ndërtime ERP dhe arke, si dhe mbështetje për ekipin.

Ne projektojmë për afat të gjatë. Në praktikë kjo do të thotë kufij të pastër modulesh, trajtim të kujdesshëm të kredencialeve, një radhë atje ku ngarkesa e kërkon dhe teste që e mbajnë të ndershme rrugën fiskale kur rregullat lëvizin.

Doni një sy të dytë mbi rrjedhën tuaj fiskale? Flisni me ekipin ose lexoni si i fusim rregullat fiskale brenda softuerit të porositur.

Çfarë vjen më pas

Raportimi i drejtpërdrejtë vazhdon të përhapet, prandaj API e fiskalizimit do të mbërrijë në më shumë tregje. Qeveritë e pëlqejnë shpejtësinë dhe gjurmën e pastër të auditimit. Po ashtu, firmat e pëlqejnë uljen e punës me dorë.

Platformat në re do të mbajnë më shumë nga ngarkesa. Për më tepër, vërtetimi më i zgjuar mund t'i kapë faturat e çuditshme para se të mbërrijnë te shteti. Me kohë, faturimi, stoku dhe raportimi tatimor do të rrinë në një rrjedhë të vetme.

Ekipet që ndërtojnë sot programe të lakueshme do të përballen më mirë me rregullat e nesërme. Modulet e vogla, siguria e disiplinuar dhe puna e mirë me API mbeten themeli.

Pyetje të shpeshta

Çfarë është API e fiskalizimit? Është ndërfaqja që i lejon programet e biznesit t'i raportojnë faturat te administrata tatimore dhe të marrin një përgjigje me vlerë ligjore.

Kujt i duhet? Dyqaneve, restoranteve, hoteleve, klinikave dhe çdo firme me ERP ose arkë në një treg me raportim tatimor të drejtpërdrejtë.

A është API e fiskalizimit i njëjtë në çdo vend? Jo. Çdo vend cakton specifikimin e vet, rregullat e veta të identitetit dhe formatin e vet të faturës. Prandaj lexoni gjithmonë dokumentacionin vendor.

Pse siguria është kaq qendrore? Sepse faturat mbajnë para dhe të dhëna klientësh. Kredencialet e dobëta ose trafiku i pambrojtur i vënë të dyja në rrezik.

A i shkon API e fiskalizimit një ERP-je? Po. Shumica e platformave ERP, të kontabilitetit dhe të arkës e lidhin sot brenda, për të ulur punën e raportimit me dorë.

Ju duhet ndihmë për një ndërtim fiskal në Shqipëri? Square ndërton dhe mirëmban punë me API e fiskalizimit për arka, ERP dhe produkte SaaS në Shqipëri. Shihni çfarë mbulon kjo punë ose flisni me ekipin.