Llojet e faturave

Çdo lloj fature ka endpoint-in e vet, dhe body i kërkesës ndryshon më shumë nga sa duket. E njëjta faturë e dërguar te /invoice/cash dhe te /invoice/e-invoice refuzohet nga i dyti, sepse e-fatura kërkon fusha që fatura cash nuk i njeh. Kuptimi i dokumenteve dhe i kodeve që kthehen është te Konceptet bazë.

Çdo lëshim kthen id, number, iic, fic, verifyURL dhe pdf. Shembujt janë në sandbox, https://demo.fature.al/api/v1.

Fatura cash#

Kërkon një pajisje fiskale (TCR) të lidhur me përdoruesin e token-it. payment_method është i detyrueshëm dhe pranon BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY ose ORDER. Çdo rresht kërkon vat (0, 6, 10 ose 20).

Klienti nuk është i detyrueshëm. Pa client fatura lëshohet për klientin e rastit, që është rasti normal i një arke:

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": "BANKNOTE",
    "lines": [
      { "product_name": "Kafe", "product_code": "KAF-001", "unit": "copë",
        "quantity": 2, "price": 150, "total": 300, "vat": 20 }
    ]
  }'

Sapo dërgoni qoftë edhe një fushë të klientit, client.name bëhet i detyrueshëm, dhe bashkë me të adresa me qytetin, ose në kërkesë ose të ruajtura më parë te klienti në fature.al. Rregullat e plota të objektit client janë te faqja e endpoint-it.

Dy fusha që varen nga mënyra e pagesës#

company_card dhe vouchers varen plotësisht nga payment_method, dhe të dyja refuzohen kur mënyra nuk përputhet.

COMPANY kërkon company_card:

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

SVOUCHER kërkon vouchers. Numrat janë në formën numër-vit-NIPT, nuk përsëriten brenda të njëjtës faturë, dhe nuk kalojnë 20:

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

Dërgimi i company_card me BANKNOTE, ose i vouchers me CARD, refuzohet me 422.

Fatura jo-cash#

payment_method nuk është i detyrueshëm dhe pranon vlera të tjera nga fatura cash: ACCOUNT, COMPENSATION, FACTORING, KIND, OTHER, TRANSFER, WAIVER.

client.name duhet, përveç kur dërgoni client.internal_id të një klienti të ruajtur.

Llogaria bankare shkruhet në faturë në tri mënyra, sipas asaj që keni në dorë:

{ "bank_account": 42 }

{ "bank_account_iban": "AL35202111090000000001234567" }

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

E para tregon një llogari që e keni në fature.al, e dyta e gjen me IBAN, e treta e shkruan të plotë. Forma e tretë e ruan llogarinë si llogari të kompanisë suaj; një IBAN që ekziston tashmë ripërdoret në vend që të dyfishohet. E njëjta formë pranohet edhe nga POST /invoice/e-invoice.

Një tarifë shtesë shkon veçmas nga rreshtat:

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

Notë krediti dhe notë debiti#

Një faturë jo-cash korrigjohet nga një faturë tjetër jo-cash. Dërgoni doc_type bashkë me original_invoice_iic, IIC-në që ju ktheu fatura origjinale:

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

381 është notë krediti dhe ul vlerën që blerësi ju detyrohet, 383 është notë debiti dhe e rrit. Pa doc_type, ose me 380, fatura është e zakonshme. Origjinali duhet të jetë faturë jo-cash e fiskalizuar, e paanuluar dhe ende e korrigjueshme.

Rreshtat që dërgoni janë rreshtat e korrigjimit, jo ata të faturës origjinale, dhe vlerat shkojnë pozitive: drejtimin e përcakton doc_type, jo shenja e numrave. Për të kthyer një faturë të plotë përdorni endpoint-in e anulimit.

E-fatura#

E-fatura ka faqen e vet: Fatura elektronike. Ndryshimet kryesore nga faturat e mësipërme janë tri: client është i detyrueshëm me NIPT (client.nuis), çdo rresht kërkon unit_code, dhe doc_type me process duhen gjithmonë.

Porosi dhe përmbledhëse#

Këto të dyja punojnë në çift. Porosia regjistron konsumin që ka nisur, përmbledhësja e mbyll me pagesën. Përdoren në bar dhe restorant, ku tavolina hapet dhe paguhet më vonë. Të dyja lëshohen nga një TCR, si fatura cash.

Hapi 1, porosia. Mos dërgoni payment_method: ai vendoset vetë në ORDER. Çdo rresht kërkon vat.

curl -X POST https://demo.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": "Birrë", "product_code": "BIR-01", "unit": "copë",
        "quantity": 3, "price": 300, "total": 900, "vat": 20 }
    ]
  }'

Ruani iic që ju kthehet. Ai është çelësi me të cilin porosia mbyllet.

