Fillimi i shpejtë

Tri thirrje ju çojnë nga token-i te fatura e parë e fiskalizuar. Nuk kërkohet asgjë e instaluar përveç curl. Punoni në sandbox, https://demo.fature.al/api/v1, ku faturat nuk kanë vlerë fiskale. Termat që hasni këtu shpjegohen te Konceptet bazë.

1. Merrni token-in#

Token-i është i përdoruesit, jo i kompanisë. Gjenerojeni nga fature.al te Konfigurime > API Tokens. Ai identifikon si përdoruesin ashtu edhe biznesin në emër të të cilit lëshohen faturat, prandaj çdo thirrje e mban:

-H 'Authorization: Bearer TOKEN_I_JUAJ'

Nëse jeni ofrues software-i që përdoret nga shumë biznese, aplikacioni juaj ka edhe një çift kredencialesh që dërgohen krahas token-it:

-H 'X-Client-Id: ft_id_...'
-H 'X-Client-Secret: ft_sk_...'

Çifti tregon cili software po thërret, ndërsa token-i tregon kush po e përdor. Një integrim i shkruar për një biznes të vetëm punon vetëm me token-in. Detajet janë te Identifikimi.

2. Provoni lidhjen#

GET /ping nuk prek asgjë dhe kthen kohën e serverit:

curl https://demo.fature.al/api/v1/ping \
  -H 'Authorization: Bearer TOKEN_I_JUAJ'

{"status": true, "data": {"pong": 1788547330, "ip": ["81.2.3.4"]}}

Një 401 do të thotë që token-i nuk po arrin: kontrolloni që header-i quhet Authorization dhe që fjala Bearer është para tij.

Pas kësaj, GET /account kthen përdoruesin, kompaninë, njësinë e biznesit dhe kodin e pajisjes fiskale, pra konfirmon që token-i i përket biznesit të duhur.

3. Lëshoni faturën e parë#

Një faturë jo-cash është fillimi më i thjeshtë, sepse nuk kërkon pajisje fiskale:

curl -X POST https://demo.fature.al/api/v1/invoice/noncash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "TEST-0001",
    "payment_method": "TRANSFER",
    "client": {"name": "Klient Provë", "address": "Rruga e Kavajës 12", "city": "Tiranë"},
    "lines": [
      {"product_name": "Shërbim", "product_code": "SRV-01", "unit": "copë", "unit_code": "C62",
       "quantity": 1, "price": 1000, "total": 1000, "vat": 20}
    ]
  }'

{
  "status": true,
  "data": {
    "invoice": {
      "id": 40312,
      "number": "1/2026",
      "iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
      "fic": "b3f1c0a2-4d5e-4f60-9a71-2c3d4e5f6071",
      "tcrCode": null,
      "businessCode": "bb123bb123",
      "operatorCode": "aa123aa123",
      "fiscalizedAt": "2026-09-13 10:42:07",
      "verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?iic=...",
      "pdf": "https://demo.fature.al/api/v1/invoice/print/40312"
    }
  }
}

Fatura del menjëherë edhe në panelin e fature.al. Ruani id, number, iic dhe fic pranë shitjes tuaj. Kuptimi i secilit kod është te Konceptet bazë.

Nëse fic vjen null, CIS-i nuk u arrit në çastin e lëshimit: fatura u ruajt dhe fiskalizohet vetë më vonë. Mos e lëshoni përsëri.

internalId është çelësi juaj#

internalId (string, i detyrueshëm në çdo lëshim) është identifikuesi i faturës në sistemin tuaj: numri juaj i faturës ose një UUID. Duhet të jetë unik brenda kompanisë suaj për vitin kalendarik. Ai bën dy punë:

• Nuk krijon dublikata. Kur dërgoni një internalId që ekziston tashmë për këtë vit, serveri nuk lëshon faturë të dytë: kthen faturën ekzistuese me 200. Prandaj një riprovim pas një timeout-i ose një lidhjeje që u ndërpre është i sigurt, me kusht që të përdorni të njëjtin internalId, kurrë një të ri. Nëse riprovoni ndërsa kërkesa e parë nuk ka mbaruar ende (deri në rreth 5 minuta), merrni 409: prisni pak dhe riprovoni.
• Ju kursen ruajtjen e id-së sonë. GET /invoice/details/{internalId} dhe POST /invoice/cancel-by-internal-id/{internalId} punojnë me numrin tuaj.

Si lexohet përgjigja#

Lexoni së pari kodin HTTP. Në 200, status: true do të thotë që rezultati është te data; status: false do të thotë që veprimi u refuzua dhe arsyeja është te message. Në 422, përgjigja e validimit përdor success: false në vend të status, me errors si objekt sipas fushës. Tabela e plotë është te Gabimet.

Më tej#

• Llojet e faturave tregon cilin endpoint të thirrni dhe me çfarë body.
• Fatura elektronike mbulon e-faturat, notat e kreditit dhe të debitit.
• Pagination shpjegon si lexohen listat e gjata.
• Çfarë mund të ndërtoni tregon rrjedhat e plota.