Hyrje
Fiskaliza API është një gateway me çelësa API përpara shërbimit të fiskalizimit Njolla — regjistro POS-e, lësho shitje dhe merr kuponë fiskalë përmes HTTP.
Fiskaliza API është një gateway me çelësa API përpara shërbimit të fiskalizimit Njolla. Ti dërgon shitjen; Fiskaliza e llogarit, e fiskalizon te ATK dhe ta kthen kuponin gati për t'u dorëzuar te klienti.
Ky dokumentacion mbulon versionin 1.3.0.
Një çelës, një sipërfaqe
Kjo është gjëja e parë që duhet kuptuar për API-në:
| Sipërfaqja | Kredenciali | Për çfarë shërben |
|---|---|---|
/v1 | Çelës Fiskaliza (fsk_…) | Gjithçka: POS, shitje, kuponë, operacione |
/health | asnjë | Prova liveness dhe readiness |
Çelësi e mban vetë kontekstin
Një çelës API është i lidhur me një biznes dhe me një grup fiks
aftësish. Prandaj asnjë kërkesë në /v1 nuk merr identifikues biznesi —
Fiskaliza e nxjerr vetë nga çelësi.
Modeli i API-së
POS
Një pikë shitjeje, e identifikuar me aliasin publik nj_pos_…. Mban adresën, zonën kohore, operatorin e parazgjedhur dhe certifikatën e nënshkrimit.
Command
Një ngjarje fiskale — SALE, RETURN ose CANCELLATION. Çdo lloj ka rrugën e vet.
Coupon
Rezultati fiskal i një komande të suksesshme: numri i kuponit ditor, numri i verifikimit dhe payload-i i QR-së.
Receipt document
Kuponi i rendëruar dhe i pandryshueshëm në PDF. ORIGINAL-i lëshohet bashkë me komandën; të mëvonshmit janë COPY.
Rrjedha tipike:
regjistro POS -> lësho shitje -> prit kuponin -> shkarko kuponin PDFZarfi i përgjigjes
Çdo përgjigje JSON është e mbështjellë. Kjo vlen edhe për gabimet.
{ "success": true, "data": { "command": { "…": "…" } } }{ "success": false, "errors": ["insufficient_capability"] }Të dyja mund të mbajnë një varg opsional warnings. Fusha errors përmban
kode të qëndrueshme, jo tekst për përdoruesin — mos i shfaq drejtpërdrejt
dhe mos i analizo si prozë.
Skemat në referencë e modelojnë zarfin, prandaj data shfaqet e ndërthurur
saktësisht siç vjen në rrjet. Mos harro ta hapësh një nivel.
Base URL
Çelësat test dhe live përdorin të njëjtën adresë publike:
| Serveri | URL |
|---|---|
| Zhvillim lokal | http://fiskaliza.localhost/api |
| Prodhim | https://fiskaliza.com/api |
Çelësi zgjedh ambientin
Çelësi i autentikuar fsk_test_… ose fsk_live_… zgjedh realm-in e izoluar
të core-it. Mos e ndrysho URL-në bazë kur kalon nga një modalitet në tjetrin.
Konventat
- Vlerat monetare janë numra të plotë në cent; fushat mbarojnë me
_cents.EUR 1.18shkruhet118. - Çmimet e artikujve janë me taksë të përfshirë.
- Të gjitha shumat janë në EUR.
- Sasitë janë numra dhjetorë me maksimum tre shifra pas presjes.
- Datat janë string-je
date-timesipas RFC 3339. - POS-et identifikohen me aliasin
nj_pos_…; ky është i vetmi identifikues POS-i që API-ja ekspozon. - Krijimi i POS-eve, i komandave dhe i dokumenteve të kuponit kërkon header-in
Idempotency-Key.
Llogaritjet i bën Fiskaliza
Ti dërgon çmime, sasi dhe një kategori tatimore për çdo rresht. Shumat e rreshtave, grupet e taksave dhe totalet e kuponit llogariten prej tyre.