Çfarë është API-ja e fiskalizimit
Fiskalizimi në Shqipëri nuk është raportim pas faktit. Fatura shkon te Drejtoria e Tatimeve në momentin që lëshohet, validohet atje dhe kthehet e regjistruar, para se t'i jepet klientit. Kjo do të thotë që çdo sistem që lëshon fatura, qoftë një ERP, një dyqan online, një aplikacion arke apo një program i shkruar posaçërisht për një biznes, duhet të bëhet pjesë e asaj rrjedhe.
API-ja e fiskalizimit, e kërkuar shpesh thjesht si fiskalizimi API, e bën pikërisht këtë. Ju dërgoni faturën si JSON në një endpoint të vetëm dhe merrni mbrapsht faturën e fiskalizuar. Nuk shkruani XML, nuk merreni me SOAP, nuk trajtoni certifikata dhe nuk implementoni rifiskalizimin kur rrjeti bie. Ajo pjesë është përgjegjësia jonë, dhe e njëjta pjesë përdoret nga vetë aplikacioni fature.al.
Si funksionon një kërkesë
Rrjedha është e njëjtë për çdo lloj fature. Sistemi juaj dërgon një POST me rreshtat e faturës. fature.al e ndërton dokumentin fiskal, e nënshkruan me certifikatën e biznesit, e dërgon te Sistemi Qendror i Informacionit dhe pret përgjigjen. Fatura ruhet njëkohësisht në një arkiv që nuk mund të modifikohet, sepse ligji e kërkon gjurmën.
Përgjigja nuk kthehet derisa fatura të jetë regjistruar. Kur merrni
status: true, fatura ekziston te tatimet dhe kodet që merrni janë ato që
shtypen mbi dokument.
Pse nuk lidheni vetë me CIS
Është pyetja e parë e çdo zhvilluesi që hyn në këtë temë. Përgjigja e shkurtër është që shërbimi i fiskalizimit nuk pranon një kërkesë të thjeshtë HTTP. Mesazhi duhet të jetë XML i formuar saktësisht sipas skemës, i nënshkruar në mënyrë digjitale me certifikatën elektronike të tatimpaguesit, dhe software-i lëshues duhet të figurojë ndër subjektet e certifikuara.
Përveç kësaj ka detyrime që nuk duken në specifikim, por shfaqen në ditën e parë të prodhimit. Fatura që nuk kalon duhet riprovuar. Fatura e lëshuar jashtë linje duhet të mbërrijë brenda 48 orësh. Numri i faturës për arkën ndjek pajisjen fiskale, jo bazën tuaj të të dhënave. Certifikata skadon dhe duhet zëvendësuar pa ndërprerje. Të gjitha këto janë punë e vazhdueshme, jo një integrim i njëhershëm.
Duke kaluar përmes API-t tonë, sistemi juaj mbetet sistemi ku ndodh biznesi, ndërsa pjesa fiskale mbahet dhe përditësohet nga ne sa herë ndryshon skema e tatimeve. Lexoni edhe çfarë është fiskalizimi për kontekstin ligjor.
Identifikimi dhe kredencialet
Çdo kërkesë mbart dy nivele identifikimi. Kush e bën kërkesën tregohet me token-in e përdoruesit, dhe cili software e bën tregohet me kredencialet e aplikacionit tuaj.
Authorization: Bearer {api_token}
X-Client-Id: ft_id_...
X-Client-Secret: ft_sk_...
User-Agent: EmriIAplikacionit/2.4.1Token-i gjenerohet nga vetë klienti te Konfigurime dhe API Tokens, ose kthehet nga përgjigja e regjistrimit kur ju e regjistroni biznesin me API. Ai ndryshon nga një klient te tjetri. Client id dhe client secret, përkundrazi, i përkasin aplikacionit tuaj dhe janë të njëjtat për të gjithë bizneset që e përdorin atë.
Secret-i shfaqet vetëm një herë kur gjenerohet. Nëse humbet ose dyshoni se është kompromentuar, e rigjeneroni nga i njëjti ekran. Client id-ja mbijeton rigjenerimin, prandaj në aplikacion ndërroni vetëm një vlerë.
Endpoint-et kryesore
Të gjitha adresat më poshtë kanë prefiksin /api/v1. Kjo tabelë është
harta, jo referenca e plotë. Çdo endpoint me fushat, shembujt dhe përgjigjet e veta
është te dokumentacioni.
| Endpoint | Për çfarë shërben |
|---|---|
POST /invoice/cash |
Faturë me para në dorë, kartë, tollon ose pagesë në dorëzim. Numërohet mbi pajisjen fiskale. |
POST /invoice/noncash |
Faturë me transfertë bankare, e numëruar në nivel kompanie. |
POST /invoice/e-invoice |
Faturë elektronike drejt sistemit qeveritar, me EIC dhe UBL. |
POST /invoice/order dhe /invoice/summary |
Porosia e hapur dhe fatura përmbledhëse që e mbyll atë. |
POST /invoice/bulk-noncash |
Dërgim në grup i faturave jo-cash, për ngarkesa periodike. |
POST /invoice/wtn |
Fletë-shoqërimi për transportin e mallrave. |
POST /invoice/cancel/{id} |
Anullim, edhe sipas identifikuesit tuaj me /invoice/cancel-by-internal-id/{internalId}. |
GET /invoice/print/{id} |
PDF-ja e faturës, gati për t'u dërguar ose shtypur. |
POST /cash-register/open-balance |
Hapja dhe mbyllja e arkës, e detyrueshme për shitjen me para në dorë. |
GET /client/search |
Kërkim i biznesit në regjistrin fiskal sipas NIPT-it. |
GET /reports/* |
Xhiro, TVSH, artikujt dhe klientët kryesorë, të agreguara në bazën e të dhënave. |
Shembull: një faturë cash
Ky është integrimi i plotë për shumicën e rasteve. Një POST, një përgjigje, fatura e fiskalizuar.
POST https://demo.fature.al/api/v1/invoice/cash
Authorization: Bearer {api_token}
X-Client-Id: ft_id_...
X-Client-Secret: ft_sk_...
Content-Type: application/json
{
"internalId": "CASH-001",
"payment_method": "BANKNOTE",
"lines": [
{
"product_name": "Kafe Espresso",
"product_code": "ESP-01",
"unit": "cope",
"quantity": 2,
"price": 100,
"total": 200,
"vat": 20
}
]
}
Përgjigja kthen faturën e regjistruar. iic është NSLF-ja e gjeneruar nga
software-i lëshues, fic është NIVF-ja që kthen Sistemi Qendror, dhe
verifyURL është adresa që fshihet pas kodit QR mbi faturë.
{
"status": true,
"data": {
"invoice": {
"id": 918273,
"number": "12/2026/aa123bb456",
"iic": "A1B2C3D4E5F6...",
"fic": "0f8a2c4e-...",
"tcrCode": "aa123bb456",
"businessCode": "bb123cc456",
"operatorCode": "cc123dd456",
"fiscalizedAt": "2026-08-25 11:42:07",
"verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?iic=...",
"pdf": "https://fature.al/api/v1/invoice/print/918273"
}
}
}Fatura e krijuar me API është një faturë krejt e zakonshme brenda fature.al. Shfaqet në listë, hyn në raporte dhe në TVSH, dhe printohet njësoj si një faturë e lëshuar me dorë.
Regjistrimi i klientëve me API
Nëse jeni ofrues software-i dhe sillni klientët tuaj, nuk keni pse t'i kaloni ata nga paneli. I gjithë konfigurimi fillestar bëhet me API, në pesë hapa që kryhen një herë për çdo biznes.
POST /registerkrijon kompaninë dhe kthen token-in bashkë me id-në e njësisë.POST /on-boarding/certificatengarkon certifikatën elektronike të biznesit.POST /on-boarding/branch/{id}vendos kodin e njësisë së biznesit.POST /on-boarding/fiscal-deviceregjistron pajisjen fiskale dhe kthen kodin TCR.POST /on-boarding/user/{id}lidh kodin e operatorit me pajisjen.
Pas hapit të pestë biznesi është gati dhe çdo gjë tjetër është vetëm një kërkesë faturimi. Kodi i operatorit dhe kodi i njësisë merren nga platforma Self Care e tatimeve. Nëse nuk i keni hasur më parë, i shpjegojmë te kodi i operatorit dhe te vendi i ushtrimit të veprimtarisë.
Sandbox dhe kalimi në Live
Integrimi ndërtohet gjithmonë kundrejt https://demo.fature.al. Faturat e
lëshuara atje nuk kanë vlerë fiskale dhe mund të përdoren lirisht për provë. Kur rrjedha
juaj është e plotë, kalohet në https://fature.al duke ndryshuar vetëm
adresën bazë. Asnjë fushë dhe asnjë header nuk ndryshon.
Limitet, gabimet dhe idempotenca
Endpoint-et që lëshojnë fatura fiskale pranojnë deri në 30 kërkesa në minutë dhe 600 në
orë për përdorues. Dërgimi në grup ka limit më të ulët, ndërsa kërkimi i klientëve dhe
endpoint-et e tjera kanë limite më të gjera. Kur limiti arrihet, kthehet statusi
429 me header-in Retry-After, që ju thotë sa sekonda të prisni.
Fusha internalId është identifikuesi i faturës në sistemin tuaj dhe është e
detyrueshme për çdo endpoint që lëshon fatura. Ajo shërben si çelës idempotence, prandaj
një kërkesë e dërguar dy herë nuk krijon dy fatura. E njëjta fushë ju lejon ta gjeni më
vonë faturën me POST /invoice/details/{internalId} pa ruajtur id-në tonë.
Mos u mbështetni vetëm te kodi HTTP. Para se të lexoni data, verifikoni që
status është true. Në rast gabimi, mesazhet vijnë në vargun
errors dhe duhet të shfaqen ose të ruhen në log, sepse aty ndodhet arsyeja
e vërtetë e refuzimit nga tatimet.
{
"status": false,
"message": "Mesazhi i gabimit",
"errors": ["Detaji i pare", "Detaji i dyte"]
}Kur bie lidhja
Fiskalizimi kërkon internet, por shitja nuk mund të ndalet. Kur lidhja me tatimet bie, fatura ruhet dhe dërgohet automatikisht sapo shërbimi kthehet, brenda afatit ligjor prej 48 orësh. Ju nuk keni pse ta implementoni këtë radhë riprovimi, sepse ekziston tashmë dhe punon njësoj për faturat që vijnë nga API-ja.
Për biznese ku edhe interneti i vetë lokalit është i pasigurt, ekziston agjenti lokal, që pret në kompjuterin e biznesit dhe mban arkën në punë edhe kur lidhja mungon fare. Ky është modul shtesë. Na kontaktoni nëse ju duhet.
Integrime të gatshme
Nëse platforma juaj është një nga ato që kemi mbuluar tashmë, mund të mos ju duhet fare të shkruani kod. Lidhja me Shopify dhe me Wolt është e ndërtuar, dhe të njëjtat endpoint-e që përdorin ato janë të hapura për çdo integrim tjetër.
Gjendjen e shërbimit të fiskalizimit e publikojmë hapur te statusi i fiskalizimit, që ta dini nëse një problem vjen nga integrimi juaj apo nga tatimet.
Pyetje dhe përgjigje
Çfarë është API-ja e fiskalizimit?
Është një ndërfaqe REST që lejon një sistem tjetër, ERP, dyqan online ose aplikacion i shkruar nga ju, të lëshojë fatura të fiskalizuara pa e hapur fare fature.al. Ju dërgoni faturën si JSON, ne e nënshkruajmë dhe e regjistrojmë te Sistemi Qendror i Informacionit i Drejtorisë së Tatimeve, dhe ju kthejmë NIVF, NSLF, URL-në e verifikimit dhe PDF-në.
A mund të lidhet sistemi im drejtpërdrejt me fiskalizimin, pa ofrues të certifikuar?
Jo në praktikë. Fatura duhet të nënshkruhet me certifikatën elektronike të tatimpaguesit dhe të formohet saktësisht siç e pret shërbimi i fiskalizimit, dhe software-i që e lëshon duhet të jetë i certifikuar. Prandaj integrimi bëhet përmes një ofruesi të certifikuar, që merr përsipër nënshkrimin, XML-në, ruajtjen e detyrueshme dhe rifiskalizimin.
Cila gjuhë programimi duhet përdorur?
Çdo gjuhë që bën kërkesa HTTP. API-ja është REST me JSON, pa SDK të detyrueshëm dhe pa SOAP nga ana juaj. PHP, C#, Java, Python, Go, Node.js ose çfarëdo tjetër punojnë njësoj, sepse e vetmja gjë që duhet është një POST me tre header dhe një trup JSON.
A më duhet certifikata elektronike dhe pajisja TCR?
Po, ato i përkasin biznesit që lëshon faturën, jo software-it. Certifikata ngarkohet një herë, njësia e biznesit dhe pajisja fiskale konfigurohen një herë, pastaj çdo faturë e mëpasshme kalon vetëm me një kërkesë. Të gjitha këto hapa mund t'i bëni edhe vetë me API, pa hyrë në panel.
Sa zgjat fiskalizimi i një fature përmes API-t?
Fatura fiskalizohet brenda së njëjtës kërkesë. Përgjigja nuk kthehet derisa Sistemi Qendror ta ketë validuar faturën dhe të ketë kthyer NIVF-në, prandaj kur merrni status true fatura është tashmë e regjistruar dhe mund t'i jepet klientit.
Çfarë kthen API-ja pas fiskalizimit?
Numrin e faturës, NSLF-në që gjenerohet nga software-i lëshues, NIVF-në që kthen Sistemi Qendror, kodin e pajisjes fiskale, kodin e njësisë së biznesit, kodin e operatorit, URL-në e verifikimit që fshihet pas kodit QR dhe një lidhje ku e merrni PDF-në e faturës.
A anulohet një faturë e fiskalizuar përmes API-t?
Po, me endpoint-in e anullimit, sipas id-së ose sipas internalId-së tuaj. Ligji nuk njeh fshirje të një fature të regjistruar, prandaj anullimi realizohet me një faturë korrigjuese që i referohet origjinalit dhe mban vlera negative.
A ka sandbox për të testuar pa pasoja?
Po. I gjithë integrimi ndërtohet kundrejt demo.fature.al, ku faturat nuk kanë vlerë fiskale. Kur rrjedha juaj është e plotë, ndryshoni vetëm adresën bazë në fature.al. Struktura e kërkesave dhe e përgjigjeve është e njëjtë në të dy mjediset.
Sa fatura mund të dërgoj në minutë?
Endpoint-et që lëshojnë fatura fiskale pranojnë deri në 30 kërkesa në minutë dhe 600 në orë për përdorues, ndërsa dërgimi në grup ka limit më të ulët. Kur limiti arrihet, kthehet statusi 429 bashkë me header-in Retry-After. Për volume vazhdimisht të larta na kontaktoni.
Si të fillosh
Hapni një llogari falas, gjeneroni token-in nga Konfigurime dhe API Tokens, dhe dërgoni
kërkesën e parë kundrejt demo.fature.al. Referenca e plotë me çdo fushë dhe
çdo përgjigje është te dokumentacioni i API-t, i disponueshëm
edhe si OpenAPI JSON dhe si Markdown për asistentët AI.
Nëse jeni shtëpi software-i dhe doni t'i sillni klientët tuaj mbi fature.al, shkruajini [email protected]. Ju japim kredencialet e aplikacionit dhe një mjedis prove, dhe ju ndihmojmë me rastet e para.