fature.al API
fature.al është platforma e faturimit dhe e fiskalizimit për bizneset në Shqipëri. Me këtë API sistemi juaj lëshon fatura të fiskalizuara pa u marrë vetë me certifikata, nënshkrim XML dhe SOAP: dërgoni faturën si JSON dhe merrni mbrapsht dokumentin e regjistruar te administrata tatimore, me kodet fiskale, URL-në e verifikimit dhe PDF-në.
Termat e këtij dokumentacioni (fiskalizim, NIPT, TCR, IIC, FIC) shpjegohen te Konceptet bazë.
Në pak rreshta#
| Versioni për të ndërtuar | v1 |
| Versione në përdorim | v1 dhe v2, krahas njëri-tjetrit |
| Live | https://fature.al/api/v1 |
| Sandbox | https://demo.fature.al/api/v1 |
| Formati | JSON në kërkesë dhe në përgjigje, UTF-8 |
| Identifikimi | Bearer token i përdoruesit; ofruesit e software-it dërgojnë edhe client id dhe client secret të aplikacionit |
| Kufiri i përgjithshëm | 300 kërkesa në minutë për token, 120 në minutë për IP pa token; kalimi kthen 429 |
Versioni është pjesë e rrugës: /invoice/cash do të thotë https://fature.al/api/v1/invoice/cash.
Ndërtoni kundrejt sandbox-it dhe kaloni në live duke ndryshuar vetëm adresën bazë.
Për kë është#
- Programe kontabiliteti dhe ERP, që e lëshojnë faturën aty ku bëhet shitja.
- Dyqane online, që e kthejnë porosinë e paguar në faturë në të njëjtin çast.
- Programe arke, bari dhe restoranti, me porosi që hapen dhe mbyllen me një pagesë.
- Ofrues software-i, që e instalojnë të njëjtin program te shumë biznese, secili me identitetin e vet fiskal.
Çfarë ju duhet para thirrjes së parë#
| Ju duhet | Ku e merrni |
|---|---|
| Një llogari në fature.al, me abonim që përfshin modulet që do të përdorni | fature.al, ose demo.fature.al për sandbox |
| Një API token | Në panelin e fature.al, te Konfigurime > API Tokens. Token-i është i përdoruesit, jo i kompanisë |
| Client id dhe client secret të aplikacionit, nëse jeni ofrues software-i | Nga fature.al, kur regjistrohet integrimi juaj. Shihni Identifikimi |
| Certifikata elektronike e biznesit, e ngarkuar në fature.al | Biznesi e merr nga e-Albania dhe e ngarkon një herë në panel |
| Për fatura cash: një pajisje fiskale (TCR) e lidhur me përdoruesin e token-it | Konfigurohet nga biznesi në panel, ose nga ju me endpoint-et e regjistrimit |
Thirrja e parë e dobishme është GET /account: ju thotë me cilin biznes, njësi biznesi dhe pajisje
fiskale po punoni.
Çfarë mbulon#
- Faturat: cash, jo-cash, e-faturë, porosi me përmbledhëse, bulk jo-cash dhe fletë shoqëruese (WTN), me listë, detaje, anulim dhe PDF.
- Klientët dhe produktet, si të dhëna që ndahen mes sistemit tuaj dhe fature.al.
- Arka fiskale: hapja dhe mbyllja e balancës, hyrjet dhe daljet e parave.
- Llogaritë bankare dhe monedhat, bashkë me kursin e ditës.
- Faturat e blerjes, të tërhequra nga CIS-i.
- Raportet, të llogaritura në server.
- Regjistrimi i kompanive, për ofruesit që hapin llogari për klientët e tyre.
Një pamje e plotë është te Çfarë mund të ndërtoni.
Si lexohet një përgjigje#
Çdo përgjigje është JSON. Lexoni së pari kodin HTTP. Në 200, fusha status thotë nëse veprimi u
krye (true, rezultati te data) ose u refuzua (false, arsyeja te message). Në 422, përgjigja
e validimit përdor fushën success në vend të status, dhe errors është objekt sipas fushës.
{"status": true, "data": {"...": "..."}}
{"status": false, "message": "Përshkrimi i gabimit", "errors": ["Mesazhi për përdoruesin"]}
Tabela e plotë e kodeve është te Gabimet.
Nga ku të filloni#
- Konceptet bazë shpjegon fiskalizimin dhe termat.
- Fillimi i shpejtë ju çon nga token-i te fatura e parë.
- Identifikimi mbulon token-in dhe kredencialet e aplikacionit.
Ky API shërben 2 versione:
v2 (paralel me v1), v1 (aktual). Integrimet e reja shkruhen mbi v1.
- Versioni
- 1.0.0
- Adresa bazë
- https://fature.al
- Endpoint-e
- 116
For machines
Every page here is also available in a form an agent or a crawler can read directly.
- openapi.json
- OpenAPI 3.1, so generated clients get real JSON Schema.
- llms.txt
- A one-line-per-endpoint index for retrieval models.
- llms-full.txt
- The entire API as Markdown in one file.
- /.well-known/api-docs
- Discovery, from one guessable URL.
Every endpoint page has a Markdown twin: swap
.html for
.md on any of them.
Si të fillosh
- Hyrje API-ja e fature.al ju jep fiskalizimin shqiptar si shërbim. Dërgoni një faturë si JSON dhe merrni një dokument të fiskalizuar, me IIC, FIC, URL verifikimi dhe PDF.
- Konceptet bazë Çfarë është fiskalizimi, cilat subjekte qëndrojnë pas një token-i, cilat dokumente lëshon API-ja, cilët identifikues kthen dhe një fjalorth i termave.
- Fillimi i shpejtë Nga token-i deri te fatura e parë e lëshuar me API-n e fature.al, në tri thirrje.
- Çfarë mund të ndërtoni Çfarë bën API-ja për ju dhe cilat të dhëna ju jep që nuk i keni vetë: regjistrin e NIPT-eve, faturat e blerjes nga CIS-i dhe kursin e ditës.
- Identifikimi Çdo endpoint kërkon bearer token-in e përdoruesit. Aplikacionet e ofruesve të software-it dërgojnë edhe client id dhe client secret, që tregojnë cili program po thërret.
- Versionet e API-t v1 është API-ja e plotë dhe ajo mbi të cilën ndërtohet. v2 mbulon faturat me pagesë të ndarë, klientët në formatin e ri dhe fletët shoqëruese me internalId të detyrueshëm, dhe përdoret krahas v1. Asnjë version nuk është në dalje.
- Ndryshimet Çdo shtesë në API sipas datës, nga më e reja te më e vjetra. Asnjë fushë ekzistuese nuk ka ndryshuar kuptim dhe asnjë endpoint nuk është hequr.
- Gabimet Si lexohet një përgjigje, kodet HTTP që kthen kjo API dhe çfarë të bëni pas secilit. Validimi përdor success në vend të status, dhe një refuzim pas validimit vjen me 200.
- Kufiri i kërkesave Çfarë e kufizon një integrim me fature.al: kufiri i përgjithshëm për token, anulimet, një kërkesë në proces njëkohësisht dhe buxheti për grup endpoint-esh.
- Pagination Listat nuk kanë të gjitha të njëjtin pagination. Cili endpoint pranon limit me offset, cili pranon page, dhe ku qëndron numri i përgjithshëm.
Shembuj
- Dokumentet që lëshon API-ja Nga emri që përdor programi juaj te endpoint-i që e lëshon. Faturë fiskale, cash, e-faturë, parapagim rezervimi dhe grupi, notë krediti, notë debiti, faturë korrigjuese, proformë dhe faturë informative.
- Llojet e faturave Cash, jo-cash, e-faturë, porosi me përmbledhëse, bulk jo-cash dhe fletë shoqëruese (WTN). Cili endpoint lëshon cilin dokument, dhe cilat fusha ndryshojnë mes tyre.
- Fatura elektronike Çfarë e ndan një faturë elektronike nga një faturë e zakonshme jo-cash, dhe si zgjidhet doc_type me process për secilin dokument.
- Zbritjet në faturë Si zbritet një faturë nga API, si zbritet një rresht i vetëm, si lexohen përqindja dhe vlera fikse dhe çfarë kthehet në përgjigje.
Ping (v1)
Një thirrje që nuk prek asgjë, për të provuar lidhjen dhe token-in. Hapi i parë i çdo integrimi dhe kontrolli më i thjeshtë kur diçka nuk përgjigjet.
Llogaria (v1)
Përdoruesi që mban token-in dhe konteksti me të cilin do të lëshohen faturat: kompania me NIPT-in e saj, njësia e biznesit, pajisja fiskale (TCR), të drejtat dhe modulet e abonimit.
Faturat (v1)
Lëshimi i faturave dhe gjithçka që vjen pas tij: cash, jo-cash, e-faturë, porosi, përmbledhëse dhe bulk jo-cash, si dhe lista, detajet, anulimi dhe dokumenti për printim.
-
GET
/api/v1/invoiceListo faturat -
POST
/api/v1/invoice/bulk-noncashLësho fatura jo-cash në bulk -
POST
/api/v1/invoice/cancel-by-internal-id/{internalId}Anulo një faturë sipas internalId -
POST
/api/v1/invoice/cancel/{id}Anulo një faturë sipas id -
POST
/api/v1/invoice/cashLësho faturë cash -
GET
/api/v1/invoice/details/{internalId}Merr një faturë sipas internalId -
POST
/api/v1/invoice/details/{internalId}Merr një faturë sipas internalId -
POST
/api/v1/invoice/e-invoiceLësho e-faturë -
POST
/api/v1/invoice/noncashLësho faturë jo-cash -
POST
/api/v1/invoice/orderLësho faturë porosi -
GET
/api/v1/invoice/print-eic/{eic}Shkarko PDF-në e e-faturës sipas EIC -
GET
/api/v1/invoice/print/{id}Shkarko dokumentin e faturës -
POST
/api/v1/invoice/summaryLësho faturë përmbledhëse -
GET
/api/v1/invoice/{id}/detailsMerr një faturë sipas id
Klientët (v1)
Klientët e kompanisë, blerësit që dalin në faturë: lista, detajet, krijimi dhe përditësimi, si dhe kërkimi i një biznesi sipas NIPT-it në regjistrin fiskal.
Produktet (v1)
Katalogu i produkteve dhe i shërbimeve të kompanisë, me kategoritë e tyre: lista, detajet, krijimi dhe përditësimi.
Arka fiskale (v1)
Dita e punës në pajisjen fiskale (TCR) të përdoruesit të token-it: hapja e ditës, hyrjet dhe daljet e parave, mbyllja e ditës, gjendja në çdo moment dhe historiku i veprimeve. Shumat janë gjithmonë në ALL.
-
GET
/api/v1/cash-register/actionsListo veprimet e arkës -
GET
/api/v1/cash-register/balanceMerr gjendjen e arkës -
POST
/api/v1/cash-register/close-balanceMbyll ditën në arkë -
POST
/api/v1/cash-register/depositRegjistro hyrje parash -
POST
/api/v1/cash-register/open-balanceHap ditën në arkë -
POST
/api/v1/cash-register/withdrawRegjistro dalje parash -
GET
/api/v1/mobile/cash-register/actionsVeprimet e arkes per aplikacionet mobile: vetem ato te perdoruesit te token-it ne arken e tij te tanishme. Nje perdorues qe ka punuar me pare ne nje arke tjeter nuk i sheh ato, dhe as veprimet e kolegeve ne kete arke
Llogaritë bankare (v1)
Llogaritë bankare të kompanisë, ato që dalin si informacion pagese në faturat jo-cash dhe në e-faturat.
Monedhat (v1)
Monedhat e konfiguruara për kompaninë dhe kursi i këmbimit i ditës nga kursi.al. Ju duhen kur lëshoni fatura ose ruani produkte në monedhë tjetër nga ALL: currency merr kodin nga lista, dhe exchange_rate i faturës kursin.
Fletët shoqëruese (v1)
Fletët shoqëruese (WTN) për mallin që lëviz midis njësive ose drejt një klienti pa qenë shitje: lëshimi, lista, detajet dhe të dhënat për printim.
Faturat e blerjes (v1)
Faturat që furnitorët i kanë lëshuar kompanisë, ashtu siç i ka regjistruar CIS-i. Vetëm lexim: këto dokumente nuk lëshohen këtu, dhe nuk vijnë nga furnitori, por nga sistemi qendror i fiskalizimit.
Raportet (v1)
Shifra të grumbulluara mbi një periudhë: shitjet, TVSH-ja, ecuria ditore, klientët dhe produktet kryesore, shitjet sipas operatorit dhe sipas pajisjes fiskale, arka dhe fletët shoqëruese.
-
GET
/api/v1/reports/by-operatorMerr shitjet sipas operatorit -
GET
/api/v1/reports/by-tcrMerr shitjet sipas pajisjes fiskale -
GET
/api/v1/reports/cash-registerMerr gjendjen e arkës për një ditë -
GET
/api/v1/reports/cash-register/closingMerr raportin e mbylljes së arkës -
GET
/api/v1/reports/daily-trendMerr ecurinë ditore -
GET
/api/v1/reports/reversalsListo faturat e anuluara -
GET
/api/v1/reports/sales-summaryMerr përmbledhjen e shitjeve -
GET
/api/v1/reports/top-clientsListo klientët kryesorë -
GET
/api/v1/reports/top-productsListo produktet më të shitura -
GET
/api/v1/reports/vatMerr raportin e TVSH-së -
GET
/api/v1/reports/wtnMerr raportin e fletëve shoqëruese
Paneli (v1)
Përmbledhja e ditës në një thirrje të vetme: turni i hapur dhe gjendja e arkës, shitjet e sotme orë pas ore, dhe java e fundit përballë asaj të mëparshme.
Regjistrimi i kompanive (v1)
Për ofruesit e software-it që u hapin vetë llogari klientëve të tyre në fature.al. Grupi është i mbyllur si parazgjedhje dhe hapet me kërkesë.
-
GET
/api/v1/registerKontrollo aksesin në regjistrim -
POST
/api/v1/registerRegjistro një kompani -
POST
/api/v1/on-boarding/branch/{id}Përditëso një njësi biznesi -
POST
/api/v1/on-boarding/user/{id}Përditëso një përdorues -
POST
/api/v1/on-boarding/certificateNgarko certifikatën elektronike -
POST
/api/v1/on-boarding/bank-accountKrijo një llogari bankare -
POST
/api/v1/on-boarding/fiscal-deviceRegjistro një pajisje fiskale -
POST
/api/v1/on-boarding/branchKrijo një njësi biznesi -
POST
/api/v1/on-boarding/userKrijo një përdorues
Ai (v1)
Mobile (v1)
-
POST
/api/v1/mobile/pos-shift/closeClose -
GET
/api/v1/mobile/pos-shift/currentCurrent -
POST
/api/v1/mobile/pos-shift/openOpen -
GET
/api/v1/mobile/pos-shift/{id}/reportTe dhenat e raportit te turnit (Z), qe aplikacioni e printon vete ne printerin termik. Vetem turnet e perdoruesit te token-it -
GET
/api/v1/mobile/pos-shiftsTurnet e perdoruesit te token-it, me te rinjte ne krye, qe aplikacioni te zgjedhe faturat e cilit turn te shfaqe me `GET /invoice?id_pos_shift=` -
GET
/api/v1/mobile/products/stockList mobile -
GET
/api/v1/mobile/products/{id}/stockRetrieve a mobile -
POST
/api/v1/mobile/switch-userSwitch To -
GET
/api/v1/mobile/switch-user/candidatesKolegët që mund të hyjnë ne kete telefon, me emrin qe shfaq lista
Wolt Partner API
Ana e njësisë (venue) në një integrim me Wolt: lexoni feed-in e porosive, pranoni ose refuzoni çfarë mbërrin, çojeni porosinë nëpër marrjen nga korrieri dhe dorëzimin, dhe merrni faturën fiskale që ajo lëshoi.
-
GET
/api/partner/v1/wolt/eventsLexo feed-in e ngjarjeve -
GET
/api/partner/v1/wolt/ordersListo porositë -
GET
/api/partner/v1/wolt/orders/{id}Merr një porosi -
POST
/api/partner/v1/wolt/orders/{id}/acceptPrano një porosi -
POST
/api/partner/v1/wolt/orders/{id}/confirm-preorderKonfirmo një porosi të paraporositur -
POST
/api/partner/v1/wolt/orders/{id}/courier-at-customerShëno korrierin te klienti -
POST
/api/partner/v1/wolt/orders/{id}/deliveredShëno porosinë të dorëzuar -
GET
/api/partner/v1/wolt/orders/{id}/invoiceMerr faturën fiskale të porosisë -
POST
/api/partner/v1/wolt/orders/{id}/pickup-completedShëno marrjen nga korrieri -
POST
/api/partner/v1/wolt/orders/{id}/readyShëno porosinë gati -
POST
/api/partner/v1/wolt/orders/{id}/rejectRefuzo një porosi -
POST
/api/partner/v1/wolt/orders/{id}/retry-fiscalizeRiprovo fiskalizimin -
GET
/api/partner/v1/wolt/pingKontrollo lidhjen
Faturat (v2)
Lëshimi i faturave dhe gjithçka që vjen pas tij: cash, jo-cash, e-faturë, porosi, përmbledhëse dhe bulk jo-cash, si dhe lista, detajet, anulimi dhe dokumenti për printim.
-
GET
/api/v2/invoiceListo faturat -
POST
/api/v2/invoice/bulk-noncashLësho fatura jo-cash në bulk -
POST
/api/v2/invoice/cancel-by-internal-id/{internalId}Anulo një faturë sipas internalId -
POST
/api/v2/invoice/cancel/{id}Anulo një faturë sipas id -
POST
/api/v2/invoice/cashLësho faturë cash -
GET
/api/v2/invoice/details/{internalId}Merr një faturë sipas internalId -
POST
/api/v2/invoice/details/{internalId}Merr një faturë sipas internalId -
POST
/api/v2/invoice/e-invoiceLësho e-faturë -
POST
/api/v2/invoice/noncashLësho faturë jo-cash -
POST
/api/v2/invoice/orderLësho faturë porosi -
GET
/api/v2/invoice/print-eic/{eic}Shkarko PDF-në e e-faturës sipas EIC -
GET
/api/v2/invoice/print/{id}Shkarko dokumentin e faturës -
POST
/api/v2/invoice/summaryLësho faturë përmbledhëse -
GET
/api/v2/invoice/{id}/detailsMerr një faturë sipas id
Klientët (v2)
Klientët e kompanisë në formatin e v2: objekte të ndara company, person, address dhe contact, me fushën type (company ose person) që thotë cili nga dy të parët është i plotësuar, dhe identifikuesin si objekt id me type dhe value.
Arka fiskale (v2)
Dita e punës në pajisjen fiskale (TCR) të përdoruesit të token-it: hapja e ditës, hyrjet dhe daljet e parave, mbyllja e ditës, gjendja në çdo moment dhe historiku i veprimeve. Shumat janë gjithmonë në ALL.
-
GET
/api/v2/cash-register/actionsListo veprimet e arkës -
GET
/api/v2/cash-register/balanceMerr gjendjen e arkës -
POST
/api/v2/cash-register/close-balanceMbyll ditën në arkë -
POST
/api/v2/cash-register/depositRegjistro hyrje parash -
POST
/api/v2/cash-register/open-balanceHap ditën në arkë -
POST
/api/v2/cash-register/withdrawRegjistro dalje parash
Fletët shoqëruese (v2)
Fletët shoqëruese (WTN) për mallin që lëviz midis njësive ose drejt një klienti pa qenë shitje: lëshimi, lista, detajet dhe të dhënat për printim.
-
GET
/api/v2/invoice/wtnListo fletët shoqëruese -
POST
/api/v2/invoice/wtnLësho fletë shoqëruese -
GET
/api/v2/invoice/wtn/details/{internalId}Merr një fletë shoqëruese sipas internalId -
GET
/api/v2/invoice/wtn/print/{id}Merr fletën shoqëruese për printim -
GET
/api/v2/invoice/wtn/{id}/detailsMerr një fletë shoqëruese sipas id
Faturat e blerjes (v2)
Faturat që furnitorët i kanë lëshuar kompanisë, ashtu siç i ka regjistruar CIS-i. Vetëm lexim: këto dokumente nuk lëshohen këtu, dhe nuk vijnë nga furnitori, por nga sistemi qendror i fiskalizimit.
Regjistrimi është falas.
Regjistrohu në fature.al