Fillimi i shpejte

Ky udhezues ju con nga zeroja deri te nje fature e fiskalizuar. Zgjat pak minuta dhe nuk kerkon asgje te instaluar pervec curl.

1. Merrni token-in#

Token-i eshte i perdoruesit, jo i kompanise. Gjenerojeni nga fature.al te Konfigurime > API Tokens. Ai identifikon si perdoruesin ashtu edhe biznesin ne emer te te cilit leshohen faturat, prandaj cdo thirrje e mban:

-H 'Authorization: Bearer TOKEN_I_JUAJ'

Nese jeni nje ofrues qe shet nje program per shume biznese, aplikacioni juaj merr edhe nje cift kredencialesh qe dergohen krahas token-it:

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

Cifti tregon cili program po therret, ndersa token-i tregon kush po e perdor. Te dyja duhen kur aplikacioni juaj kalon ne zbatim te detyrueshem.

2. Provoni lidhjen#

GET /api/v1/ping nuk prek asgje dhe kthen kohen e serverit. Eshte menyra me e shpejte per te vertetuar se token-i lexohet:

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

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

Nese merrni 401, token-i nuk po arrin. Kontrolloni qe header-i quhet Authorization dhe qe fjala Bearer eshte para tij.

Pas kesaj, GET /api/v1/account ju kthen te dhenat e llogarise dhe te biznesit, pra konfirmon se po punoni mbi kompanine e duhur.

3. Leshoni faturen e pare#

Nje fature jo-cash eshte fillimi me i thjeshte, sepse nuk kerkon pajisje fiskale te zgjedhur nga ju:

curl -X POST 'https://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 Kavajes 12",
      "city": "Tirane"
    },
    "lines": [
      {
        "product_name": "Sherbim",
        "product_code": "SRV-01",
        "unit": "Cope",
        "unit_code": "C62",
        "quantity": 1,
        "price": 1000,
        "total": 1000,
        "vat": 20
      }
    ]
  }'

Pergjigja mban gjithcka qe duhet ruajtur prane shitjes tuaj:

{
  "status": true,
  "data": {
    "invoice": {
      "id": 40312,
      "number": "1/2026",
      "iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
      "fic": "b3f1c0a2-4d5e-4f60-9a71-2c3d4e5f6071",
      "verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?...",
      "pdf": "https://fature.al/api/v1/invoice/print/40312"
    }
  }
}

internalId eshte celesi juaj#

internalId eshte numri qe fatura ka ne sistemin tuaj, dhe fature.al e ruan ashtu sic e dergoni. Ai ben dy pune:

• Ndalon faturat e dyfishta. I njejti internalId brenda te njejtit vit kthen 409 ne vend qe te leshoje nje fature te dyte. Prandaj nje riprovim pas nje lidhjeje qe u nderpre eshte i sigurt: ose leshohet nje fature, ose merrni 409.
• Ju kursen ruajtjen e ID-se sone. POST /api/v1/invoice/details/{internalId} dhe POST /api/v1/invoice/cancel-by-internal-id/{internalId} punojne me numrin tuaj, pra nuk keni pse te mbani id e fature.al ne bazen tuaj.

Zarfi i pergjigjes#

Nje pergjigje e suksesshme ka gjithmone status: true dhe te dhenat brenda data. Nje gabim ka status: false bashke me message dhe errors.

Perjashtimi i vetem eshte deshtimi i validimit, 422, i cili perdor success: false ne vend te status. Nese kontrolloni vetem status, nje pergjigje 422 do t'ju duket sikur nuk ka statusin fare. Kontrolloni me pare kodin HTTP.

Me tej#

• Raste perdorimi tregon rrjedhat e plota qe ndertohen me shpesh.
• Fatura elektronike mbulon e-faturat, notat e kreditit dhe ato te debitit.
• Faqezimi shpjegon si lexohen listat e gjata.