Dokumentet që lëshon API-ja

Programet e hotelerisë, të kontabilitetit dhe ERP-të i quajnë dokumentet me emrat e tyre. Kjo faqe i merr ata emra një nga një dhe thotë cili endpoint e lëshon secilin, me një shembull, ose pse API-ja nuk e lëshon.

Të gjithë dokumentet fiskale kthejnë id, number, iic, fic, verifyURL dhe pdf. Ruani iic: me të lëshohen notat e krediti dhe të debitit. Shembujt janë në sandbox, https://demo.fature.al/api/v1. Rregullat e plota të çdo fushe janë te faqja e endpoint-it dhe te Llojet e faturave.

Të gjithë shembujt e kësaj faqeje janë edhe si koleksion Postman, një kërkesë për çdo dokument: document-examples.json. Pas importimit vendosni baseUrl dhe token, dhe zëvendësoni original_invoice_iic dhe id-të e faturave me ato të llogarisë suaj.

Faturë fiskale#

Në Shqipëri çdo faturë e regjistruar te CIS-i është fiskale, prandaj emri "faturë fiskale" në programin tuaj zakonisht do të thotë fatura që paguhet më vonë, me transfertë ose në llogari. Kjo është fatura jo-cash:

curl -X POST https://demo.fature.al/api/v1/invoice/noncash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "FAT-2026-0412",
    "payment_method": "TRANSFER",
    "client": { "name": "Alpha SHPK" },
    "lines": [
      { "product_name": "Qëndrim, dhomë dyshe", "product_code": "DHM-2", "unit": "natë",
        "quantity": 3, "price": 9000, "total": 27000, "vat": 6 }
    ]
  }'

Faturë cash#

Pagesa kryhet në çast, në arkë. Kërkon një pajisje fiskale (TCR) të lidhur me përdoruesin e token-it, dhe payment_method është i detyrueshëm: BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY ose ORDER.

curl -X POST https://demo.fature.al/api/v1/invoice/cash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "ARK-2026-0001",
    "payment_method": "CARD",
    "lines": [
      { "product_name": "Mëngjes", "product_code": "MNG-01", "unit": "copë",
        "quantity": 2, "price": 800, "total": 1600, "vat": 20 }
    ]
  }'

Pa client fatura lëshohet për klientin e rastit.

E-faturë#

E-fatura shkon edhe në platformën e e-faturave, prandaj blerësi duhet të jetë biznes me NIPT dhe me adresë të plotë, çdo rresht kërkon unit_code, dhe doc_type me process janë të detyrueshme. Për një shitje të zakonshme dërgoni 380 me P1:

curl -X POST https://demo.fature.al/api/v1/invoice/e-invoice \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "EF-2026-0098",
    "doc_type": "380",
    "process": "P1",
    "payment_method": "TRANSFER",
    "client": {
      "nuis": "L62221018T",
      "name": "Ei3 Software Solution shpk",
      "address": "Rruga e Kavajës 12",
      "city": "Tiranë",
      "country": "ALB"
    },
    "lines": [
      { "product_name": "Sallë konferencash", "product_code": "SLL-01", "unit": "ditë",
        "unit_code": "DAY", "quantity": 1, "price": 40000, "total": 40000, "vat": 20 }
    ]
  }'

Gjithçka tjetër për e-faturën është te Fatura elektronike.

Parapagim rezervimi#

Një parapagim nuk ka lloj të veçantë fiskal te CIS-i: faturohet si çdo shitje tjetër, për shumën e marrë, në çastin kur merret. Lloji i faturës varet nga mënyra si paguhet.

Paguhet në recepsion, me para në dorë ose me kartë. Faturë cash për shumën e parapaguar:

curl -X POST https://demo.fature.al/api/v1/invoice/cash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "DEP-2026-0031",
    "payment_method": "CARD",
    "notes": "Parapagim për rezervimin R-88213, 12 deri 15 tetor",
    "lines": [
      { "product_name": "Parapagim rezervimi R-88213", "product_code": "DEP-REZ", "unit": "copë",
        "quantity": 1, "price": 10000, "total": 10000, "vat": 6 }
    ]
  }'

Paguhet me transfertë nga një person ose biznes. E njëjta faturë te POST /invoice/noncash, me payment_method TRANSFER dhe me client.

Paguhet nga një biznes që merr e-fatura. E-faturë parapagimi, me doc_type 386 dhe process P4. 386 është kodi UBL i faturës së parapagimit dhe P4 profili i pagesës paraprake, kështu që blerësi e merr dokumentin si parapagim dhe jo si shitje të zakonshme:

curl -X POST https://demo.fature.al/api/v1/invoice/e-invoice \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "DEP-2026-0032",
    "doc_type": "386",
    "process": "P4",
    "payment_method": "TRANSFER",
    "client": {
      "nuis": "L62221018T",
      "name": "Ei3 Software Solution shpk",
      "address": "Rruga e Kavajës 12",
      "city": "Tiranë",
      "country": "ALB"
    },
    "lines": [
      { "product_name": "Parapagim rezervimi R-88214", "product_code": "DEP-REZ", "unit": "copë",
        "unit_code": "C62", "quantity": 1, "price": 30000, "total": 30000, "vat": 6 }
    ]
  }'

Norma e TVSH-së e parapagimit është ajo e shërbimit që parapaguhet: 6 për akomodimin në shembujt më sipër.

Parapagimi dhe fatura përfundimtare#

API-ja nuk i lidh të dyja. Nuk ka fushë që i thotë faturës përfundimtare se një pjesë e saj është paguar tashmë me një parapagim, dhe fature.al nuk e zbret vetë. Fatura përfundimtare lëshohet si faturë më vete, dhe si pasqyrohet parapagimi në të është zgjedhje kontabël e biznesit. Mbani iic-në e parapagimit në programin tuaj, bashkë me numrin e rezervimit, që ta gjeni kur mbyllet qëndrimi.

