Autentikimi

Kërkesat drejt /v1 autentikohen me një çelës Fiskaliza si bearer token. Aftësitë e çelësit nuk janë scope OAuth.

Çdo kërkesë drejt /v1 autentikohet me një çelës Fiskaliza, i dërguar si bearer token:

curl "$BASE_URL/v1/pos" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY"

Vetëm rrugët /health janë të hapura; gjithçka tjetër kërkon çelësin.

Formati i çelësit

fsk_<mode>_<id>.<secret>

mode është test ose live. Modaliteti caktohet nga deployment-i që e lëshon çelësin — një çelës test nuk shndërrohet në live.

Të dy modalitetet e çelësave përdorin të njëjtën URL bazë publike. Pas autentikimit, modaliteti i verifikuar zgjedh realm-in përkatës të izoluar të core-it; hostname-i i kërkesës nuk e zgjedh ambientin.

Çelësi është sekret serveri

Një çelës Fiskaliza jep akses të plotë fiskal për biznesin e tij. Mbaje vetëm në backend. Mos e vendos kurrë në aplikacione POS, në browser, në apps mobile apo në repository.

Si merret një çelës

Çelësat lëshohen nga Fiskaliza dhe të dërgohen drejtpërdrejt. Kur kërkon një çelës, përcaktohen tri gjëra:

Biznesi të cilit i përket.
Aftësitë (capabilities) që do të mbajë — të paktën një.
Fushëveprimi POS (pos_access): ALL, ose SELECTED me një listë të përcaktuar pos_ids.

Kërko vetëm aftësitë që të duhen. Një shërbim që vetëm lexon komanda nuk ka nevojë për fiskaliza:commands:write.

Çfarë mban një çelës

Çelësi është i lidhur me një biznes. Prandaj asnjë kërkesë /v1 nuk merr business_id — Fiskaliza e nxjerr vetë nga çelësi.

Aftësitë

Aftësia	Lejon
`fiskaliza:pos:manage`	Regjistrim, lexim dhe përditësim POS-esh, plus certifikatat
`fiskaliza:commands:read`	Leximin e komandave dhe artikujve të tyre
`fiskaliza:commands:write`	Lëshimin e shitjeve, kthimeve, anulimeve dhe ritentimeve
`fiskaliza:receipts:issue`	Lëshimin dhe shkarkimin e dokumenteve të kuponit
`fiskaliza:operations:read`	Leximin e përmbledhjes operacionale
`fiskaliza:audit:export`	Eksportimin e evidencës

Aftësitë nuk janë scope OAuth

Në referencë do t'i shohësh aftësitë e listuara në vendin ku OpenAPI pret scope-e. Kjo është kufizim i formatit: OpenAPI nuk ka mënyrë ta shprehë një bearer token me aftësi. Ato janë aftësi të vetë çelësit dhe nuk kërkohen kurrë gjatë ndonjë shkëmbimi token-i.

Nëse çelësit i mungon aftësia që rruga kërkon, përgjigja është 403 me kodin insufficient_capability.

Fushëveprimi POS

Një çelës SELECTED sheh vetëm POS-et në listën e vet; një çelës ALL sheh çdo POS të biznesit. Tri gjëra kërkojnë shprehimisht akses ALL:

POST /v1/pos — një çelës SELECTED nuk mund ta zgjerojë vetë fushëveprimin e tij.
GET /v1/exports/{kind} — një eksport i pjesshëm nuk është evidencë.
Vendosja ose pastrimi i vat_number te PATCH /v1/pos/{pos_id} — është numri i TVSH-së i tatimpaguesit dhe printohet në kuponët e çdo POS-i, jo vetëm të atij që po ndryshohet.

Eksportet duhet të emërtojnë kërkesën që u përgjigjen

GET /v1/exports/{kind} kërkon header-in X-Fiscal-Authority që emërton kërkesën e ATK-së ose të autoritetit shtetëror që po adresohet. Ai regjistrohet në zinxhirin e auditimit. Nuk mund të verifikohet, prandaj ajo që siguron është një zbulim për të cilin mund të jepet llogari më pas.

Rrotullimi i çelësit

Çelësat janë të pandryshueshëm: aftësitë dhe fushëveprimi i tyre nuk përditësohen pas lëshimit. Rrotullimi bëhet me tre hapa:

Kërko një çelës zëvendësues

Me të njëjtat aftësi si i vjetri.

Migro thirrësit

Vendos çelësin e ri në konfigurimin e çdo shërbimi që e përdor dhe konfirmo se trafiku po kalon me të.

Kërko revokimin e të vjetrit

Vetëm pasi migrimi të ketë përfunduar.

Revokimi është i menjëhershëm dhe i pakthyeshëm

Sapo një çelës revokohet, çdo thirrës që ende e mban ndalon së fiskalizuari në atë çast dhe merr 401 invalid_api_key. Nuk ka periudhë hiri.

Përgjigjet e autentikimit

Kodi	`errors`	Kuptimi
`401`	`invalid_api_key`	Çelës i panjohur ose i revokuar
`403`	`insufficient_capability`	Çelësit i mungon aftësia që rruga kërkon
`404`	`resource_not_found`	Burimi mungon, është i huaj ose i paautorizuar

404 është i qëllimshëm

Burimet që mungojnë, ato që i përkasin një biznesi tjetër dhe ato të paautorizuara janë të padallueshme nga njëra-tjetra. Kjo pengon një çelës të zbulojë identifikuesit e bizneseve të tjera. Nëse ID-ja duket e saktë, dyshimi i parë duhet të jetë fushëveprimi i çelësit.

Në këtë faqe