Llojet e faturave

Cdo lloj fature ka endpoint-in e vet, dhe trupi i kerkeses ndryshon me shume nga sa duket. E njejta fature e derguar tek /invoice/cash dhe tek /invoice/e-invoice refuzohet nga i dyti, sepse e-fatura kerkon fusha qe arka nuk i njeh.

Fatura cash#

payment_method eshte i detyrueshem dhe pranon BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY ose ORDER.

Klienti nuk eshte i detyrueshem. Pa client fatura leshohet per klientin e rastit, qe eshte rasti normal i nje arke:

curl -X POST 'https://fature.al/api/v1/invoice/cash' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "ARK-2026-0001",
    "payment_method": "BANKNOTE",
    "lines": [
      { "product_name": "Kafe", "product_code": "KAF-001", "unit": "cope",
        "quantity": 2, "price": 150, "total": 300, "vat": 20 }
    ]
  }'

Sapo dergoni qofte edhe nje fushe te klientit, client.name behet i nevojshem, dhe bashke me te adresa me qytetin, ose ne kerkese ose te ruajtura me pare tek klienti.

Dy kombinime qe lidhen me menyren e pageses#

Dy fusha varen plotesisht nga payment_method, dhe te dyja jane te ndaluara kur menyra nuk perputhet. Kjo eshte gabimi me i shpeshte ne kete endpoint.

COMPANY kerkon company_card. Pa te CIS-i e kthen faturen:

{
  "internalId": "ARK-2026-0002",
  "payment_method": "COMPANY",
  "company_card": "4111-2233",
  "lines": [ ... ]
}

SVOUCHER kerkon vouchers. Numrat jane ne formen numer-vit-NIPT, nuk perseriten brenda te njejtes fature, dhe nuk kalojne 20:

{
  "internalId": "ARK-2026-0003",
  "payment_method": "SVOUCHER",
  "vouchers": ["12-2026-K51501011M", "13-2026-K51501011M"],
  "lines": [ ... ]
}

Dergimi i company_card me BANKNOTE, ose i vouchers me CARD, refuzohet. Nuk ka vend ku ato te shkojne ne dokumentin fiskal, prandaj nuk pranohen ne heshtje.

Fatura jo-cash#

payment_method ketu nuk eshte i detyrueshem, dhe pranon vlera te tjera nga cash-i: ACCOUNT, COMPENSATION, FACTORING, KIND, OTHER, TRANSFER, WAIVER.

client.name duhet, pervec kur dergoni client.internal_id te nje klienti te ruajtur.

Llogaria bankare shkruhet ne fature ne tri menyra, sipas asaj qe keni ne dore:

{ "bank_account": 42 }

{ "bank_account_iban": "AL35202111090000000001234567" }

{
  "bankAccount": {
    "name": "BKT", "iban": "AL35202111090000000001234567",
    "currency": "ALL", "swift": "NCBAALTX", "holder": "Ei3 Software Solution shpk"
  }
}

E para tregon nje llogari qe e keni ne fature.al, e dyta e gjen me IBAN, e treta e shkruan te plote. Forma e trete e ruan llogarine si llogari te kompanise suaj, dhe nje IBAN qe ekziston tashme riperdoret ne vend qe te dyfishohet, keshtu qe mund ta dergoni ne cdo fature pa i mbushur llogarite.

E njejta forme pranohet edhe nga POST /invoice/e-invoice.

Nje tarife shtese shkon vecmas nga rreshtat:

{ "fee": { "fee_type": "PACK", "fee_amount": 50 } }

Note krediti dhe note debiti#

Nje fature jo-cash korrigjohet nga nje fature tjeter jo-cash. Dergoni doc_type bashke me original_invoice_iic, IIC-ne qe ju ktheu fatura origjinale:

{
  "internalId": "NK-2026-000037",
  "doc_type": "381",
  "original_invoice_iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
  "client": { "name": "Alpha SHPK" },
  "lines": [ ... ]
}

381 eshte note krediti dhe ul vleren qe bleresi ju detyrohet, 383 eshte note debiti dhe e rrit. Pa doc_type, ose me 380, fatura eshte e zakonshme. Origjinali duhet te jete fature jo-cash e fiskalizuar, e paanuluar dhe ende e korrigjueshme.

Rreshtat qe dergoni jane rreshtat e korrigjimit, jo ata te fatures origjinale, dhe vlerat shkojne pozitive: drejtimin e percakton doc_type, jo shenja e numrave. Per te kthyer nje fature te plote perdorni endpoint-in e anulimit.

E-fatura#

E-fatura ka rregullat e veta dhe nje faqe te veten: Fatura elektronike. Ndryshimet kryesore nga faturat e mesiperme jane tri: client eshte i detyrueshem me NIPT, cdo rresht kerkon unit_code, dhe doc_type me process duhen gjithmone.

Porosi dhe permbledhese#

Keto te dyja punojne ne cift. Porosia regjistron konsumin qe ka nisur, permbledhesja e mbyll pagesen. Perdoren tipikisht ne bar dhe restorant, ku tavolina hapet dhe paguhet me vone.

Hapi 1, porosia. Mos dergoni payment_method: ai vendoset vete ne ORDER.

curl -X POST 'https://fature.al/api/v1/invoice/order' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "POR-2026-0044",
    "lines": [
      { "product_name": "Birre", "product_code": "BIR-01", "unit": "cope",
        "quantity": 3, "price": 300, "total": 900, "vat": 20 }
    ]
  }'

Ruani iic qe ju kthehet. Ai eshte celesi me te cilin porosia mbyllet.

