Hyrje në API

Fiscal Pro ofron një REST API të plotë për integrimin e sistemeve tuaja (POS, ERP, e-commerce) me fiskalizimin shqiptar: autentikim, fatura të thjeshta (B2C) dhe elektronike (B2B), fatura shoqëruese (WTN), arka (TCR), produkte, klientë dhe raporte. Kjo faqe mbulon autentikimin, ciklin bazë të fiskalizimit të një fature të thjeshtë dhe formatin e gabimeve.

• Adresa bazë e API-t: https://api.fiskalpro.com.al
• Dokumentacioni interaktiv (Swagger UI): https://api.fiskalpro.com.al/docs

Parakushtet

Para se të fiskalizoni faturën e parë, biznesi juaj duhet të ketë të konfiguruara në Fiscal Pro:

1. Biznesin — me NIPT/NUIS, emër dhe adresë.
2. Certifikatën elektronike — skedari PKCS#12 (.p12) i ngarkuar në platformë.
3. Njësinë e biznesit — të paktën një njësi aktive me kodin e saj nga CIS.
4. Kodin e software-it — i caktuar nga AKSHI.
5. Arkën (TCR) — të regjistruar dhe aktive (e detyrueshme për faturat kesh).
6. Kodin e operatorit — për përdoruesin që lëshon faturat.

Autentikimi

API mbështet dy metoda: çelësat API (të rekomanduar për integrime) dhe token-at JWT.

Çelësat API (të rekomanduar)

Çelësi krijohet nga paneli web te Cilësimet > Çelësat API me veprimin Krijo Çelës API. Kopjojeni menjëherë — shfaqet vetëm një herë. Formati: fp_live_ + 48 karaktere heksadecimale.

Dërgojeni në secilën kërkesë me njërin nga dy header-at (të barasvlershëm):

curl -X GET https://api.fiskalpro.com.al/api/receipts \
  -H "X-API-Key: fp_live_a3f9c2e1..."

ose Authorization: Bearer fp_live_a3f9c2e1.... Çelësi lidhet automatikisht me biznesin tuaj (nuk dërgoni businessId në kërkesa) dhe çdo veprim regjistrohet në gjurmën e auditimit.

JWT (për aplikacione me hyrje përdoruesi)

1. Hyrja — POST /api/auth/login:

curl -X POST https://api.fiskalpro.com.al/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "ju@shembull.al", "password": "fjalekalimi" }'

Përgjigjja kthen accessToken dhe refreshToken:

{
  "success": true,
  "data": {
    "user": { "id": "...", "email": "...", "role": "USER", "businessId": "..." },
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi..."
  }
}

2. Përdorimi — dërgoni token-in në çdo kërkesë: Authorization: Bearer {accessToken}.

3. Rifreskimi — accessToken skadon pas 24 orësh; merrni një të ri me POST /api/auth/refresh duke dërguar { "refreshToken": "..." }.

Fluksi i fiskalizimit të një fature të thjeshtë

Fiskalizimi i një fature kesh kalon në tre hapa: krijoni draftin, fiskalizojeni dhe përdorni kodet e kthyera (IIC, FIC, QR).

Hapi 0 — merrni arkën (TCR): listoni arkat me GET /api/tcr dhe përdorni id-në e arkës si tcrDeviceId.

Hapi 1 — krijoni draftin:

curl -X POST https://api.fiskalpro.com.al/api/receipts \
  -H "X-API-Key: fp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tcrDeviceId": "id-e-arkes",
    "receiptType": "CASH",
    "paymentMethod": "BANKNOTE",
    "currency": "ALL",
    "items": [
      { "name": "Produkt 1", "quantity": 2, "priceBeforeVAT": 100,
        "priceAfterVAT": 120, "vatRate": 20, "rebate": 0 }
    ]
  }'

Fatura krijohet me statusin DRAFT; numri përfundimtar i faturës caktohet gjatë fiskalizimit, jo në draft. receiptType është CASH (numri i faturës me kod arke) ose NONCASH (pa kod arke).

Hapi 2 — fiskalizoni:

curl -X POST https://api.fiskalpro.com.al/api/receipts/{id}/fiscalize \
  -H "X-API-Key: fp_live_..."

Përgjigjja e suksesshme kthen kodet fiskale:

{
  "success": true,
  "data": {
    "invoiceNumber": "1/2025/dp408gc613",
    "status": "FISCALIZED",
    "iic": "F4A7B2C3D4E5F6G7H8I9J0K1L2M3N4O5",
    "fic": "ABC123DEF456",
    "qrVerificationUrl": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?iic=...",
    "fiscalizedAt": "2025-01-05T10:30:00Z"
  }
}

Hapi 3 — kodi QR: gjeneroni kodin QR nga qrVerificationUrl dhe printojeni në faturë; klienti e verifikon faturën në faqen zyrtare të DPT-së.

Kujdes me aritmetikën e TVSH-së: CIS kërkon saktësi të plotë (PriceBeforeVAT + TVSH = PriceAfterVAT për çdo artikull dhe në totale), përndryshe fiskalizimi refuzohet. Normat shqiptare të TVSH-së: 0%, 6%, 20%.

Formati i gabimeve

Të gjitha gabimet kthehen në një format të njëjtë:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Mesazh i lexueshëm",
    "details": {}
  }
}

Kodet më të zakonshme:

Kodi	HTTP	Kuptimi
UNAUTHORIZED	401	Token ose çelës i pavlefshëm a i skaduar
FORBIDDEN	403	Të drejta të pamjaftueshme
NOT_FOUND	404	Burimi nuk u gjet
VALIDATION_ERROR	400	Të dhëna të pavlefshme në kërkesë
FISCALIZATION_FAILED	500	Fiskalizimi dështoi në CIS
INTERNAL_ERROR	500	Gabim serveri

Kur dështon vetë CIS-i, details përmban kodin e gabimit të kthyer nga administrata tatimore — p.sh. 10 (certifikatë e skaduar), 30 (arka joaktive), 40 (IIC i dyfishtë), 59 (gabim aritmetik i shumave), 60 (format i pavlefshëm i numrit të faturës).

Kur CIS-i nuk arrihet fare, fatura ruhet me statusin PENDING_SYNC dhe mund të rifiskalizohet më vonë me POST /api/receipts/sync-all.

Referenca të mëtejshme

• Swagger UI: https://api.fiskalpro.com.al/docs — të gjitha endpoint-et me skema dhe mundësi testimi.
• Verifikimi i faturave (DPT): https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify
• Praktika sigurie: mos i vendosni kurrë çelësat API në kod klienti; ruajini si sekrete në server dhe rrotullojini periodikisht nga paneli.