Hapi 2, përmbledhësja. Këtu nuk dërgohen rreshta: ata merren nga vetë porositë. Dërgoni IIC-të e tyre te order_invoices, dhe payment_method që pranon vetëm BANKNOTE ose CARD:

curl -X POST https://demo.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"
    ]
  }'

Një përmbledhëse mbyll disa porosi njëherësh, prandaj një tavolinë me tri porosi të hapura paguhet me një dokument të vetëm. Përgjigja i liston ato te settledOrderInvoices.

Bulk jo-cash#

POST /invoice/bulk-noncash merr një array invoices, ku secili element është i njëjti body si një faturë jo-cash e vetme:

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

Përgjigja është një object me çelës internalId, dhe kodi mbetet 200 edhe kur ndonjë faturë brenda dështon. Kontrolloni çdo hyrje më vete. Buxheti i kërkesave numëron kërkesa, jo fatura (shihni Kufiri i kërkesave).

Zbritjet#

Një faturë zbritet e gjitha, me invoice_discount_type dhe invoice_discount_value, dhe rreshtat mbeten ashtu siç i dërgoni:

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

Vlen për cash, jo-cash, e-faturë dhe përmbledhëse, por jo për porosi.

Një rresht i vetëm zbritet me lines[].discount, përqindje mbi çmimin e njësisë, me price të plotë dhe total tashmë të ulur:

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

Rregullat e plota dhe shembujt me numra janë te Zbritjet në faturë.

Fletë shoqëruese (WTN)#

Fleta shoqëruese nuk është shitje: shoqëron mall që lëviz nga një pikë në tjetrën. Body i saj nuk ngjan me asnjë nga të mësipërmet, dhe rreshtat quhen invoice_lines, jo lines.

Kërkohen vehPlates, valueOfGoods dhe invoice_lines. Pjesa tjetër ka vlera të parazgjedhura:

curl -X POST https://demo.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": "Tiranë",
    "invoice_lines": [
      { "product_name": "Miell", "product_code": "MLL-01", "unit": "kg",
        "quantity": 500, "price": 90, "total": 45000 }
    ]
  }'

Vlerat e lejuara janë të fiksuara: type është WTN ose SALE, transaction është TRANSFER, EXAMINATION, SALES ose DOOR, vehOwnership është OWNER ose THIRDPARTY, ndërsa startPoint dhe destinPoint marrin ANOTHER, CUSTOMS, EXHIBITION, OTHER, SALE, STORE ose WAREHOUSE.

POST /invoice/wtn dhe GET /invoice/wtn pranojnë një kërkesë në proces njëkohësisht për token: sa kohë një thirrje nuk ka mbaruar, e dyta refuzohet me 429.

Anulimi i plotë dhe i pjesshëm#

Pa body anulohet e gjithë fatura, sido që të jetë lloji i saj:

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

Me lines anulohet vetëm një pjesë, dhe kjo është e mundur vetëm për faturat cash:

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

Çdo rresht duhet të ekzistojë në faturën origjinale me të njëjtin product_code dhe product_name, dhe sasia mund vetëm të ulet. Produktet që nuk i dërgoni mbeten të shitura. Kur i njëjti produkt është faturuar në dy rreshta me çmime të ndryshme, shtoni price për të zgjedhur rreshtin.

Një faturë që u lëshua me zbritje mbi të gjithë faturën anulohet vetëm e plotë. Zbritja është shpërndarë mbi të gjitha normat e TVSH-së së dokumentit, kështu që anulimi i vetëm disa rreshtave do ta prishte TVSH-në.

Fatura mbetet e hapur për anulime të mëtejshme derisa ato ta mbulojnë të gjithën, dhe vetëm atëherë shënohet si e anuluar. Anulimi bëhet edhe me numrin tuaj: POST /invoice/cancel-by-internal-id/{internalId}.

Çfarë ndryshon mes tyre#

Kjo tabelë është arsyeja pse një body i kopjuar nga një lloj në tjetrin refuzohet:

Te faturat cash dhe jo-cash NIPT-i i blerësit shkon te client.id me type NUIS; te e-fatura shkon te client.nuis.

Fusha të përbashkëta për të gjitha: internalId, lines me të paktën një rresht, dhe currency me exchange_rate kur fatura nuk është në lekë.

Kur biznesi nuk është në skemën e TVSH-së#

Një biznes jashtë skemës së TVSH-së nuk lëshon dot fatura me TVSH, prandaj çdo rresht regjistrohet me vat 0 dhe me përjashtim TAX_FREE, sido që ta dërgoni fushën. Kërkesa nuk refuzohet dhe asgjë nuk ju paralajmëron: fatura del pa TVSH.

Këtë e vendos konfigurimi i biznesit në fature.al, jo kërkesa. Nëse shihni një faturë pa TVSH aty ku prisnit 20 për qind, kontrolloni skemën e biznesit para se të kontrolloni body-n që dërguat.