Hapi 2, permbledhesja. Ketu nuk dergohen rreshta fare: ata merren nga vete porosite. Dergoni IIC-te e tyre, dhe payment_method qe pranon vetem BANKNOTE ose CARD:

curl -X POST 'https://fature.al/api/v1/invoice/summary' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "PRM-2026-0021",
    "payment_method": "CARD",
    "order_invoices": [
      "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
      "A1B2C3D4E5F60718293A4B5C6D7E8F90"
    ]
  }'

Nje permbledhese mbyll disa porosi njeheresh, prandaj nje tavoline me tri porosi te hapura paguhet me nje dokument te vetem. Pergjigja i liston ato tek settledOrderInvoices.

Bllok jo-cash#

POST /invoice/bulk-noncash merr nje varg invoices, ku secili element eshte i njejti trup si nje fature jo-cash e vetme:

{
  "invoices": [
    { "internalId": "AB-001", "client": { "name": "Klient A" }, "lines": [ ... ] },
    { "internalId": "AB-002", "client": { "name": "Klient B" }, "lines": [ ... ] }
  ]
}

Pergjigja eshte nje objekt me celes internalId, dhe statusi mbetet 200 edhe kur ndonje fature brenda deshton. Kontrolloni cdo hyrje me vete.

Zbritjet#

Nje fature zbritet e gjitha, me invoice_discount_type dhe invoice_discount_value, dhe rreshtat mbeten ashtu si i dergoni:

{ "invoice_discount_type": "percent", "invoice_discount_value": 10 }

Vlen per cash, jo-cash, e-fature dhe permbledhese, por jo per porosi.

Nje rresht i vetem zbritet me lines[].discount, perqindje mbi cmimin e njesise, me price te plote dhe total tashme te ulur:

{ "product_name": "Kafe", "product_code": "KAF-001", "unit": "cope",
  "quantity": 2, "price": 150, "discount": 10, "total": 270, "vat": 20 }

Rregullat e plota dhe shembujt me numra jane tek Zbritjet ne fature.

Flete shoqeruese#

Fleta shoqeruese nuk eshte shitje: shoqeron mall qe leviz nga nje pike ne tjetren. Prandaj trupi i saj nuk ngjan me asnje nga te mesipermet, dhe rreshtat quhen invoice_lines, jo lines.

Kerkohen vehPlates, valueOfGoods dhe invoice_lines. Pjesa tjeter ka vlera te parazgjedhura:

curl -X POST 'https://fature.al/api/v1/invoice/wtn' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ' \
  -H 'Content-Type: application/json' \
  -d '{
    "vehPlates": "AA123BB",
    "valueOfGoods": 45000,
    "type": "WTN",
    "transaction": "TRANSFER",
    "vehOwnership": "OWNER",
    "startPoint": "WAREHOUSE",
    "destinPoint": "STORE",
    "startCity": "Tirane",
    "invoice_lines": [
      { "product_name": "Miell", "product_code": "MLL-01", "unit": "kg",
        "quantity": 500, "price": 90, "total": 45000 }
    ]
  }'

Vlerat e lejuara jane te fiksuara: type eshte WTN ose SALE, transaction eshte TRANSFER, EXAMINATION, SALES ose DOOR, vehOwnership eshte OWNER ose THIRDPARTY, ndersa startPoint me destinPoint marrin ANOTHER, CUSTOMS, EXHIBITION, OTHER, SALE, STORE ose WAREHOUSE.

Anulimi i plote dhe i pjesshem#

Pa trup anulohet e gjithe fatura, sido qe te jete lloji i saj:

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

Me lines anulohet vetem nje pjese, dhe kjo eshte e mundur vetem per faturat cash:

{
  "lines": [
    { "product_name": "Kafe", "product_code": "KAF-001", "quantity": 1, "price": 150 }
  ]
}

Cdo rresht duhet te ekzistoje ne faturen origjinale me te njejtin product_code dhe product_name, dhe sasia mund vetem te ulet. Produktet qe nuk i dergoni mbeten te shitura. Kur i njejti produkt eshte faturuar ne dy rreshta me cmime te ndryshme, shtoni price per te zgjedhur rreshtin.

Nje fature qe u leshua me zbritje mbi te gjithe faturen anulohet vetem e plote. Zbritja eshte shperndare mbi te gjitha normat e TVSH-se se dokumentit, keshtu qe anulimi i vetem disa rreshtave do ta prishte TVSH-ne.

Fatura mbetet e hapur per anulime te metejshme derisa ato ta mbulojne te gjithen, dhe vetem atehere shenohet si e anuluar.

Cfare ndryshon mes tyre#

Kjo tabele eshte arsyeja pse nje trup i kopjuar nga nje lloj ne tjetrin refuzohet:

Fusha te perbashketa per te gjitha: internalId, lines me te pakten nje rresht, dhe currency me exchange_rate kur fatura nuk eshte ne leke.

Kur biznesi nuk eshte ne skemen e TVSH-se#

Nje biznes jashte skemes se TVSH-se nuk leshon dot fatura me TVSH, prandaj cdo rresht regjistrohet me vat 0 dhe me perjashtim TAX_FREE, sido qe ta dergoni fushen. Kerkesa nuk refuzohet dhe asgje nuk ju paralajmeron: fatura del pa TVSH.

Kete e vendos konfigurimi i biznesit ne fature.al, jo kerkesa, keshtu qe po ta shihni nje fature pa TVSH aty ku prisnit 20 per qind, kontrolloni skemen e biznesit para se te kontrolloni trupin qe derguat.