Fatura elektronike

Një faturë elektronike (e-faturë) shkon në platformën e e-faturave, jo vetëm në fiskalizim. Kjo sjell dy gjëra që faturat e tjera nuk i kanë: blerësi duhet të jetë i identifikuar me NIPT dhe me adresë të plotë, dhe dokumenti duhet të thotë se çfarë lloji është.

Lëshohet me POST /api/v1/invoice/e-invoice.

Blerësi duhet të jetë i plotë#

Blerësi shkon i plotë në platformën e e-faturave, prandaj adresa dhe qyteti janë të nevojshme. Mund t'i dërgoni në kërkesë si client.address dhe client.city, ose t'i keni ruajtur më parë te klienti në fature.al. Kur mungon njëra, kërkesa refuzohet me 400 dhe fusha errors thotë saktë çfarë duhet plotësuar.

Kur klienti ekziston tashmë në fature.al, dërgoni vetëm client.internal_id. Atëherë klienti gjendet me të dhe fushat e tjera nuk lexohen fare:

{ "client": { "internal_id": 8812 } }

Ndryshe duhen client.nuis, client.name dhe client.country. country është kod ISO 3166-1 alpha-3, pra ALB, RKS, USA.

doc_type dhe process#

Të dyja janë të detyrueshme; pa to kërkesa refuzohet me 422. process shkon si ProfileID në dokumentin UBL, dhe doc_type si lloji i dokumentit.

Për një shitje të zakonshme dërgoni 380 me P1. Një notë krediti ose një notë debiti korrigjon një faturë tjetër, prandaj dërgon 381 ose 383 me P9, bashkë me original_invoice_iic. Për llojet e tjera të dokumentit ajo fushë nuk pranohet.

Për të kthyer një faturë të plotë mos lëshoni notë krediti. Përdorni endpoint-in e anulimit, i cili e shënon origjinalin si të kthyer.

Lista e plotë e vlerave që pranohen për të dyja fushat është në faqen e endpoint-it.

Nota krediti dhe nota debiti#

Të dyja korrigjojnë një faturë që është regjistruar tashmë, dhe të dyja lëshohen nga i njëjti endpoint si një faturë e zakonshme. Ndryshimi është drejtimi: nota krediti e ul vlerën që blerësi ju detyrohet, nota debiti e rrit.

Të dyja kërkojnë original_invoice_iic, IIC-në që ju ktheu fatura origjinale. Ajo shkon si BillingReference në dokumentin UBL dhe si referencë korrigjimi në regjistrimin te CIS-i, kështu që blerësi dhe CIS-i e dinë saktë cilën faturë po korrigjoni. Pa të kërkesa refuzohet me 422.

Rreshtat që dërgoni janë rreshtat e korrigjimit, jo rreshtat e faturës origjinale. Dërgoni vetëm atë që po korrigjoni, me vlerën e diferencës.

Nota krediti: zbritje pas faturimit#

Fatura 412/2026 doli 12,000 lekë. I zbriten 2,000 lekë sepse shërbimi u ndërpre për një muaj. Lëshoni një notë krediti për diferencën, jo për të gjithë faturën:

curl -X POST 'https://fature.al/api/v1/invoice/e-invoice' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "NK-2026-000037",
    "process": "P9",
    "doc_type": "381",
    "original_invoice_iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
    "payment_method": "TRANSFER",
    "client": {
      "nuis": "L62221018T",
      "name": "Ei3 Software Solution shpk",
      "address": "Rruga e Kavajës 12",
      "city": "Tiranë",
      "country": "ALB"
    },
    "lines": [
      {
        "product_name": "Zbritje për ndërprerje shërbimi",
        "product_code": "ABO-01",
        "unit": "Copë",
        "unit_code": "C62",
        "quantity": 1,
        "price": 2000,
        "total": 2000,
        "vat": 20
      }
    ]
  }'

Vlerat dërgohen pozitive. Është doc_type=381 që e bën dokumentin zbritje, jo shenja e numrave.

Nota debiti: vlerë e nënfaturuar#

