Identifikimi

Të gjitha endpoint-et kërkojnë identifikim. Nuk ka asnjë endpoint publik.

Çdo kërkesë ka dy nivele identifikimi: kush e bën (përdoruesi, me bearer token) dhe cili software e bën (aplikacioni juaj, me client id dhe client secret).

Authorization: Bearer {api_token}
X-Client-Id: ft_id_...
X-Client-Secret: ft_sk_...

Token-i i përdoruesit#

Token-in e gjeneroni nga Konfigurime > API Tokens në panelin e fature.al, ose e merrni nga përgjigja e POST /register. Ai i përket një përdoruesi të biznesit që e përdor software-in tuaj, dhe ndryshon nga njëri biznes te tjetri. Prej tij zgjidhen kompania, njësia e biznesit, operatori dhe pajisja fiskale (shihni Konceptet bazë).

Authorization: Bearer TOKEN_I_JUAJ

Token-i jep akses të plotë në llogari. Ruajeni në server, jo në kodin e shfletuesit apo në aplikacione publike, mos e vendosni në kontrollin e versioneve, dhe rigjenerojeni menjëherë nëse dyshoni se ka rrjedhur.

Kredencialet e aplikacionit#

Nëse software-i juaj përdoret nga më shumë se një biznes, aplikacioni juaj identifikohet me një çift kredencialesh që i dërgoni në çdo kërkesë, krahas token-it të përdoruesit. Një integrim i shkruar për një biznes të vetëm punon vetëm me token-in.

• Client id fillon me ft_id_ dhe është publik. Client secret fillon me ft_sk_ dhe është i fshehtë: trajtojeni si fjalëkalim.
• Të dyja i përkasin aplikacionit tuaj, jo biznesit. Nuk gjenerohen për çdo biznes dhe nuk duhet të përfundojnë në kod që shpërndahet dhe mund të lexohet nga të tjerët.
• Kredencialet nuk e zëvendësojnë token-in dhe nuk hapin asnjë të drejtë më vete.
• Kredencialet e para i merrni nga fature.al kur regjistrohet integrimi juaj. Më pas i shihni dhe i rigjeneroni vetë nga Konfigurime > Zhvillues në llogarinë tuaj në fature.al, ku shihni edhe sa përdorues dhe sa biznese kanë punuar përmes aplikacionit tuaj në 24 orët e fundit.

Secret-i shfaqet vetëm një herë, në momentin që gjenerohet, dhe nuk mund të lexohet më pas. Ruajeni menjëherë.

Rigjenerimi#

Nëse e humbisni ose dyshoni se ka rrjedhur, rigjenerojeni nga i njëjti ekran. Rigjenerimi është i menjëhershëm dhe pa periudhë mbivendosjeje: secret-i i vjetër ndërpritet në kërkesën e parë që vjen pas tij. Përgatisni instalimet tuaja që të marrin secret-in e ri dhe rigjenerojeni vetëm kur jeni gati ta shpërndani menjëherë. Client id nuk ndryshon, kështu që ju mbetet të zëvendësoni një vlerë të vetme.

Header-i User-Agent#

Krahas kredencialeve, në çdo kërkesë dërgoni header-in User-Agent në formatin <emri i aplikacionit>/<versioni i build-it>:

User-Agent: EmriIAplikacionit/2.4.1

• Emri i aplikacionit është gjithmonë i njëjti: në çdo kërkesë, për çdo biznes dhe në çdo version. Ky emër është identifikuesi i integrimit tuaj; mos e varioni sipas kompanisë, pajisjes apo mjedisit. Përdorni shkronja, numra ose shenjat _ . + -, filloni me një shkronjë dhe mos vendosni hapësira.
• Versioni i build-it ndryshon me çdo publikim, p.sh. 2.4.1 ose 2026.07.13. Pa hapësira dhe pa /.

Kredencialet tregojnë cili aplikacion po flet; User-Agent-i tregon cili version i tij është në përdorim. Nëse kredencialet mungojnë, User-Agent-i është e vetmja mënyrë për të identifikuar integrimin tuaj.

Një kërkesë e plotë#

curl https://demo.fature.al/api/v1/account \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'X-Client-Id: ft_id_...' \
  -H 'X-Client-Secret: ft_sk_...' \
  -H 'User-Agent: EmriIAplikacionit/2.4.1' \
  -H 'Accept: application/json'

Kur nuk kalon#

Kredencialet e aplikacionit#

Nëse header-at X-Client-Id dhe X-Client-Secret nuk dërgohen fare, kërkesa vazhdon normalisht dhe integrimi identifikohet vetëm nga User-Agent-i. Çdo ofrues software-i njoftohet paraprakisht për datën nga e cila kredencialet bëhen të detyrueshme për aplikacionin e tij; vetëm pas asaj date kërkesat pa kredenciale refuzohen me 401.

Nëse header-at dërgohen por nuk verifikohen, kërkesa refuzohet menjëherë me 401, pa pritur asnjë datë. Nëse ende nuk i keni kredencialet, mos i dërgoni header-at bosh ose me vlera provizore.

Filloni ta dërgoni çiftin që tani: kërkesat me kredenciale të sakta punojnë njësoj si më parë.