Parapagim grupi#

Një parapagim grupi faturohet sipas asaj se kush paguan:

Kur paguajnë shumë veta me transfertë, POST /invoice/bulk-noncash i lëshon të gjitha faturat me një kërkesë. Çdo element i invoices është i njëjti body si një faturë jo-cash:

curl -X POST https://demo.fature.al/api/v1/invoice/bulk-noncash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoices": [
      {
        "internalId": "DEP-GRP-0007-01",
        "payment_method": "TRANSFER",
        "client": { "name": "Arben Hoxha" },
        "lines": [
          { "product_name": "Parapagim grupi G-0007", "product_code": "DEP-GRP", "unit": "copë",
            "quantity": 1, "price": 15000, "total": 15000, "vat": 6 }
        ]
      },
      {
        "internalId": "DEP-GRP-0007-02",
        "payment_method": "TRANSFER",
        "client": { "name": "Elira Kola" },
        "lines": [
          { "product_name": "Parapagim grupi G-0007", "product_code": "DEP-GRP", "unit": "copë",
            "quantity": 1, "price": 15000, "total": 15000, "vat": 6 }
        ]
      }
    ]
  }'

Përgjigja ka një hyrje për çdo internalId, dhe kodi mbetet 200 edhe kur ndonjë faturë brenda dështon, prandaj kontrolloni secilën më vete. Pjesëtarët që paguajnë në recepsion marrin secili një faturë cash.

Notë krediti#

Ul vlerën e një fature të lëshuar: zbritje pas faturimit, shërbim i pakryer pjesërisht, mall i dëmtuar. Dërgoni doc_type 381 bashkë me original_invoice_iic, IIC-në e faturës që korrigjoni. Rreshtat janë vetëm diferenca, me vlera pozitive:

curl -X POST https://demo.fature.al/api/v1/invoice/noncash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "NK-2026-0037",
    "doc_type": "381",
    "original_invoice_iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
    "payment_method": "TRANSFER",
    "client": { "name": "Alpha SHPK" },
    "lines": [
      { "product_name": "Zbritje, një natë e pashfrytëzuar", "product_code": "DHM-2", "unit": "natë",
        "quantity": 1, "price": 9000, "total": 9000, "vat": 6 }
    ]
  }'

Nota lëshohet nga i njëjti endpoint si fatura që korrigjon: një faturë jo-cash korrigjohet te /invoice/noncash, një e-faturë te /invoice/e-invoice me process P9. Origjinali duhet të jetë i fiskalizuar, i paanuluar dhe ende i korrigjueshëm. Një faturë cash nuk korrigjohet me notë krediti; ajo anulohet pjesërisht, si në seksionin "Faturë korrigjuese" më poshtë.

Notë debiti#

E kundërta e notës së krediti: rrit vlerën e një fature që doli më pak nga sa duhej. I njëjti body, me doc_type 383:

curl -X POST https://demo.fature.al/api/v1/invoice/noncash \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "ND-2026-0012",
    "doc_type": "383",
    "original_invoice_iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
    "payment_method": "TRANSFER",
    "client": { "name": "Alpha SHPK" },
    "lines": [
      { "product_name": "Minibar, i pafaturuar", "product_code": "MNB-01", "unit": "copë",
        "quantity": 4, "price": 500, "total": 2000, "vat": 20 }
    ]
  }'

Nota është dokument më vete, me iic dhe fic të vetat. Fatura origjinale mbetet e vlefshme ashtu siç u lëshua.

Faturë korrigjuese#

Fatura korrigjuese që kërkon CIS-i, ajo që e kthen një faturë mbrapsht, lëshohet nga endpoint-i i anulimit. Nuk e ndërtoni vetë: fature.al e krijon me numër të ri rendor, e lidh me origjinalin dhe e regjistron te CIS-i. Te një e-faturë del si doc_type 384 me process P10.

Anulim i plotë, për çdo lloj fature. Pa body:

curl -X POST https://demo.fature.al/api/v1/invoice/cancel/40312 \
  -H 'Authorization: Bearer TOKEN_I_JUAJ'

Anulim i pjesshëm, vetëm për faturat cash. Dërgoni rreshtat që kthehen:

curl -X POST https://demo.fature.al/api/v1/invoice/cancel/40313 \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "lines": [
      { "product_name": "Mëngjes", "product_code": "MNG-01", "quantity": 1 }
    ]
  }'

Përgjigja është vetë fatura korrigjuese, me iic dhe fic të vetat. Me numrin tuaj anuloni te POST /invoice/cancel-by-internal-id/{internalId}.

Faturë proformë#

API-ja nuk lëshon proforma. Proforma nuk është dokument fiskal dhe nuk regjistrohet te CIS-i, prandaj nuk ka kode fiskale për t'u kthyer. Mund ta krijoni te paneli i fature.al, si ofertë, ose në programin tuaj. Kur klienti paguan, lëshoni faturën e vërtetë nga endpoint-i që i përket.

Faturë informative#

API-ja nuk lëshon as faturë informative, llogarinë që i tregohet mysafirit para pagesës. Nuk është dokument fiskal, prandaj e printon vetë programi juaj, dhe dokumenti fiskal lëshohet kur mbyllet pagesa.

Mos e zëvendësoni me POST /invoice/order. Fatura porosi regjistrohet te CIS-i si dokument fiskal dhe duhet mbyllur më pas me një faturë përmbledhëse; ajo shërben për tavolinën e restorantit, jo si llogari informative.