E njëjta faturë doli 2,000 lekë më pak sepse një orë pune nuk u llogarit. Një notë debiti e shton diferencën mbi faturën origjinale:

curl -X POST 'https://fature.al/api/v1/invoice/e-invoice' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "ND-2026-000012",
    "process": "P9",
    "doc_type": "383",
    "original_invoice_iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
    "payment_method": "TRANSFER",
    "client": {
      "nuis": "L62221018T",
      "name": "Ei3 Software Solution shpk",
      "address": "Rruga e Kavajës 12",
      "city": "Tiranë",
      "country": "ALB"
    },
    "lines": [
      {
        "product_name": "Orë pune shtesë",
        "product_code": "SRV-02",
        "unit": "Orë",
        "unit_code": "HUR",
        "quantity": 2,
        "price": 1000,
        "total": 2000,
        "vat": 20
      }
    ]
  }'

Përgjigja është e njëjta si e një fature: nota merr id, number, iic, fic dhe eic të vetat. Është një dokument më vete, jo një ndryshim mbi faturën e vjetër, dhe origjinali mbetet i vlefshëm ashtu siç u lëshua.

Cilin të zgjidhni#

Anulimi ndryshon nga të dyja: ai e shënon origjinalin si të kthyer, ndërsa një notë e lë faturën të hapur dhe i qëndron përkrah si dokument korrigjues.

Rreshtat#

Çdo rresht kërkon product_name, product_code, unit, unit_code, quantity, price dhe total.

unit është teksti që lexon njeriu, ndërsa unit_code është kodi që mban dokumenti fiskal. Kodin e jep thirrësi dhe nuk ka vlerë të parazgjedhur. Vlerat më të përdorura janë C62 për copë, MTK për metër katror, LTR për litër dhe KGM për kilogram. E4 është kilogrami bruto dhe DT toni i thatë, prandaj për peshën e zakonshme dërgoni KGM ose TNE.

vat pranon 0, 6, 10 ose 20. Kur një rresht është i përjashtuar nga TVSH-ja, dërgoni vat_exempt_type me një nga TYPE_1, TYPE_2, EXPORT_OF_GOODS ose TAX_FREE.

Monedha dhe kursi#

Kur fatura është në monedhë të huaj, dërgoni currency bashkë me exchange_rate. exchange_rate është sa lekë vlen një njësi e monedhës së faturës. Pa të, ose me një vlerë jo pozitive, merret 1.

Për monedha që vlejnë më pak se një lek, si JPY ose HUF, dërgoni vlerë nën 1. Kursi shkon në drejtimin lek për njësi, jo anasjelltas.

Çfarë ju kthehet#

Përgjigja e suksesshme mban id, number, iic, fic, verifyURL dhe pdf.

eic është i pranishëm vetëm te një e-faturë që e ka marrë tashmë, prandaj trajtojeni si mungesë të çelësit dhe jo si null. Kur ekziston, pdf tregon PDF-in zyrtar të e-faturës, jo tonin.

fic mbetet null derisa fiskalizimi i shtyrë të kryhet vetë. Kjo ndodh kur CIS-i nuk u arrit në çastin e lëshimit: fatura ruhet dhe kërkesa kthen 200 me fic: null. Një 503 është rasti tjetër: fatura nuk u ruajt, riprovoni me të njëjtin internalId.

Shkarkimi i PDF-it me EIC#

curl 'https://fature.al/api/v1/invoice/print-eic/2e9b6f31-d712-4c45-8cc0-9faf24c805a3' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -o fatura.pdf

Kujdes me një EIC që nuk gjendet: përgjigja është teksti Document not found. me status 200 dhe Content-Type: text/html, jo një PDF. Kontrolloni Content-Type para se ta ruani skedarin.

Gabimet që hasen më shpesh#

Formati i gabimit është i njëjtë kudo përveç 422, i cili kthen success: false bashkë me errors të ndarë sipas fushës. Një internalId që mungon kthehet me formatin standard, jo me atë të validimit.