_Version: 1.0_

> This document is the LLM-friendly export of the API. It is regenerated on every request from the live OpenAPI spec. Use it as context when asking an AI assistant for help.

# fature.al API

fature.al është platforma e faturimit dhe e fiskalizimit për bizneset në Shqipëri. Me këtë API sistemi
juaj lëshon fatura të fiskalizuara pa u marrë vetë me certifikata, nënshkrim XML dhe SOAP: dërgoni
faturën si JSON dhe merrni mbrapsht dokumentin e regjistruar te administrata tatimore, me kodet
fiskale, URL-në e verifikimit dhe PDF-në.

## Për kë është

- **Programe kontabiliteti dhe ERP**, që e lëshojnë faturën aty ku bëhet shitja.
- **Dyqane online**, që e kthejnë porosinë e paguar në faturë në të njëjtin çast.
- **Programe arke, bari dhe restoranti**, me porosi që hapen dhe mbyllen me një pagesë.
- **Ofrues software-i**, që e instalojnë të njëjtin program te shumë biznese, secili me identitetin e
  vet fiskal.

## Çfarë ju duhet para thirrjes së parë

| Ju duhet | Ku e merrni |
| --- | --- |
| Një llogari në fature.al, me abonim që përfshin modulet që do të përdorni | `fature.al`, ose `demo.fature.al` për sandbox |
| Një **API token** | Në panelin e fature.al, te **Konfigurime > API Tokens**. Token-i është i përdoruesit, jo i kompanisë |
| **Client id** dhe **client secret** të aplikacionit, nëse jeni ofrues software-i | Nga fature.al, kur regjistrohet integrimi juaj. Shihni "Identifikoni aplikacionin tuaj" |
| Certifikata elektronike e biznesit, e ngarkuar në fature.al | Biznesi e merr nga e-Albania dhe e ngarkon një herë në panel |
| Për fatura cash: një pajisje fiskale (TCR) e lidhur me përdoruesin e token-it | Konfigurohet nga biznesi në panel, ose nga ju me endpoint-et e regjistrimit |

Thirrja e parë e dobishme është `GET /account`: ju thotë me cilin biznes, njësi biznesi dhe pajisje
fiskale po punoni.

## Konceptet bazë

### Fiskalizimi, në pak rreshta

Në Shqipëri çdo faturë raportohet në kohë reale te administrata tatimore, në sistemin qendror të
fiskalizimit (**CIS**). Sistemi e regjistron faturën dhe kthen kodet e saj, të cilat shfaqen në
dokumentin që merr blerësi bashkë me një kod QR që hap faqen e verifikimit. Kur CIS-i nuk arrihet,
fatura lëshohet gjithsesi, ruhet dhe fiskalizohet automatikisht sapo shërbimi kthehet. Faturat drejt
bizneseve mund të shkojnë edhe në platformën qendrore të e-faturave, e cila ia dorëzon blerësit
dokumentin elektronik.

fature.al i bën të gjitha këto: nënshkruan me certifikatën e biznesit, komunikon me CIS-in dhe me
platformën e e-faturave, mban numërimin, ruan dokumentin dhe e riprovon fiskalizimin kur shërbimi nuk
përgjigjet.

### Kush lëshon faturën

| Subjekti | Çfarë është | Ku del në API |
| --- | --- | --- |
| **Kompania** | Biznesi që lëshon faturat, i identifikuar me **NIPT** (i njëjti kod quhet edhe **NUIS**) | Token-i i përket një përdoruesi të saj |
| **Njësia e biznesit** | Vendi ku ushtrohet veprimtaria: dyqani, zyra, magazina. Ka një kod të marrë nga tatimet, `businessUnitCode` | `businessCode` në përgjigje |
| **Operatori** | Personi që lëshon faturën, me kodin e operatorit të marrë nga tatimet | `operatorCode` në përgjigje |
| **Pajisja fiskale (TCR)** | Arka e regjistruar te tatimet, me kodin e saj TCR. Vetëm faturat cash lëshohen nga një TCR | `tcrCode` në përgjigje |
| **Certifikata** | Certifikata elektronike e biznesit, me të cilën nënshkruhet çdo kërkesë drejt tatimeve | Ngarkohet një herë; nuk dërgohet në kërkesa |

Token-i i përdoruesit i mban të gjitha: prej tij zgjidhen kompania, njësia, operatori dhe TCR-ja.
Ju nuk i dërgoni në asnjë kërkesë faturimi.

### Llojet e dokumenteve

| Dokumenti | Endpoint-i | Kur përdoret |
| --- | --- | --- |
| **Faturë cash** | `POST /invoice/cash` | Pagesa kryhet në çast, në arkë: para në dorë, kartë, kartë kompanie, tollona |
| **Faturë jo-cash** | `POST /invoice/noncash` | Pagesa vjen më vonë, me transfertë ose në llogari |
| **E-faturë** | `POST /invoice/e-invoice` | Blerësi është biznes dhe fatura i dorëzohet nëpërmjet platformës së e-faturave |
| **Faturë porosi** | `POST /invoice/order` | Konsumi ka nisur, pagesa jo: tavolina në restorant |
| **Faturë përmbledhëse** | `POST /invoice/summary` | Mbyll një ose më shumë porosi me një pagesë |
| **Bulk jo-cash** | `POST /invoice/bulk-noncash` | Shumë fatura jo-cash me një kërkesë, për faturim periodik |
| **Fletë shoqëruese (WTN)** | `POST /invoice/wtn` | Mall që lëviz pa u shitur; e kërkuar nga ligji |

Body i kërkesës ndryshon nga një lloj te tjetri më shumë nga sa duket: e njëjta faturë e dërguar te
dy endpoint-e refuzohet nga njëri prej tyre. Çdo endpoint i thotë rregullat e veta.

### Korrigjimet, parapagimet dhe dokumentet jo-fiskale

| Dokumenti | Si lëshohet |
| --- | --- |
| **Notë krediti** | `doc_type` `381` me `original_invoice_iic`, te `POST /invoice/noncash` ose `POST /invoice/e-invoice` |
| **Notë debiti** | `doc_type` `383` me `original_invoice_iic`, te të njëjtat endpoint-e |
| **Faturë korrigjuese** | `POST /invoice/cancel/{id}`: anulim i plotë për çdo faturë, i pjesshëm vetëm për faturat cash |
| **Parapagim**, edhe për një rezervim ose një grup | Faturë cash ose jo-cash për shumën e marrë, ose e-faturë me `doc_type` `386` dhe `process` `P4` |
| **Proformë, faturë informative** | Nuk lëshohen nga API-ja: nuk janë dokumente fiskale dhe nuk regjistrohen te CIS-i |

Një parapagim nuk ka lloj të veçantë te CIS-i dhe API-ja nuk e lidh me faturën përfundimtare: nuk
ka fushë që e zbret atë nga fatura që lëshohet kur mbyllet shërbimi.

Faturat cash, jo-cash dhe e-faturat, bashkë me çdo dokument të kësaj tabele, kanë një shembull të
gatshëm te koleksioni Postman [document-examples.json](/docs/api/postman/document-examples.json).

### Çfarë ktheni pas dhe çfarë të ruani

Çdo lëshim kthen të njëjtët identifikues:

| Fusha | Çfarë është | Ruajeni? |
| --- | --- | --- |
| `id` | Id-ja e faturës në fature.al | Po, ose punoni me `internalId` tuaj |
| `number` | Numri i faturës, si `12/2026` | Po; shfaqet te blerësi |
| `iic` | Kodi identifikues i faturës, i llogaritur nga nënshkrimi. Në ligj quhet **NSLF** | Po; është çelësi për notat e korrigjimit dhe për përmbledhëset |
| `fic` | Kodi që kthen CIS-i kur e regjistron faturën. Në ligj quhet **NIVF**. `null` sa kohë fatura pret fiskalizimin | Po |
| `eic` | Kodi i faturës në platformën e e-faturave. Vetëm te e-faturat | Po, te e-faturat |
| `verifyURL` | Faqja e verifikimit te tatimet, ajo që hap kodi QR | Po, nëse printoni vetë |
| `pdf` | URL-ja e dokumentit të gatshëm | Sipas nevojës |

`internalId` është numri i faturës në sistemin tuaj. Ju e dërgoni në çdo lëshim, dhe me të mund ta
gjeni dhe ta anuloni faturën pa mbajtur `id`-në tonë.

### Fjalorth

| Termi | Kuptimi |
| --- | --- |
| **NIPT / NUIS** | Numri i identifikimit të tatimpaguesit, si `L62221018T`. Dy emra për të njëjtin kod |
| **CIS** | Sistemi qendror i fiskalizimit i administratës tatimore, ku regjistrohet çdo faturë |
| **IIC / NSLF** | Kodi identifikues i faturës, 32 karaktere hexadecimal. I njëjti kod me dy emra |
| **FIC / NIVF** | Kodi që kthen CIS-i kur regjistron faturën, një UUID. I njëjti kod me dy emra |
| **EIC** | Kodi i e-faturës në platformën qendrore të e-faturave |
| **TCR** | Pajisja fiskale (arka) e regjistruar te tatimet, dhe kodi i saj |
| **Njësia e biznesit** | Vendi i ushtrimit të veprimtarisë; ka kodin `businessUnitCode` |
| **Kodi i operatorit** | Kodi i personit që lëshon faturën, i marrë nga tatimet |
| **Self-care** | Portali i administratës tatimore ku biznesi merr kodin e njësisë dhe të operatorit |
| **e-Albania** | Portali shtetëror nga i cili biznesi merr certifikatën elektronike |
| **Arka fiskale** | Dita e punës në një TCR: hapja e balancës, hyrjet dhe daljet e parave, mbyllja |
| **Klienti i rastit** | Blerësi anonim i një shitjeje me pakicë. Fatura cash pa `client` lëshohet për të |
| **Vetëfaturim** | Faturë që e lëshon blerësi në emër të shitësit (`self_issue_type`) |
| **Notë krediti, notë debiti** | Dokument që korrigjon një faturë të lëshuar, duke ulur ose rritur vlerën (`doc_type` `381` ose `383`) |
| **Fletë shoqëruese (WTN)** | Dokumenti që shoqëron mallin në lëvizje kur nuk ka shitje |
| **UBL** | Formati XML i e-faturës; `process` dhe `doc_type` janë fusha të tij |

## Fillimi i shpejtë

Tri thirrje ju çojnë nga token-i te fatura e parë e fiskalizuar. Punoni në sandbox,
`https://demo.fature.al/api/v1`, ku faturat nuk kanë vlerë fiskale.

**1. Provoni token-in.** `GET /ping` nuk prek asgjë:

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

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

Një `401` do të thotë që token-i nuk po arrin: kontrolloni që header-i quhet `Authorization` dhe që
fjala `Bearer` është para tij.

**2. Shihni me kë po punoni.** `GET /account` kthen përdoruesin, kompaninë, njësinë e biznesit dhe
kodin e pajisjes fiskale, pra konfirmon që token-i i përket biznesit të duhur.

**3. Lëshoni faturën e parë.** Një faturë jo-cash është fillimi më i thjeshtë, sepse nuk kërkon
pajisje fiskale:

```bash
curl -X POST https://demo.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 Kavajës 12", "city": "Tiranë"},
    "lines": [
      {"product_name": "Shërbim", "product_code": "SRV-01", "unit": "copë", "unit_code": "C62",
       "quantity": 1, "price": 1000, "total": 1000, "vat": 20}
    ]
  }'
```

```json
{
  "status": true,
  "data": {
    "invoice": {
      "id": 40312,
      "number": "1/2026",
      "iic": "8FE72E2ACD1C500A83F8C89B4E2E3E1D",
      "fic": "b3f1c0a2-4d5e-4f60-9a71-2c3d4e5f6071",
      "tcrCode": null,
      "businessCode": "bb123bb123",
      "operatorCode": "aa123aa123",
      "fiscalizedAt": "2026-09-13 10:42:07",
      "verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?iic=...",
      "pdf": "https://demo.fature.al/api/v1/invoice/print/40312"
    }
  }
}
```

Fatura del menjëherë edhe në panelin e fature.al. Ruani `id`, `number`, `iic` dhe `fic` pranë
shitjes tuaj.

## Identifikimi

Çdo kërkesë ka dy nivele identifikimi: **kush** e bën (përdoruesi, me bearer token) dhe **cili
software** e bën (aplikacioni juaj, me client id dhe client secret).

```
Authorization: Bearer {api_token}
X-Client-Id: ft_id_...
X-Client-Secret: ft_sk_...
```

Token-in e gjeneroni nga **Konfigurime > API Tokens** në panelin e fature.al, ose e merrni nga
përgjigja e `POST /register`. Ai i përket biznesit që e përdor software-in tuaj dhe ndryshon nga njëri
biznes te tjetri.

Client id dhe client secret i përkasin **aplikacionit tuaj**, jo biznesit: janë të njëjtat për të
gjithë bizneset që përdorin software-in tuaj. Një integrim i shkruar për një biznes të vetëm punon
vetëm me token-in. Shihni "Identifikoni aplikacionin tuaj" më poshtë.

Token-i jep akses të plotë në llogari. Ruajeni në server, jo në kodin e shfletuesit apo në
aplikacione publike, mos e vendosni në kontrollin e versioneve, dhe rigjenerojeni menjëherë nëse
dyshoni se ka rrjedhur.

## Serverat dhe versionet

Çdo rrugë në këtë dokument është relative ndaj adresave më poshtë: `/invoice/cash` do të thotë
`https://fature.al/api/v1/invoice/cash`.

| Mjedisi | URL |
| --- | --- |
| **Live** | `https://fature.al/api/v1` |
| **Sandbox** | `https://demo.fature.al/api/v1` |

Ndërtoni gjithmonë kundrejt sandbox-it dhe kaloni në live duke ndryshuar vetëm adresën bazë.
Kërkesat dhe përgjigjet janë të njëjta në të dy mjediset.

Versioni është pjesë e rrugës. `v1` mban të gjithë API-në dhe është versioni mbi të cilin ndërtohet.
`v2` ekziston vetëm për faturat dhe klientët, me pagesën si listë dhe klientin si objekte të ndara,
dhe përdoret krahas `v1`, jo në vend të tij. Asnjë version nuk është në dalje. Brenda një versioni
ndryshimet janë vetëm shtesa: një fushë ekzistuese nuk ndryshon kuptim dhe nuk hiqet.

| Dokumenti | Çfarë mbulon | Adresa |
| --- | --- | --- |
| **v1** (ky dokument) | E gjithë API-ja e faturimit dhe e regjistrimit | [`/docs/api`](/docs/api) |
| **v2** | Faturat me pagesë të ndarë dhe klientët në formatin e ri | [`/docs/api/v2`](/docs/api/v2) |
| **Partner** | Porositë e Wolt për një njësi të vetme | [`/docs/api/partner`](/docs/api/partner) |

Secili dokument botohet edhe si OpenAPI JSON (`/docs/api.json`) dhe si Markdown për asistentët AI
(`/docs/api.md`).

## Si lexohet një përgjigje

Çdo përgjigje është JSON. Lexojeni në këtë radhë:

1. **Kodi HTTP.**
2. **Në `200`, fusha `status`.** `true`: rezultati është te `data`. `false`: veprimi u refuzua,
   arsyeja është te `message` dhe, kur ka detaje, te `errors`.
3. **Në `422`, fusha `success`.** Është përgjigja e validimit dhe e vetmja që përdor `success` në
   vend të `status`. Aty `errors` është objekt sipas fushës, me emrin e plotë të fushës, si
   `lines.0.quantity` ose `client.id.type`.
4. **Në çdo kod tjetër**, `status: false` me `message` dhe `errors` (listë). Përjashtim bëjnë `429`
   nga kufiri i përgjithshëm dhe nga anulimet, që kthejnë vetëm `message`.

```json
{"status": true, "data": {"...": "..."}}
```

```json
{"status": false, "message": "Përshkrimi i gabimit", "errors": ["Mesazhi për përdoruesin"]}
```

```json
{"success": false, "message": "Te dhenat jo te sakta.", "errors": {"lines.0.quantity": ["..."]}}
```

### Kodet HTTP

| Kodi | Kuptimi | Çfarë të bëni |
| --- | --- | --- |
| `200` me `status: false` | Kërkesa u kuptua, por veprimi u refuzua: përdorues pa pajisje fiskale, arkë pa fonde, NIPT i regjistruar tashmë, refuzim nga CIS-i | Lexoni `message`. Mos e riprovoni pa ndryshuar gjë |
| `400` | Të dhëna të paplota për fiskalizim, zakonisht adresa ose qyteti i blerësit, ose një `total` që nuk përputhet | `errors` thotë saktë çfarë mungon. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId` |
| `401` me `{"message": "Unauthenticated."}` | Token-i mungon, është i gabuar ose i revokuar | Kontrolloni header-in `Authorization` |
| `401` me `status: false` | Moduli nuk është në abonimin e biznesit: faturat, arka, fletët shoqëruese ose faturat e blerjes | Rigjenerimi i token-it nuk ndihmon; abonimi duhet zgjeruar |
| `403` | Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari | |
| `404` | Burimi nuk ekziston, ose nuk i përket kompanisë suaj | |
| `409` | Një kërkesë me këtë `internalId` është ende në proces | Prisni pak; lexojeni me `POST /invoice/details/{internalId}` |
| `422` | Validimi dështoi | Rregulloni të dhënat. Mos e riprovoni të njëjtën kërkesë |
| `429` | Kufiri i kërkesave u arrit | Prisni sa thotë `Retry-After`, ose një sekondë kur mungon |
| `500` | Gabim i papritur | Riprovoni më vonë me të njëjtin `internalId` |
| `502` | Shërbimi i fiskalizimit u përgjigj me gabim (faturat e blerjes) | Riprovoni më vonë |
| `503` | Shërbimi i fiskalizimit nuk u arrit dhe fatura **nuk u ruajt** | Riprovoni me të njëjtin `internalId` |

## internalId dhe idempotenca

`internalId` (string, i detyrueshëm në çdo lëshim) është identifikuesi i faturës në sistemin tuaj:
numri juaj i faturës ose një UUID. Duhet të jetë unik brenda kompanisë suaj për vitin kalendarik.

- **Nuk krijon dublikata.** Kur dërgoni një `internalId` që ekziston tashmë për këtë vit, serveri nuk
  lëshon faturë të dytë: kthen faturën ekzistuese me `200`, dhe nëse ajo priste fiskalizimin,
  përpiqet ta përfundojë para se ta kthejë.
- **Prandaj riprovimi është i sigurt.** Një timeout ose ndërprerje gjatë lëshimit nuk do të thotë që
  fatura dështoi; mund të jetë ruajtur. Riprovoni me **të njëjtin** `internalId`, kurrë me një të ri.
- **`409` do të thotë "ende në proces".** Nëse riprovoni ndërsa kërkesa e parë nuk ka mbaruar (deri
  në rreth 5 minuta), merrni `409`. Prisni pak dhe riprovoni, ose lexoni gjendjen me
  `POST /invoice/details/{internalId}`.
- fature.al nuk e kthen `internalId` në përgjigjen e lëshimit; ruani vetë lidhjen mes tij dhe `id`,
  `number` dhe `iic`.

## Blerësi në faturë

Objekti `client` ka tri rrjedha:

| Rasti | Çfarë dërgoni | Rezultati |
| --- | --- | --- |
| **Klient i rastit** | `client` mungon, ose është `null` | Fatura lëshohet për klientin e rastit të kompanisë. Vetëm te faturat cash: një faturë jo-cash pa `client` refuzohet me `422` |
| **Klient i ruajtur në fature.al** | Vetëm `client.internal_id` | Klienti merret siç është ruajtur; fushat e tjera nuk lexohen |
| **Klient nga sistemi juaj** | `client.name` dhe të dhënat e tjera | Klienti kërkohet me emër dhe identifikues. Nëse nuk ekziston, krijohet |

Në rrjedhën e tretë:

- `client.name` bëhet i detyrueshëm sapo dërgoni çfarëdo të dhëne tjetër të klientit.
- `client.address` dhe `client.city` duhen për çdo klient të emëruar, sepse shkojnë te CIS-i, i cili
  nuk pranon faturë pa to. Mjafton të jenë të ruajtura te klienti në fature.al; nuk është nevoja të
  dërgohen në çdo faturë. Nëse dërgoni vetëm `client.address`, qyteti i ruajtur nuk fshihet.
- `client.country` është kod ISO 3166-1 alpha-3, si `ALB`, `RKS` ose `ITA`. Pa të merret `ALB`.
- `client.id` identifikon blerësin: `{"type": "NUIS", "id": "L62221018T"}` për bizneset shqiptare,
  `VAT` ose `TAX` për bizneset e huaja, `ID`, `PASS` ose `SOC` për personat. NIPT-i nuk verifikohet
  te tatimet gjatë lëshimit; për ta verifikuar më parë përdorni `GET /client/search`.

Kur mungon një e dhënë e nevojshme, kërkesa refuzohet me `400` dhe `errors` thotë saktë çfarë duhet
plotësuar, p.sh. `Klientit "Kompani Provë SHPK" i mungon qyteti.` Fatura dhe klienti nuk ruhen;
riprovoni me të njëjtin `internalId` pasi t'i plotësoni.

## Fiskalizimi kur tatimet nuk përgjigjen

Kur CIS-i nuk arrihet, fatura ruhet dhe lëshohet gjithsesi: përgjigja vjen me `200`, `status: true`
dhe `fic: null`. fature.al e riprovon fiskalizimin vetë çdo 15 minuta dhe e plotëson `fic` sapo CIS-i
kthehet. Mos e trajtoni si gabim dhe mos e lëshoni përsëri; lexojeni më vonë me
`POST /invoice/details/{internalId}`.

Një `503` është rasti tjetër: fatura **nuk u ruajt**. Riprovoni me të njëjtin `internalId`.

## Kufijtë e kërkesave (rate limit)

Kufijtë numërohen për token. Kur kaloni një kufi, përgjigja është `429 Too Many Requests`.

### Kufijtë që kthejnë 429 sot

| Kufiri | Vlera | Body i përgjigjes |
| --- | --- | --- |
| I përgjithshëm, çdo endpoint | 300 kërkesa në minutë për token; 120 në minutë për IP pa token | `{"message": "Too Many Attempts."}` me header-at `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` |
| Anulimet, `POST /invoice/cancel/*` | 30 në minutë dhe 600 në orë | I njëjti |
| Një kërkesë në proces njëkohësisht (shih më poshtë) | Te lëshimi i faturave pritje deri në 1 sekondë; te klientët, produktet, llogaritë bankare dhe fletët shoqëruese refuzim i menjëhershëm | `{"status": false, "errors": ["..."]}`, pa `Retry-After` |
| E njëjta radhë, por me `200` | `GET /products`, `GET /product/categories` | `200` me `status: false`. Lexoni `status`, jo vetëm kodin |

### Buxheti për grup endpoint-esh

Këto janë vlerat me të cilat është dimensionuar API-ja. Sot një pjesë e tyre vetëm regjistrohen kur
kalohen, pa u refuzuar; ndërtoni brenda tyre dhe trajtoni `429`, sepse zbatohen pa njoftim.

| Grupi | Buxheti | Endpoint-et |
| --- | --- | --- |
| I zakonshëm | 240 në minutë | Çdo endpoint jashtë grupeve më poshtë |
| Lëshim faturash | 300 në minutë (5 në sekondë) | `POST /invoice/cash`, `/invoice/noncash`, `/invoice/e-invoice`, `/invoice/order`, `/invoice/summary`, `/invoice/wtn` |
| Fiskal | 30 në minutë, 600 në orë | `POST /invoice/cancel/*`, `GET /purchase-invoices` |
| Bulk | 3 në minutë, 30 në orë | `POST /invoice/bulk-noncash` |
| Printim | 30 në minutë | `GET /invoice/print/{id}`, `/invoice/print-eic/{eic}`, `/invoice/wtn/print/{id}` |
| Raporte | 30 në minutë | `GET /reports/*`, `GET /dashboard/summary` |
| Kërkim | 90 në minutë | `GET /client/search` |
| Regjistrim | 30 në minutë, 600 në orë | `POST /register`, `POST /on-boarding/*` |

### Një kërkesë në proces njëkohësisht

Lëshimi i faturave serializohet, sepse numri rendor është MAX+1 për biznes dhe vit, dhe për cash edhe
për TCR. Një kërkesë e dytë drejt të njëjtit endpoint pret deri në 1 sekondë që e para të mbarojë;
nëse nuk arrin, refuzohet me `429`.

Klientët, produktet, llogaritë bankare dhe fletët shoqëruese mbajnë të njëjtin rregull pa pritje:
sa kohë një kërkesë e token-it tuaj drejt atij endpoint-i nuk ka mbaruar, e dyta refuzohet
menjëherë. Thirrjet njëra pas tjetrës nuk kanë kufi tjetër përveç buxhetit.

| Endpoint-et | Radha |
| --- | --- |
| `POST /invoice/cash`, `/invoice/order`, `/invoice/summary` | Për biznes dhe TCR, me pritje |
| `POST /invoice/noncash`, `/invoice/e-invoice`, `/invoice/bulk-noncash` | Për biznes, me pritje |
| `POST /invoice/cancel/*` | Radha e tipit të faturës që anulohet, me pritje |
| `GET /invoice`, `GET /invoice/{id}/details` | Për token, me pritje |
| `GET`, `POST`, `PUT` te `/clients`; `GET /bank-accounts`; `GET`, `POST`, `PUT` te `/products`; `GET /product/categories`; `GET` dhe `POST` te `/invoice/wtn` | Për token dhe endpoint, pa pritje |

Ky është kufiri që integrimet me shumë fije e hasin më shpesh. Zgjidhja nuk është riprovimi i
menjëhershëm, por radhitja e kërkesave për biznes: paralelizmi nuk jep më shumë fatura, vetëm më
shumë pritje.

### Praktika

- Prisni sa thotë `Retry-After`. Kur mungon, prisni një sekondë dhe riprovoni me vonesë progresive:
  1 s, 2 s, 4 s.
- Për shumë fatura jo-cash përdorni `POST /invoice/bulk-noncash`: buxheti numëron kërkesa, jo fatura.
- Mbani në cache katalogun, kategoritë dhe monedhat, dhe mos i lexoni paralelisht nga i njëjti
  token.

## Pagination

Listat nuk kanë të gjitha të njëjtin pagination.

| Endpoint-i | Parametrat | `total` | Kufiri i `limit` |
| --- | --- | --- | --- |
| `GET /invoice`, `GET /invoice/wtn`, `GET /cash-register/actions` | `limit`, `offset` | Jo | Pa kufi |
| `GET /clients`, `GET /bank-accounts` | `limit`, `offset` | Po | 100 |
| `GET /products` | `limit`, `offset` | Po | 500. Pa `limit` kthehet i gjithë katalogu |
| `GET /purchase-invoices` | `page`, nga 1 | Jo | |

Pa `limit` merret `20` dhe pa `offset` merret `0`, me përjashtim të produkteve. Numëruesit vijnë në
objektin `pagination`: `records` (sa erdhën në këtë faqe), `total` (sa ekzistojnë, ku llogaritet),
`limit` dhe `offset`. Kur nuk ka `total`, ndaloni kur një faqe vjen më e shkurtër se `limit`. Te
faturat e blerjes përsëritni me `page + 1` sa kohë `pagination.hasMore` është `true`.

Listat kthehen nga më e reja te më e vjetra. Kur lexoni një periudhë të mbyllur, kufizojeni me
`fromDate` dhe `toDate`, që faqet të mos zhvendosen nga faturat e reja.

Lista e produkteve e mban `pagination` **krahas** `data`, jo brenda, dhe `data` mbetet një listë e
thjeshtë: `data[0]` është produkt, ndërsa te listat e tjera elementët janë te `data.items`.

## Formatet e të dhënave

| Të dhënat | Formati |
| --- | --- |
| Datat | `YYYY-MM-DD` |
| Data dhe ora | `YYYY-MM-DD HH:MM:SS`, ora lokale e Shqipërisë (CET/CEST), pa zonë kohore |
| Shumat | Numra JSON, jo string, në monedhën e faturës. Fushat `*_all` janë në lekë |
| Monedha | Kod ISO 4217. Pa `currency` merret `ALL`. `exchange_rate` është sa lekë vlen një njësi e monedhës |
| Normat e TVSH-së | `0`, `6`, `10` ose `20`, si numra |
| Vlerat logjike | `true` ose `false` në JSON |
| NIPT | Një shkronjë, tetë shifra, një shkronjë: `L62221018T` |
| Shteti | ISO 3166-1 alpha-3: `ALB`, `RKS`, `ITA` |
| Identifikuesit fiskalë | `iic` 32 karaktere hexadecimal; `fic` dhe `eic` UUID |
| Kodimi | UTF-8. Dërgoni `Content-Type: application/json` |

### Kodet e njësive matëse

`unit_code`, te produktet dhe te rreshtat e e-faturës, pranon vetëm kodet e mëposhtme (UN/ECE Rec. 20,
sipas listës së administratës tatimore). Kodi është ai që shkruhet në dokumentin fiskal; teksti i
njësisë nxirret prej tij dhe nuk dërgohet.

| Grupi | Kodet |
| --- | --- |
| Numërim | `C62` njësi, `XPP` copë, `PR` palë, `DZN` duzinë, `SET` set, `IE` person, `E55` përdorim, `E54` udhëtim, `QB` faqe, `D68` fjalë, `H93` përqindje |
| Peshë | `KGM` kg, `58` kg neto, `E4` kg bruto, `GRM` g, `DTN` kuintal, `TNE` ton, `DT` ton i thatë |
| Vëllim | `LTR` litër, `MLT` mililitër, `MTQ` m³ |
| Gjatësi dhe sipërfaqe | `MTR` metër, `CMT` cm, `MMT` mm, `LM` metër linear, `KMT` km, `MTK` m² |
| Kohë | `SEC` sekondë, `MIN` minutë, `HUR` orë, `DAY` ditë, `MON` muaj, `ANN` vit, `E49` ditë pune, `OT` orë jashtë orarit |
| Të tjera | `KWH` kWh, `MSK` m/s², `M4` vlerë monetare |
| Paketim | `XBX` kuti, `XPK` pako, `XPX` paletë, `XRO` rrotull, `XBG` qese, `XBO` shishe, `XCT` karton, `XCR` arkë, `XSA` thes, `XCA` kanaçe, `XBA` fuçi |

## Identifikoni aplikacionin tuaj

Nëse software-i juaj përdoret nga më shumë se një biznes, aplikacioni juaj identifikohet me një çift
kredencialesh që i dërgoni në çdo kërkesë, krahas token-it të përdoruesit:

```
X-Client-Id: ft_id_a1b2c3d4e5f6g7h8i9j0k1l2
X-Client-Secret: ft_sk_...
```

- **Client id** fillon me `ft_id_` dhe është publik. **Client secret** fillon me `ft_sk_` dhe është i
  fshehtë: trajtojeni si fjalëkalim.
- Të dyja i përkasin aplikacionit tuaj, jo biznesit. Nuk gjenerohen për çdo biznes dhe nuk duhet të
  përfundojnë në kod që shpërndahet dhe mund të lexohet nga të tjerët.
- Kredencialet e para i merrni nga fature.al kur regjistrohet integrimi juaj. Më pas i shihni dhe i
  rigjeneroni vetë nga **Konfigurime > Zhvillues** në llogarinë tuaj në fature.al, ku shihni edhe sa
  përdorues dhe sa biznese kanë punuar përmes aplikacionit tuaj në 24 orët e fundit.

Secret-i shfaqet **vetëm një herë**, në momentin që gjenerohet, dhe nuk mund të lexohet më pas.
Ruajeni menjëherë.

Nëse e humbisni ose dyshoni se ka rrjedhur, rigjenerojeni nga i njëjti ekran. **Rigjenerimi është i
menjëhershëm dhe pa periudhë mbivendosjeje:** secret-i i vjetër ndërpritet në kërkesën e parë që
vjen pas tij. Prandaj përgatisni instalimet tuaja që të marrin secret-in e ri dhe rigjenerojeni vetëm
kur jeni gati ta shpërndani menjëherë. Client id nuk ndryshon, kështu që ju mbetet të zëvendësoni
një vlerë të vetme.

### Vazhdoni të dërgoni edhe header-in User-Agent

Krahas kredencialeve, në çdo kërkesë dërgoni header-in `User-Agent` në formatin
`<emri i aplikacionit>/<versioni i build-it>`:

```
User-Agent: EmriIAplikacionit/2.4.1
```

- **Emri i aplikacionit** duhet të jetë gjithmonë i njëjti: në çdo kërkesë, për çdo biznes dhe në
  çdo version të aplikacionit. Ky emër është identifikuesi i integrimit tuaj, prandaj mos e ndryshoni
  dhe mos e varioni sipas kompanisë, pajisjes apo mjedisit. Përdorni shkronja, numra ose shenjat
  `_ . + -`, filloni me një shkronjë dhe mos vendosni hapësira.
- **Versioni i build-it** ndryshon me çdo publikim të aplikacionit tuaj, p.sh. `2.4.1` ose
  `2026.07.13`. Pa hapësira dhe pa `/`.

Kredencialet tregojnë cili aplikacion po flet, ndërsa User-Agent-i tregon cili version i tij është në
përdorim, gjë që na ndihmon të reagojmë më shpejt kur raportoni një problem. Nëse kredencialet
mungojnë, User-Agent-i mbetet e vetmja mënyrë për të identifikuar integrimin tuaj.

### Kalimi në detyrim

Nëse header-at **nuk dërgohen fare**, kërkesa vazhdon normalisht dhe integrimi identifikohet vetëm nga
User-Agent-i. Çdo ofrues software-i njoftohet paraprakisht për datën nga e cila kredencialet bëhen të
detyrueshme për aplikacionin e tij; vetëm pas asaj date kërkesat pa kredenciale refuzohen me
`401 Unauthorized`.

Nëse header-at **dërgohen por nuk verifikohen**, kërkesa refuzohet menjëherë me `401 Unauthorized`,
pa pritur asnjë datë. Nëse ende nuk i keni kredencialet, mos i dërgoni header-at bosh ose me vlera
provizore.

| Shkaku | Refuzohet | `message` |
| --- | --- | --- |
| Header-at mungojnë | Vetëm pas datës së detyrimit | Kjo kerkese duhet te dergoje header-at X-Client-Id dhe X-Client-Secret. |
| Client id nuk njihet | Gjithmonë | Client ID nuk njihet. |
| Client secret i gabuar ose mungon | Gjithmonë | Client secret nuk eshte i sakte. |
| Aplikacioni është pezulluar | Gjithmonë | Ky aplikacion integrimi eshte pezulluar. |

Filloni ta dërgoni çiftin që tani: kërkesat me kredenciale të sakta punojnë njësoj si më parë.

## Regjistrimi i kompanive nga partnerët

Ofruesit e software-it mund t'i hapin vetë llogaritë e klientëve të tyre me grupin **Regjistrimi i
kompanive**. Grupi është i mbyllur si parazgjedhje dhe hapet me kërkesë. Radha e hapave:

1. `POST /register`: krijon kompaninë dhe kthen token-in e përdoruesit të parë dhe id-në e njësisë.
2. `POST /on-boarding/certificate`: ngarkon certifikatën elektronike, pa të cilën asgjë nuk
   nënshkruhet.
3. `POST /on-boarding/branch/{id}`: vendos `businessUnitCode` te njësia.
4. `POST /on-boarding/fiscal-device`: regjistron TCR-në te tatimet dhe kthen kodin e saj. Vetëm për
   fatura cash.
5. `POST /on-boarding/user/{id}`: vendos `operatorCode` dhe `fiscalTcrCode` te përdoruesi.
6. `POST /on-boarding/bank-account`: llogaria bankare për faturat jo-cash dhe e-faturat.

Në sandbox, NIPT-i `L62221018T` te `POST /register` kalon në një rrjedhë prove që nuk krijon kompani
të re. Detajet janë te grupi.

## Postman dhe mjete të tjera

Nuk shpërndajmë koleksion Postman, sepse do të vjetrohej sa herë ndryshon API-ja. Importoni direkt
dokumentin OpenAPI, i cili gjenerohet në çdo kërkesë dhe është gjithmonë i përditësuar:

**Postman** > *Import* > *Link* > `https://fature.al/docs/api.json`

E njëjta adresë vlen për Insomnia, Bruno, Swagger UI ose çdo gjenerues klientësh. Për v2 dhe për
partner API-n përdorni `/docs/api/v2.json` dhe `/docs/api/partner.json`. Pas importimit vendosni
`Authorization: Bearer <api_token>`, `X-Client-Id` dhe `X-Client-Secret` si variabla të koleksionit
dhe zgjidhni serverin Sandbox derisa integrimi të jetë gati.

## Ndryshimet

Çdo shtesë në API, nga më e reja te më e vjetra, me datën kur hyri në kod. Asnjë fushë ekzistuese
nuk ka ndryshuar kuptim dhe asnjë endpoint nuk është hequr; shihni edhe *Serverat dhe versionet*.

| Data | Ndryshimi |
| --- | --- |
| 2026-10-05 | `GET /purchase-invoices`: `pagination.hasMore` tregon kur ka faqe tjetër, edhe kur `items` vjen bosh |
| 2026-09-30 | Lëshimi i faturave merr kufirin e vet të kërkesave: 300 në minutë (5 në sekondë) për token |
| 2026-09-29 | v2: arka fiskale, me `internalId` të detyrueshëm te hyrjet dhe daljet e parave |
| 2026-09-28 | Fleta shoqëruese kthen orën e fiskalizimit, jo vetëm datën |
| 2026-09-24 | v2: fletët shoqëruese, me `internalId` të detyrueshëm |
| 2026-09-14 | v2: `payment_methods[].amount` pranon çdo numër, edhe 0 dhe negative, si CIS-i |
| 2026-09-12 | v2: pagesa e faturës si listë `payment_methods`, në lëshim, anulim, listë, detaje, bulk dhe PDF |
| 2026-09-07 | Anulimet marrin kufirin e tyre të kërkesave: 30 në minutë dhe 600 në orë për token |
| 2026-08-26 | `POST /on-boarding/branch`: partnerët krijojnë njësi biznesi |
| 2026-08-04 | Kredencialet e aplikacionit: header-at `X-Client-Id` dhe `X-Client-Secret` |
| 2026-07-22 | Wolt Partner API, me dokumentin e vet |
| 2026-07-15 | `GET /purchase-invoices` |
| 2026-07-07 | `GET /reports/cash-register/closing` |
| 2026-06-09 | v2: klientët në formatin e ri, `/api/v2/clients` |
| 2026-05-19 | `PUT /clients/{id}` dhe `PUT /products/{id}`; `GET /currencies` dhe `GET /exchange-rates` |
| 2026-04-24 | `GET /products/{id}/details` |
| 2026-04-22 | `GET /bank-accounts`; `GET /dashboard/summary` |
| 2026-04-21 | Raportet nën `/reports`; `GET /cash-register/balance` |
| 2026-04-20 | Arka: `deposit`, `withdraw` dhe lista `actions` |
| 2026-04-19 | Klientët (lista, detajet, krijimi); `POST /products`; fletët shoqëruese (WTN) |
| 2026-02-26 | Faturat porosi dhe përmbledhëse |
| 2026-02-19 | `GET /invoice/{id}/details` |
| 2025-02-04 | `GET /invoice` |
| 2023-12-11 | `POST /invoice/details/{internalId}` |
| 2023-10-31 | `POST /invoice/cancel-by-internal-id/{internalId}` |
| 2023-10-17 | Arka: hapja dhe mbyllja e ditës; `GET /register` |
| 2023-09-28 | Regjistrimi i kompanive nga partnerët dhe onboarding-u: certifikata, njësia, përdoruesi, pajisja fiskale, llogaria bankare |
| 2023-09-23 | `GET /client/search` |
| 2023-01-30 | `POST /invoice/bulk-noncash` |
| 2022-12-02 | Versioni i parë: lëshimi i faturave cash, jo-cash dhe e-faturave |

## Mbështetja

Pyetjet për integrimin: [info@fature.al](mailto:info@fature.al). Nëse jeni shtëpi software-i dhe doni
t'i sillni klientët tuaj mbi fature.al, na shkruani: ju japim kredencialet e aplikacionit dhe një
mjedis prove.

## Servers

- `https://fature.al/api/v1` - Live
- `https://demo.fature.al/api/v1` - Sandbox

## Endpoints

### GET /account

**Summary:** Merr të dhënat e llogarisë

Kthen përdoruesin e token-it dhe kontekstin fiskal që merr çdo faturë e lëshuar me të:
kompaninë, njësinë e biznesit, pajisjen fiskale, të drejtat dhe modulet e abonimit.

Përdoreni pas `GET /ping` për të konfirmuar me cilin biznes punoni, dhe para faturës së parë
cash për të parë nëse përdoruesi ka pajisje fiskale. Asnjë nga këto vlera nuk dërgohet në
kërkesat e faturimit; ato zgjidhen nga token-i.

| Fusha | Çfarë është |
| --- | --- |
| `name`, `email` | Përdoruesi që mban token-in |
| `company`, `nipt` | Emri dhe NIPT-i i kompanisë që lëshon faturat |
| `fiscalCode` | Kodi TCR i pajisjes fiskale të përdoruesit. String bosh kur nuk ka; atëherë faturat cash dhe veprimet e arkës refuzohen |
| `branch` | Njësia e biznesit e përdoruesit: `name`, `address` dhe `city` |
| `companyBranches` | Të gjitha njësitë e kompanisë, si objekt me adresën si çelës dhe emrin si vlerë |
| `setupFinished` | `true` kur kompania i ka mbyllur hapat e konfigurimit dhe mund të lëshojë fatura |
| `permissions` | `createArticles` dhe `createClients`: nëse përdoruesi mund të krijojë produkte dhe klientë. Pa to `POST /products` dhe `POST /clients` refuzohen me `403` |
| `configs.openDayAlways0` | `true` kur kompania e hap ditën në arkë gjithmonë me gjendje `0` |
| `vatConfigs` | `issuerInVat` thotë nëse kompania është në skemën e TVSH-së. `vat_rates` janë normat që pranohen në rreshtat e faturës: `20`, `10`, `6` dhe `0` në skemë, vetëm `0` jashtë saj. `vat_exempts` janë llojet e përjashtimit që pranohen, me `code` dhe `label` |
| `subscription` | `cash`, `noncash`, `einvoice` dhe `wtn`: cilat module ka abonimi. Endpoint-i i një moduli që mungon përgjigjet `401` me `status: false` |

Ruani `nipt` dhe `fiscalCode` pranë konfigurimit të integrimit, që një token i ndërruar
gabimisht të kapet para se të lëshojë fatura në emër të një biznesi tjetër.

**Tags:** Llogaria

**Responses:**

- `200` - Përdoruesi i token-it dhe konteksti fiskal i tij: kompania, njësia e biznesit, pajisja fiskale, të drejtat dhe modulet e abonimit.
- `401`

---

### GET /bank-accounts

**Summary:** Listo llogaritë bankare

Kthen llogaritë bankare aktive të kompanisë, me llogarinë e parazgjedhur të parën dhe pastaj
nga më e reja te më e vjetra, me kërkim me tekst.

Përdoreni për të zgjedhur llogarinë që shkon në një faturë jo-cash ose në një e-faturë: ruani
`id`-në për `bank_account`, ose `iban`-in për `bank_account_iban`. Lista ndryshon rrallë, ndaj
mbajeni në cache.

- Pagination me `limit` dhe `offset`. `limit` kufizohet në `100`; një vlerë më e madhe ulet pa
  gabim. `pagination` kthen `total`, ndaj vazhdoni me `offset += limit` derisa `offset` të
  arrijë `total`.
- `query` kërkon me përputhje të pjesshme në emrin e bankës, IBAN, SWIFT, mbajtësin dhe
  shënimet.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

Çdo llogari vjen me `bank_name`, `iban`, `swift`, `holder`, `currency_code` (ISO 4217),
`is_default`, `notes`, `valid_from` dhe `valid_to` kur llogaria ka periudhë vlefshmërie, dhe
`created_at` (ISO 8601).

**Tags:** Llogaritë bankare

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Sa llogari të kthehen në një faqe, deri në 100. |
| `offset` | query | no | Nga cila llogari të fillohet, duke numëruar nga 0. |
| `query` | query | no | Kërkim në emrin e bankës, IBAN, SWIFT, mbajtësin ose shënimet. |

**Responses:**

- `200` - Llogaritë bankare aktive të kompanisë, me të parazgjedhurën të parën, dhe `pagination` me `total`; `items` është bosh kur kompania nuk ka llogari.
- `401`
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### GET /cash-register/actions

**Summary:** Listo veprimet e arkës

Kthen historikun e arkës, nga më i riu te më i vjetri, me filtrim sipas tipit dhe datës:
hyrjet, daljet, hapjet dhe mbylljet e ditës.

Përdoreni për rakordimin e turnit dhe për të lexuar gjendjen fiskale të një veprimi që u
ruajt ndërsa CIS-i nuk arrihej.

| `type` | Veprimi |
| --- | --- |
| `MONEY_IN` | Hyrje parash |
| `MONEY_OUT` | Dalje parash |
| `OPEN_DAY` | Hapje e ditës |
| `CLOSE_DAY` | Mbyllje e ditës |

- Disa tipe ndahen me presje: `type=MONEY_IN,MONEY_OUT` kthen vetëm lëvizjet e parave.
- Mbyllja nga `POST /cash-register/close-balance` del si `MONEY_OUT` me përshkrimin
  "Mbyllje turni/xhiro ditore", jo si `CLOSE_DAY`.
- `fromDate` dhe `toDate` kufizojnë sipas datës së veprimit, të dyja përfshirëse.
- Pagination me `limit` dhe `offset`. `pagination` nuk kthen `total`, ndaj ndaloni kur një faqe
  vjen më e shkurtër se `limit`.

`amount` është gjithmonë pozitive, në ALL; drejtimin e jep `action_type`. `fiscal_status` dhe
`fiscal_fic` thonë nëse veprimi është fiskalizuar.

**Tags:** Arka fiskale

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Sa veprime të kthehen në një faqe. |
| `offset` | query | no | Nga cili veprim të fillohet, duke numëruar nga 0. |
| `type` | query | no | Filtro sipas tipit: `MONEY_IN`, `MONEY_OUT`, `OPEN_DAY` ose `CLOSE_DAY`, disa tipe të ndara me presje. |
| `fromDate` | query | no | Data e fillimit, `YYYY-MM-DD`. |
| `toDate` | query | no | Data e mbarimit, `YYYY-MM-DD`. |

**Responses:**

- `200` - Lista e veprimeve të periudhës, nga më i riu te më i vjetri, me `pagination`; `items` është bosh kur nuk ka veprime.
- `401`
- `500` - Gabim i papritur në server.

---

### GET /cash-register/balance

**Summary:** Merr gjendjen e arkës

Kthen gjendjen e pajisjes fiskale (TCR) të përdoruesit të token-it, në ALL, bashkë me kodin e
saj `fiscal_tcr_code`.

Pa `toDate` kthehet gjendja e tanishme. Me `toDate` kthehet gjendja në fund të asaj dite, për
rakordim me një ditë të shkuar. Gjendja ruhet në cache për 5 sekonda, ndaj një veprim i sapo
regjistruar mund të duket pas pak.

- Përdoruesi duhet të ketë një TCR.

**Tags:** Arka fiskale

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `toDate` | query | no | Data, `YYYY-MM-DD`, deri te e cila llogaritet gjendja e arkës. Pa të kthehet gjendja e fundit. |

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `500` - Gabim i papritur në server.

---

### POST /cash-register/close-balance

**Summary:** Mbyll ditën në arkë

Mbyll ditën e punës në pajisjen fiskale (TCR) të përdoruesit të token-it: nxjerr gjithë
gjendjen nga arka dhe kthen shumën që doli.

Thirreni në fund të turnit, pa kontrolluar më parë nëse dita është e hapur: kur nuk është,
hapet vetë me `0` dhe mbyllet menjëherë. Kërkesa nuk ka body.

- Përdoruesi duhet të ketë një TCR.

`balance` është shuma në ALL që doli nga arka, me dy shifra pas presjes; `0` kur arka ishte
bosh. Dalja del te
`GET /cash-register/actions` si veprim `MONEY_OUT` me përshkrimin
"Mbyllje turni/xhiro ditore"; kur arka ishte bosh nuk regjistrohet asnjë dalje. Kur CIS-i
nuk arrihet, mbyllja ruhet dhe fiskalizohet vetë më vonë; përgjigja është e njëjtë.

**Tags:** Arka fiskale

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale ose kur mbyllja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`

---

### POST /cash-register/deposit

**Summary:** Regjistro hyrje parash

Regjistron para që hyjnë në arkë pa qenë shitje, si një arkëtim nga klienti ose një fond
fillestar, si veprim `MONEY_IN` në pajisjen fiskale (TCR) të përdoruesit të token-it.

Për një shitje lëshoni faturë cash, jo hyrje. Nëse dita nuk është hapur ende, hapet vetë me
`0`.

- `amount` është në ALL dhe duhet të jetë më e madhe se `0`.
- `id_client`, kur dërgohet, duhet të jetë `id`-ja e një klienti të kompanisë suaj.
- Përdoruesi duhet të ketë një TCR.

Përgjigja mban `id`-në e veprimit, numrat e tij (`transaction_no`, `cash_action_no`) dhe
gjendjen fiskale (`fiscal_status`, `fiscal_uuid`, `fiscal_fic`). Kur CIS-i nuk arrihet,
veprimi ruhet dhe fiskalizohet vetë më vonë: përgjigja vjen me `status: true`,
`fiscal_status: UNFISCALISED` dhe pa `id`; lexojeni më pas te `GET /cash-register/actions`.

**Tags:** Arka fiskale

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, kur `id_client` nuk i përket kompanisë suaj, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

---

### POST /cash-register/open-balance

**Summary:** Hap ditën në arkë

Hap ditën e punës në pajisjen fiskale (TCR) të përdoruesit të token-it me gjendjen fillestare
`balance`, në ALL, dhe e regjistron si veprim `OPEN_DAY`.

Thirreni në fillim të turnit, para faturës së parë cash. Nuk është e detyrueshme: fatura e
parë cash, një hyrje, një dalje ose mbyllja e hapin vetë ditën me `0`. Përdoreni kur dita
nis me para në arkë dhe doni që gjendja të jetë e saktë.

- `balance` është opsional; pa të merret `0`. Një vlerë negative refuzohet.
- Përdoruesi duhet të ketë një TCR.

Përgjigja kthen `balance` të rrumbullakosur në dy shifra pas presjes, siç u ruajt. Kur CIS-i
nuk arrihet, hapja ruhet dhe fiskalizohet vetë më vonë; përgjigja është e njëjtë.

**Tags:** Arka fiskale

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, kur `balance` është negative, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`

---

### POST /cash-register/withdraw

**Summary:** Regjistro dalje parash

Regjistron para që dalin nga arka, si një pagesë furnitori ose një tërheqje gjatë ditës, si
veprim `MONEY_OUT` në pajisjen fiskale (TCR) të përdoruesit të token-it.

Për tërheqjen e gjithë gjendjes në fund të turnit përdorni `POST /cash-register/close-balance`.
Nëse dita nuk është hapur ende, hapet vetë me `0`.

- `amount` është në ALL dhe duhet të jetë më e madhe se `0`; shenja vjen nga endpoint-i, jo
  nga numri.
- Arka duhet të ketë të paktën `amount`; kur nuk ka, dalja refuzohet.
- `id_client`, kur dërgohet, duhet të jetë `id`-ja e një klienti të kompanisë suaj.
- Përdoruesi duhet të ketë një TCR.

Përgjigja ka të njëjtin format si hyrja. Kur CIS-i nuk arrihet, veprimi ruhet dhe
fiskalizohet vetë më vonë: përgjigja vjen me `status: true`, `fiscal_status: UNFISCALISED`
dhe pa `id`; lexojeni më pas te `GET /cash-register/actions`.

**Tags:** Arka fiskale

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, kur arka nuk ka aq para sa `amount`, kur `id_client` nuk i përket kompanisë suaj, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

---

### GET /client/search

**Summary:** Kërko një biznes sipas NIPT

Kërkon një biznes në regjistrin fiskal sipas NIPT-it dhe kthen emrin, adresën, qytetin dhe
shtetin e tij.

Përdoreni për të plotësuar të dhënat e një klienti të ri nga një fushë e vetme, ose për të
kapur një NIPT të gabuar para se të dalë në faturë. Për klientët që keni ruajtur tashmë në
fature.al përdorni `GET /clients` me `query`.

`verified` thotë nëse regjistri e konfirmoi biznesin. Dy përgjigjet e refuzimit nuk janë e
njëjta gjë:

- `404`: NIPT-i nuk është në regjistër.
- `503`: regjistri nuk u arrit dhe NIPT-i mbeti i pakontrolluar. Riprovoni më vonë.

**Tags:** Klientët

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `nuis` | query | yes | NIPT-i që kërkohet në regjistrin fiskal: një shkronjë, tetë shifra, një shkronjë. Shkronjat e vogla pranohen. I detyrueshëm. |

**Responses:**

- `200` - Biznesi që u gjet te `client`, me `verified: true`.
- `401`
- `422` - NIPT-i mungon ose nuk është në formatin X00000000X. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `404` - NIPT-i nuk është në regjistrin fiskal.
- `503` - Regjistri fiskal nuk u arrit dhe NIPT-i mbeti i pakontrolluar. Riprovoni më vonë.

---

### GET /clients

**Summary:** Listo klientët

Kthen klientët e kompanisë, nga më i riu te më i vjetri, me kërkim me tekst. Çdo klient vjen
me të njëjtat fusha si te `GET /clients/{id}/details`.

Përdoreni për të gjetur `id`-në e një klienti të ruajtur, ose për të sinkronizuar regjistrin
tuaj me atë të fature.al.

- Pagination me `limit` dhe `offset`. `limit` kufizohet në `100`; një vlerë më e madhe ulet pa
  gabim. `pagination` kthen `total`, ndaj vazhdoni me `offset += limit` derisa `offset` të
  arrijë `total`.
- `query` kërkon me përputhje të pjesshme në emrin e kompanisë, emrin, mbiemrin, atësinë,
  NIPT-in, numrin e dokumentit, adresën, email-in, telefonin dhe numrin e klientit, njësoj si
  kërkimi i klientëve në fature.al.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

`company_type` kthehet `null` për një person, `first_name` dhe `surname` për një kompani;
`name` mban gjithmonë emrin e plotë.

**Tags:** Klientët

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Sa klientë të kthehen në një faqe, deri në 100. |
| `offset` | query | no | Nga cili klient të fillohet, duke numëruar nga 0. |
| `query` | query | no | Kërkim në emrin e kompanisë, emrin, mbiemrin, atësinë, NIPT-in, numrin e dokumentit, adresën, email-in, telefonin ose numrin e klientit. |

**Responses:**

- `200` - Klientët e faqes te `items`, me `pagination`; `items` është bosh kur asnjë klient nuk përputhet.
- `401`
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### POST /clients

**Summary:** Krijo një klient

Krijon një klient të ri të kompanisë, kompani ose person, dhe kthen `id`-në e tij.

Përdoreni kur mbani regjistrin e klientëve në fature.al. Kur klienti ju duhet vetëm për një
faturë, dërgojeni te objekti `client` i faturës; ky endpoint nuk është i nevojshëm.

`client_type` vendos cilat fusha janë të detyrueshme:

| `client_type` | Fushat e detyrueshme |
| --- | --- |
| `COMPANY` | `company_name`, `nipt`, `address`, `city` |
| `PERSON` | `name`, `surname`, `document_type`, `document_number` |

- Për një biznes shqiptar thirrni më parë `GET /client/search`: emri, adresa dhe qyteti vijnë
  gati nga regjistri.
- NIPT-i është unik brenda kompanisë; një klient i dytë me të njëjtin NIPT refuzohet me `409`.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

Ruani `id`-në e kthyer: me të lexoni dhe përditësoni klientin më vonë.

**Tags:** Klientët

**Request body content types:** application/json

**Responses:**

- `200` - Klienti i sapokrijuar te `client`, me `id`-në e tij.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Ekziston tashmë një klient me këtë NIPT.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### PUT /clients/{id}

**Summary:** Përditëso një klient

Përditëson një klient ekzistues dhe kthen të dhënat e tij pas ndryshimit.

Body i kërkesës ka të njëjtin format dhe të njëjtat fusha të detyrueshme sipas `client_type`
si `POST /clients`.

- NIPT-i i ri nuk mund të përkojë me atë të një klienti tjetër; refuzohet me `409`.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

**Tags:** Klientët

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e klientit në fature.al. |

**Request body content types:** application/json

**Responses:**

- `200` - Klienti pas ndryshimit te `client`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `404` - Klienti nuk u gjet, ose nuk i përket kompanisë suaj.
- `409` - Ekziston tashmë një klient tjetër me këtë NIPT.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### GET /clients/{id}/details

**Summary:** Merr një klient sipas id

Kthen një klient të vetëm me të gjitha fushat, kompani ose person.

Përdoreni kur keni ruajtur `id`-në nga lista ose nga krijimi dhe ju duhen të dhënat e
përditësuara. `company_type` kthehet `null` për një person, `first_name` dhe `surname` për
një kompani; `name` mban gjithmonë emrin e plotë.

**Tags:** Klientët

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e klientit në fature.al. |

**Responses:**

- `200` - Klienti i kërkuar te `client`, me të gjitha fushat.
- `401`
- `404` - Klienti nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server.

---

### GET /currencies

**Summary:** Listo monedhat

Kthen monedhat e konfiguruara për kompaninë, me `ALL` gjithmonë të parën dhe të tjerat sipas
kodit.

Përdoreni për të mbushur zgjedhjen e monedhës në sistemin tuaj: `code` është kodi ISO 4217 që
dërgoni si `currency` te faturat dhe te produktet. Pa `currency` merret `ALL`. Për kursin e
ditës thirrni `GET /exchange-rates`.

- `id` është id-ja e monedhës në fature.al; `name` mban të njëjtën vlerë si `code`.
- Lista ndryshon vetëm kur biznesi shton një monedhë nga paneli, ndaj mbajeni në cache.

**Tags:** Monedhat

**Responses:**

- `200` - Monedhat e konfiguruara për kompaninë, me `ALL` të parën dhe të tjerat sipas kodit.
- `401`

---

### GET /dashboard/summary

**Summary:** Merr përmbledhjen e ditës

Kthen një pamje të shpejtë të ditës së sotme për ekranin kryesor, në tre objekte:

| Objekti | Përmbajtja |
| --- | --- |
| `shift` | `is_open`, `opened_at`, `cash_in_drawer` dhe `currency` për pajisjen fiskale të përdoruesit. Pa pajisje, `is_open` është `false` dhe `cash_in_drawer` është `0`. |
| `today` | `invoice_count`, `gross_total` dhe `hourly_series`, një pikë për çdo dy orë me `hour` dhe `gross`. |
| `week` | `series`, një pikë për secilën nga 7 ditët e fundit me `date` dhe `gross`, dhe `wow_delta_percent`, ndryshimi në përqindje ndaj 7 ditëve të mëparshme, `null` kur ato nuk kanë shitje. |

Shitjet numërojnë faturat cash, jo-cash dhe e-faturat, pa faturat porosi dhe pa faturat e
anuluara. Shumat janë në ALL.

Përgjigja ruhet në cache për 5 sekonda për përdorues, prandaj nuk është burim për rakordim:
për shifra të sakta mbi një periudhë përdorni raportet.

**Tags:** Paneli

**Responses:**

- `200` - Përmbledhja e ditës te `data`, në tre objekte: `shift`, `today` dhe `week`; shifrat mund të jenë deri në 5 sekonda të vjetra nga cache.
- `401`
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /exchange-rates

**Summary:** Merr kursin e këmbimit të ditës

Kthen kursin e shitjes së ditës për çdo monedhë, në lekë për një njësi të monedhës, nga burimi
i zgjedhur. Të dhënat vijnë nga kursi.al dhe ruhen në cache në server për një orë.

Përdoreni për të propozuar `exchange_rate` kur lëshoni një faturë në monedhë të huaj. Kursi që
shkon në faturë është ai që dërgoni ju, jo ky.

| `source` | Burimi |
| --- | --- |
| `BOA` | Banka e Shqipërisë, kursi zyrtar |
| `BKT` | Banka Kombëtare Tregtare |
| `Iliria98` | Këmbim valutor Iliria '98 |
| `ADON` | Këmbim valutor Adon |

- `source` dallon shkronjat e mëdha: `bkt` nuk njihet. Një burim që nuk njihet nuk kthen gabim;
  përdoret `BOA`, dhe `source` në përgjigje thotë cili burim u përdor.
- `rates` është objekt me kodin e monedhës si çelës dhe kursin si vlerë, gjithmonë me `ALL: 1`.
  `EUR: 98.5` do të thotë që një euro vlen 98.5 lekë.
- `fetchedAt` është koha e përgjigjes, ISO 8601.

Kur kursi.al nuk arrihet, `rates` mban vetëm `ALL: 1`, pa gabim dhe deri në një orë. Mos e
trajtoni si kurs: mbani snapshot-in e fundit të plotë dhe përdoreni atë.

**Tags:** Monedhat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `source` | query | no | Burimi i kursit: `BOA`, `BKT`, `Iliria98` ose `ADON`, me shkronjat siç janë. Një vlerë tjetër bie te `BOA`. |

**Responses:**

- `200` - Kursi i shitjes i ditës për çdo monedhë nga burimi `source`, gjithmonë me `ALL: 1`; kur kursi.al nuk arrihet, `rates` mban vetëm `ALL: 1`.
- `401`

---

### GET /invoice

**Summary:** Listo faturat

Kthen faturat e kompanisë, nga më e reja te më e vjetra, me filtrim sipas tipit, datës dhe një
teksti kërkimi. Çdo faturë vjen me blerësin, shumat dhe pagesën, por pa rreshtat; për rreshtat
thirrni `GET /invoice/{id}/details`.

- Pagination me `limit` dhe `offset`. `pagination` nuk kthen `total`, ndaj ndaloni kur një faqe
  vjen më e shkurtër se `limit`.
- Kur lexoni një periudhë të mbyllur, kufizojeni me `fromDate` dhe `toDate`, që faqet të mos
  zhvendosen nga faturat e reja.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, pret deri në një sekondë
  dhe pastaj refuzohet me `429`.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Sa fatura të kthehen në një faqe. |
| `offset` | query | no | Nga cila faturë të fillohet, duke numëruar nga 0. |
| `id_pos_shift` | query | no | Vetëm faturat e këtij turni të POS-it, si filtri i turnit te lista e faturave në web. |
| `type` | query | no | Filtro sipas tipit: `CASH`, `NONCASH` ose `EINVOICE`, disa tipe të ndara me presje. Një vlerë tjetër injorohet pa gabim; nëse asnjë nuk mbetet e vlefshme, filtri nuk zbatohet fare. |
| `fromDate` | query | no | Data e fillimit, `YYYY-MM-DD`. |
| `toDate` | query | no | Data e mbarimit, `YYYY-MM-DD`. |
| `query` | query | no | Kërkim sipas numrit të faturës, emrit të blerësit ose NIPT-it. |

**Responses:**

- `200` - Faturat e periudhës te `items`, nga më e reja te më e vjetra, me `pagination`; `items` është bosh kur nuk ka fatura.
- `401`
- `422` - Datat nuk janë në formatin `YYYY-MM-DD`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### POST /invoice/bulk-noncash

**Summary:** Lësho fatura jo-cash në bulk

Lëshon shumë fatura jo-cash me një kërkesë të vetme, për faturim periodik. Çdo element i
`invoices` ka të njëjtat fusha si body i `POST /invoice/noncash`, `internalId` përfshirë, dhe
lëshohet me të njëjtat rregulla.

Përgjigja është një objekt me një hyrje për çdo `internalId`, dhe statusi HTTP mbetet `200`
edhe kur ndonjë faturë dështon:

- kontrolloni `status` brenda çdo hyrjeje më vete, jo kodin HTTP;
- riprovoni vetëm `internalId`-të që dështuan, jo të gjithë bulk-un;
- faturat lëshohen një nga një, në radhë, ndaj një bulk i madh zgjat aq sa shuma e lëshimeve.

## Shembull: parapagim grupi

Një faturë për çdo pjesëtar që paguan pjesën e vet.

```json
{
  "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
        }
      ]
    }
  ]
}
```

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Një objekt me një hyrje për çdo `internalId`. Një faturë që dështon mban formatin e gabimit brenda hyrjes së vet, dhe statusi i përgjigjes mbetet 200.
- `401`

---

### POST /invoice/cancel-by-internal-id/{internalId}

**Summary:** Anulo një faturë sipas internalId

Anulon faturën duke e gjetur me `internalId`-në që dërguat kur e lëshuat, kështu që nuk keni
pse të mbani `id`-në e fature.al pranë shitjes suaj. Sillet njësoj si anulimi sipas id:

- pa body anulohet e gjithë fatura;
- me `lines` anulohet vetëm një pjesë, e mundur **vetëm për faturat cash**;
- rreshtat duhet të përputhen në `product_code` dhe `product_name`, dhe sasia vetëm ulet;
- një faturë me zbritje mbi të gjithë faturën anulohet vetëm e plotë.

Përgjigja është dokumenti korrigjues, me `iic` dhe `fic` të vetat. Kur CIS-i nuk arrihet,
anulimi ruhet me `fic: null` dhe fiskalizohet vetë më vonë.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `internalId` | path | yes | Identifikuesi juaj i faturës, i dërguar kur u lëshua. |

**Request body content types:** application/json

**Responses:**

- `200` - Dokumenti korrigjues, me `iic` dhe `fic` të vetat; `fic` është `null` kur CIS-i nuk u arrit dhe fiskalizimi do të përfundojë vetë.
- `401`
- `422` - Fatura nuk mund të anulohet në gjendjen e saj aktuale, ose rreshtat e dërguar nuk përputhen me origjinalin. `errors` thotë pse.
- `404` - Fatura nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server, përfshirë rastin kur anulimi nuk u regjistrua dot te CIS-i.
- `429` - Kufiri i anulimeve u arrit, ose një anulim tjetër i të njëjtit tip është ende në proces. Nga kufiri i anulimeve përgjigja mban vetëm `message` dhe header-in `Retry-After`.

---

### POST /invoice/cancel/{id}

**Summary:** Anulo një faturë sipas id

Anulon faturën duke lëshuar te CIS-i një dokument korrigjues, i cili merr numër të ri rendor.
Origjinali shënohet i anuluar vetëm kur anulimet e mbulojnë të gjithin.

## I plotë ose i pjesshëm

| Body | Çfarë ndodh |
| --- | --- |
| Bosh | Anulohet e gjithë fatura, sido që të jetë lloji i saj |
| Me `lines` | Anulohet vetëm pjesa e dërguar. **Vetëm për faturat cash** |

## Rregullat e anulimit të pjesshëm

- Çdo rresht duhet të ekzistojë në faturën origjinale me të njëjtin `product_code` dhe
  `product_name`.
- Sasia mund vetëm të ulet ose të mbetet e njëjtë; 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ë me zbritje mbi të gjithë faturën anulohet vetëm e plotë: zbritja është shpërndarë
  mbi të gjitha normat e TVSH-së, dhe një pjesë e rreshtave nuk e mban dot pjesën e vet pa e
  gabuar TVSH-në.

## Shembull: anulim i pjesshëm

Kthehet një mëngjes nga një faturë cash; pjesa tjetër e faturës mbetet e shitur.

```json
{
  "lines": [
    {
      "product_name": "Mëngjes",
      "product_code": "MNG-01",
      "quantity": 1
    }
  ]
}
```

Përgjigja është dokumenti korrigjues, me `iic` dhe `fic` të vetat. Kur CIS-i nuk arrihet,
anulimi ruhet me `fic: null` dhe fiskalizohet vetë më vonë. Anulimet kanë kufirin e tyre të
kërkesave: 30 në minutë dhe 600 në orë për token.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e faturës në fature.al. |

**Request body content types:** application/json

**Responses:**

- `200` - Dokumenti korrigjues, me `iic` dhe `fic` të vetat; `fic` është `null` kur CIS-i nuk u arrit dhe fiskalizimi do të përfundojë vetë.
- `401`
- `422` - Fatura nuk mund të anulohet në gjendjen e saj aktuale, ose rreshtat e dërguar nuk përputhen me origjinalin. `errors` thotë pse.
- `404` - Fatura nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server, përfshirë rastin kur anulimi nuk u regjistrua dot te CIS-i.
- `429` - Kufiri i anulimeve u arrit, ose një anulim tjetër i të njëjtit tip është ende në proces. Nga kufiri i anulimeve përgjigja mban vetëm `message` dhe header-in `Retry-After`.

---

### POST /invoice/cash

**Summary:** Lësho faturë cash

Lëshon një faturë me pagesë në çast nga pajisja fiskale (TCR) e lidhur me përdoruesin e
token-it: para në dorë, kartë, çek, kartë kompanie ose tollona. Nëse dita në arkë nuk është
hapur ende, hapet vetë me balancë `0`.

Përdoruesi i token-it duhet të ketë një TCR; pa të, kërkesa refuzohet me `200` dhe
`status: false`.

## Blerësi është opsional

Pa `client` fatura lëshohet për klientin e rastit, që është rasti normal i një arke. Sapo
dërgoni qoftë edhe një të dhënë të klientit, duhen `client.name`, `client.address` dhe
`client.city`, sepse adresa dhe qyteti shkojnë te CIS-i. Adresën dhe qytetin mund t'i ketë
edhe klienti i ruajtur më parë në fature.al, kështu që nuk ka nevojë t'i dërgoni në çdo
faturë. Kur mungon njëra, kërkesa refuzohet me `400` dhe `errors` thotë saktë çfarë duhet
plotësuar.

## Fusha që varen nga mënyra e pagesës

Dy fusha kërkohen vetëm për një mënyrë pagese, dhe refuzohen për çdo tjetër:

| `payment_method` | Fusha e detyrueshme | Kufiri |
| --- | --- | --- |
| `COMPANY` | `company_card` | Deri në 50 karaktere |
| `SVOUCHER` | `vouchers` | Deri në 20, në formën numër-vit-NIPT, pa përsëritje |

`company_card` me `BANKNOTE`, ose `vouchers` me `CARD`, refuzohen: nuk kanë vend në
dokumentin fiskal, prandaj nuk pranohen në heshtje.

## Zbritja

Zbritja mbi të gjithë faturën dërgohet me `invoice_discount_type` dhe `invoice_discount_value`
bashkë; zbritja e një rreshti me `lines[].discount`, si përqindje mbi çmimin e njësisë, me
`price` të plotë dhe `total` tashmë të ulur. Të dyja mund të jenë në të njëjtën faturë, dhe
rregullat e plota janë te fushat e kërkesës.

## Vetëfaturimi paguhet nga arka

Me `self_issue_type` fatura i paguhet shitësit me para nga arka, ndaj arka duhet të ketë të
paktën sa totali i faturës, në monedhën e faturës. Kur nuk ka, fatura nuk ruhet dhe nuk
fiskalizohet: përgjigja vjen me HTTP 200, `status: false` dhe një `message` me gjendjen e arkës
dhe shumën e faturës. Bëni një hyrje në arkë dhe dërgojeni përsëri faturën me të njëjtin
`internalId`.

## Shembull: parapagim në recepsion

Një parapagim i paguar me para në dorë ose me kartë faturohet si shitje cash, për shumën e
marrë.

```json
{
  "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
    }
  ]
}
```

## Pas lëshimit

Përgjigja mban `iic`, `fic`, `tcrCode` dhe `pdf`. Kur CIS-i nuk arrihet, fatura ruhet dhe
`fic` është `null` derisa fiskalizimi të përfundojë vetë.

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, kur arka nuk mbulon një vetëfaturim, ose kur fatura refuzohet pas validimit nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
- `400` - Të dhëna të paplota ose të pavlefshme për fiskalizim. `errors` thotë saktë çfarë duhet plotësuar. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET /invoice/details/{internalId}`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `503` - Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.

---

### GET /invoice/details/{internalId}

**Summary:** Merr një faturë sipas internalId

Kthen rezultatin e lëshimit të faturës që ju e dërguat me këtë `internalId`: `id`, `number`,
`iic`, `fic`, kodet fiskale dhe `pdf`. Përdoreni për të lexuar gjendjen pas një timeout-i ose
pas një `409`, dhe për të parë nëse `fic` u plotësua pas një fiskalizimi të shtyrë.

Për blerësin, shumat dhe rreshtat përdorni `GET /invoice/{id}/details`.

Pranohet edhe `POST` në të njëjtën adresë, për integrimet që e thërrasin ashtu që nga fillimi.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `internalId` | path | yes | Identifikuesi juaj i faturës, i dërguar kur u lëshua. |

**Responses:**

- `200` - Rezultati i lëshimit të faturës me këtë `internalId`, i njëjti që ktheu lëshimi.
- `401`
- `404` - Asnjë faturë me këtë `internalId` në kompaninë tuaj.
- `422` - `internalId` është bosh.
- `500` - Gabim i papritur në server.

---

### POST /invoice/e-invoice

**Summary:** Lësho e-faturë

Lëshon një faturë elektronike drejt një biznesi: fiskalizohet te CIS-i dhe dërgohet në
platformën qendrore të e-faturave, e cila ia dorëzon blerësit si dokument UBL.

Përdoreni kur blerësi është biznes me NIPT dhe fatura duhet t'i mbërrijë elektronikisht. Për
një shitje me pagesë të mëvonshme që nuk shkon në platformën e e-faturave përdorni
`POST /invoice/noncash`.

## Blerësi

`client` është i detyrueshëm: `client.id` i tipit `NUIS` (ose `VAT` dhe `TAX` për një biznes
të huaj), `client.name`, dhe `client.address` me `client.city`, ose në kërkesë ose të ruajtura
më parë te klienti në fature.al. Kur mungon një e dhënë, kërkesa refuzohet me `400` dhe
`errors` thotë saktë çfarë duhet plotësuar. Çdo rresht kërkon `unit_code`.

## Lloji i dokumentit

`doc_type` është lloji i dokumentit dhe `process` profili i tij në UBL. Të dyja janë të
detyrueshme; për një faturë të zakonshme dërgoni `380` dhe `P1`. Validimi pranon edhe llojet
e tjera të dokumentit dhe profilet e standardit UBL, të listuara te fushat e kërkesës:

| Dokumenti | `doc_type` | `process` | Kërkon `original_invoice_iic` |
| --- | --- | --- | --- |
| Faturë shitjeje | `380` | `P1` | Jo |
| Notë krediti | `381` | `P9` | **Po** |
| Notë debiti | `383` | `P9` | **Po** |

Nota e kreditit dhe nota e debitit korrigjojnë një faturë tjetër: `original_invoice_iic` është
`iic`-ja që ju ktheu ajo faturë, shkon si BillingReference në dokumentin UBL dhe si referencë
korrigjimi te CIS-i, dhe pa të kërkesa refuzohet me `422`. Për të kthyer një faturë të plotë
përdorni anulimin, jo një notë krediti: ai e shënon origjinalin si të kthyer.

## Zbritja

Zbritja mbi të gjithë faturën dërgohet me `invoice_discount_type` dhe `invoice_discount_value`
bashkë; zbritja e një rreshti me `lines[].discount`, si përqindje mbi çmimin e njësisë, me
`price` të plotë dhe `total` tashmë të ulur. Të dyja mund të jenë në të njëjtën faturë, dhe
rregullat e plota janë te fushat e kërkesës. Në dokumentin UBL zbritja del si
AllowanceCharge, me një zë për çdo normë TVSH-je.

## Shembuj

### Parapagim nga një biznes

`doc_type` `386` është fatura e parapagimit dhe `process` `P4` profili i pagesës paraprake.
Faturohet shuma e marrë, me normën e TVSH-së së shërbimit që parapaguhet.

```json
{
  "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
    }
  ]
}
```

### Notë krediti

Rreshtat janë vetëm diferenca, me vlera pozitive.

```json
{
  "internalId": "NK-2026-0038",
  "doc_type": "381",
  "process": "P9",
  "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": "SLL-01",
      "unit": "ditë",
      "unit_code": "DAY",
      "quantity": 1,
      "price": 2000,
      "total": 2000,
      "vat": 20
    }
  ]
}
```

## Pas lëshimit

Përgjigja mban `iic`, `fic`, `eic` dhe `pdf`. Kur CIS-i nuk arrihet, fatura ruhet dhe `fic`
është `null` derisa fiskalizimi të përfundojë vetë. Kur platforma e e-faturave nuk arrihet
por fatura u fiskalizua, `eic` mungon derisa dërgimi të përsëritet.

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Kur fatura refuzohet pas validimit, nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
- `400` - Të dhëna të paplota ose të pavlefshme për fiskalizim. `errors` thotë saktë çfarë duhet plotësuar. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET /invoice/details/{internalId}`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `503` - Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.

---

### POST /invoice/noncash

**Summary:** Lësho faturë jo-cash

Lëshon një faturë me pagesë të mëvonshme: transfertë bankare, çek, kompensim, ose çdo pagesë
që nuk kryhet në arkë. Fiskalizohet te CIS-i, por nuk shkon në platformën e e-faturave; kur
blerësi duhet ta marrë elektronikisht, përdorni `POST /invoice/e-invoice`.

## Blerësi

`client` është i detyrueshëm: ose `client.internal_id` i një klienti të ruajtur në fature.al,
ose `client.name` me të dhënat e tjera; pa asnjërin kërkesa refuzohet me `422`. `client.address`
dhe `client.city` shkojnë te CIS-i, ndaj duhen ose në kërkesë ose të ruajtura më parë te
klienti; kur mungon njëra, kërkesa refuzohet me `400` dhe `errors` thotë saktë çfarë duhet
plotësuar.

## Llogaria bankare

Llogaria ku pritet pagesa shkruhet në faturë në një nga tri mënyrat:

| Fusha | Kuptimi |
| --- | --- |
| `bank_account` | Id-ja e një llogarie të ruajtur në fature.al |
| `bank_account_iban` | Llogaria gjendet me IBAN |
| `bankAccount` | Llogaria dërgohet e plotë dhe ruhet si llogari e kompanisë; një IBAN ekzistues ripërdoret |

## 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:

| `doc_type` | Dokumenti | Efekti |
| --- | --- | --- |
| Mungon, ose `380` | Faturë e zakonshme | Asnjë |
| `381` | Notë krediti | Ul vlerën që blerësi ju detyrohet |
| `383` | Notë debiti | Rrit vlerën që blerësi ju detyrohet |

Origjinali duhet të jetë faturë jo-cash e fiskalizuar, e paanuluar dhe ende e korrigjueshme.
Rreshtat që dërgoni janë rreshtat e korrigjimit, me vlera pozitive: drejtimin e përcakton
`doc_type`, jo shenja e numrave. Kur korrigjimet e mbulojnë të gjithë faturën, origjinali
shënohet si i kthyer. Për të kthyer një faturë të plotë përdorni anulimin, jo një notë
krediti.

## Zbritja dhe tarifa

Zbritja mbi të gjithë faturën dërgohet me `invoice_discount_type` dhe `invoice_discount_value`
bashkë; zbritja e një rreshti me `lines[].discount`, si përqindje mbi çmimin e njësisë, me
`price` të plotë dhe `total` tashmë të ulur. Rregullat e plota janë te fushat e kërkesës.
Tarifa `fee` mbetet jashtë zbritjes: zbritet shuma e rreshtave, dhe tarifa i shtohet totalit
të ulur.

## Shembuj

### Notë krediti

Rreshtat janë vetëm diferenca, me vlera pozitive.

```json
{
  "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
    }
  ]
}
```

### Notë debiti

```json
{
  "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
    }
  ]
}
```

### Parapagim me transfertë

Një parapagim nuk ka lloj të veçantë te CIS-i: faturohet si shitje, për shumën e marrë. API-ja
nuk e lidh me faturën përfundimtare dhe nuk e zbret prej saj.

```json
{
  "internalId": "DEP-2026-0033",
  "payment_method": "TRANSFER",
  "client": {
    "name": "Arben Hoxha"
  },
  "notes": "Parapagim për rezervimin R-88215",
  "lines": [
    {
      "product_name": "Parapagim rezervimi R-88215",
      "product_code": "DEP-REZ",
      "unit": "copë",
      "quantity": 1,
      "price": 20000,
      "total": 20000,
      "vat": 6
    }
  ]
}
```

## Pas lëshimit

Përgjigja mban `iic`, `fic` dhe `pdf`. Kur CIS-i nuk arrihet, fatura ruhet dhe `fic` është
`null` derisa fiskalizimi të përfundojë vetë.

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Kur fatura refuzohet pas validimit, nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
- `400` - Të dhëna të paplota ose të pavlefshme për fiskalizim. `errors` thotë saktë çfarë duhet plotësuar. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET /invoice/details/{internalId}`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `503` - Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.

---

### POST /invoice/order

**Summary:** Lësho faturë porosi

Regjistron konsumin që ka nisur pa e mbyllur pagesën, si tavolina e një restoranti. Punon në
çift me faturën përmbledhëse: porosia hap tavolinën, përmbledhësja e paguan. Lëshohet nga
TCR-ja e përdoruesit, si një faturë cash.

- Mos dërgoni `payment_method`: vendoset vetë `ORDER`.
- Ruani `iic`-në që ju kthehet: me të mbyllet porosia te `POST /invoice/summary`.
- Një tavolinë mund të ketë disa porosi të hapura njëherësh.
- Zbritja mbi të gjithë faturën nuk pranohet këtu; ajo vendoset te përmbledhësja, e cila i
  kopjon rreshtat nga porositë. Zbritja e rreshtit, `lines[].discount`, ruhet mbi rreshtin e
  porosisë dhe kalon te përmbledhësja, kështu që tavolina paguan saktësisht sa tregoi porosia.

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, ose kur porosia refuzohet pas validimit nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
- `400` - Të dhëna të paplota ose të pavlefshme për fiskalizim. `errors` thotë saktë çfarë duhet plotësuar. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET /invoice/details/{internalId}`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `503` - Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.

---

### GET /invoice/print-eic/{eic}

**Summary:** Shkarko PDF-në e e-faturës sipas EIC

Kthen PDF-në zyrtare të e-faturës nga platforma e e-faturave, sipas kodit EIC që ju ktheu
lëshimi.

Çdo dështim kthehet me statusin e vet dhe me `message` në JSON, kurrë si PDF:

| Statusi | Kur |
| --- | --- |
| `404` | Platforma e e-faturave u përgjigj, por nuk ka dokument me këtë EIC. |
| `422` | Platforma e e-faturave e refuzoi kërkesën; `message` thotë pse. |
| `503` | Platforma e e-faturave nuk po përgjigjet. Provoni sërish pas `Retry-After` sekondash. |

Kur platforma nuk përgjigjet dhe EIC i përket një e-fature tuajës në fature.al, nuk kthehet
`503` por PDF-ja rezervë, e njëjta si te shkarkimi sipas id. Header-i `X-Document-Source`
thotë cilën morët: `official` nga platforma, `stored` kopja e ruajtur nga një shkarkim i
mëparshëm, `local` dokumenti i gjeneruar nga fature.al.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `eic` | path | yes | Kodi EIC i e-faturës, një UUID. |

**Responses:**

- `500`
- `200` - PDF-ja e e-faturës. `X-Document-Source` thotë nëse është ajo zyrtare (`official`), kopja e ruajtur (`stored`) apo dokumenti i fature.al (`local`).
- `503` - Platforma e e-faturave nuk po përgjigjet. Provoni sërish pas `Retry-After` sekondash.
- `401`
- `404` - Platforma e e-faturave nuk ka dokument me këtë EIC.
- `422` - Platforma e e-faturave e refuzoi kërkesën.

---

### GET /invoice/print/{id}

**Summary:** Shkarko dokumentin e faturës

Kthen dokumentin e faturës për t'ia dhënë blerësit ose për ta printuar. Pa parametra kthehet
formati i parazgjedhur i tipit: kupon termik për faturat cash (58 ose 80 mm, sipas
konfigurimit të përdoruesit), dokument A4 për faturat jo-cash dhe preventivët, dhe PDF-ja
zyrtare nga platforma e e-faturave për e-faturat.

Me parametrin `format` merrni të njëjtat versione që ofron edhe paneli i fature.al:

| `format` | Tipi i faturës | Rezultati | Content-Type |
| --- | --- | --- | --- |
| `a4` | Cash | Dokument A4 i faturës | application/pdf |
| `thermal` | Jo-cash | Kupon termik | application/pdf |
| `v2` | Jo-cash, preventiv | Dokument A4, versioni i gjerë | application/pdf |
| `receipt` | Preventiv | Kupon termik | application/pdf |
| `local` | E-faturë | Dokument A4 i gjeneruar nga fature.al, pa e kërkuar PDF-në zyrtare | application/pdf |
| `local-thermal` | E-faturë | Kupon termik i gjeneruar nga fature.al | application/pdf |
| `html` | Cash | Kuponi termik si HTML, për ta dërguar vetë në printer | text/html |
| `json` | Të gjitha | Të dhënat e dokumentit në JSON, për ta formatuar vetë faturën | application/json |

`lang` (`en`, `it`, `de`) e përkthen dokumentin A4 të faturave jo-cash, të preventivëve dhe të
e-faturave, dhe kombinohet me `format`. Pa të, dokumenti kthehet shqip. Kuponat termikë dhe
faturat cash mbeten gjithmonë shqip, sepse janë dokumente fiskale.

Për faturat cash, `copy_only=1` kthen kopjen e kuponit në vend të origjinalit.

Një `format` që nuk vlen për tipin e faturës nuk kthen gabim: kthehet formati i parazgjedhur i
atij tipi.

## E-faturat kur platforma nuk përgjigjet

PDF-ja zyrtare vjen nga platforma e e-faturave. Kur ajo nuk përgjigjet, nuk kthehet gabim:
kthehet kopja e ruajtur nga një shkarkim i mëparshëm, ose, kur nuk ka të tillë, dokumenti i
gjeneruar nga fature.al. Header-i `X-Document-Source` thotë cilën morët: `official`,
`stored` ose `local`.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e faturës në fature.al. |
| `copy_only` | query | no | Vetëm për faturat cash: kthen kopjen e kuponit në vend të origjinalit. |
| `format` | query | no | Versioni i dokumentit sipas tabelës më sipër: `a4`, `thermal`, `v2`, `receipt`, `local`, `local-thermal`, `html`, `json`. |
| `lang` | query | no | Gjuha e dokumentit A4: `en`, `it` ose `de`. Pa të dokumenti kthehet shqip. |

**Responses:**

- `500` - Dokumenti nuk u krijua dot. Problemi raportohet automatikisht.
- `200` - Tipi i përmbajtjes varet nga `format`: PDF si parazgjedhje, `text/html` me `format=html`, dhe dokumenti i faturës në JSON me `format=json`, gati për ta formatuar vetë.
- `401`
- `404` - Fatura nuk u gjet, ose nuk i përket kompanisë suaj, ose platforma e e-faturave nuk ka dokument për këtë e-faturë.
- `422` - Platforma e e-faturave e refuzoi kërkesën për PDF-në; `message` thotë pse.

---

### POST /invoice/summary

**Summary:** Lësho faturë përmbledhëse

Mbyll pagesën e një ose më shumë faturave porosi me një dokument të vetëm, të lëshuar nga
TCR-ja e përdoruesit.

- `order_invoices` mban `iic`-të e porosive që po mbyllen, të paktën një. Duhet të jenë fatura
  porosi të kësaj kompanie, ende të pambyllura; ndryshe kërkesa refuzohet me `400` dhe
  `errors` thotë cila.
- Rreshtat nuk dërgohen: merren nga vetë porositë, me zbritjet e tyre.
- `payment_method` pranon vetëm `BANKNOTE` ose `CARD`.
- Zbritja e tavolinës vendoset këtu, me `invoice_discount_type` dhe `invoice_discount_value`.

Përgjigja i liston porositë e mbyllura te `settledOrderInvoices`.

**Tags:** Faturat

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi nuk ka pajisje fiskale, ose kur fatura refuzohet pas validimit nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
- `400` - Një porosi nuk u gjet, nuk është faturë porosi, ose është mbyllur tashmë; ose të dhënat janë të paplota për fiskalizim. `errors` thotë saktë cila. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET /invoice/details/{internalId}`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `503` - Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.

---

### GET /invoice/wtn

**Summary:** Listo fletët shoqëruese

Kthen fletët shoqëruese të kompanisë, nga më e reja te më e vjetra, me filtrim sipas datës së
krijimit. Çdo fletë vjen e plotë, me `origin`, `destination`, `carrier`, `fiscal` dhe `lines`,
kështu që për rreshtat nuk duhet një thirrje e dytë.

- Pagination me `limit` dhe `offset`. `pagination` nuk kthen `total`, ndaj ndaloni kur një faqe
  vjen më e shkurtër se `limit`.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`. Vendi lirohet sapo kthehet përgjigja, ose pas 30 sekondash nëse kërkesa u ndërpre.

`fiscal.status` është `FISCALIZED` ose `UNFISCALIZED`, dhe `print` është adresa e të dhënave
për printim të fletës.

**Tags:** Fletët shoqëruese

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Sa fletë të kthehen në një faqe. |
| `offset` | query | no | Nga cila fletë të fillohet, duke numëruar nga 0. |
| `fromDate` | query | no | Data e fillimit, `YYYY-MM-DD`, sipas datës së krijimit. |
| `toDate` | query | no | Data e mbarimit, `YYYY-MM-DD`. |

**Responses:**

- `200` - Lista e fletëve të periudhës, me `pagination`; `items` është bosh kur nuk ka fletë.
- `401`
- `422` - Datat nuk janë në formatin `YYYY-MM-DD`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### POST /invoice/wtn

**Summary:** Lësho fletë shoqëruese

Lëshon një fletë shoqëruese (WTN) dhe e fiskalizon te CIS-i. Fleta nuk është shitje: shoqëron
mallin që lëviz nga një pikë në tjetrën, dhe ligji e kërkon edhe kur asgjë nuk shitet.

Rreshtat dërgohen si `invoice_lines`, jo `lines` si te faturat, dhe çdo rresht ka
`product_name`, `product_code`, `unit` dhe `quantity`.

## Fushat e detyrueshme

- `vehPlates`, targa e automjetit;
- `valueOfGoods`, vlera e mallit që udhëton;
- `invoice_lines`, të paktën një rresht.

## Vlerat e lejuara

| Fusha | Vlerat | Parazgjedhja |
| --- | --- | --- |
| `type` | `WTN`, `SALE` | `WTN` |
| `transaction` | `TRANSFER`, `EXAMINATION`, `SALES`, `DOOR` | `TRANSFER` |
| `vehOwnership` | `OWNER`, `THIRDPARTY` | `OWNER` |
| `startPoint`, `destinPoint` | `ANOTHER`, `CUSTOMS`, `EXHIBITION`, `OTHER`, `SALE`, `STORE`, `WAREHOUSE` | `WAREHOUSE`, `STORE` |
| `carrier_id_type` | `NUIS`, `ID` | `NUIS` |

Adresat e nisjes dhe të mbërritjes (`startCity`, `startAddr`, `destinCity`, `destinAddr`) dhe
transportuesi (`carrier_name`, `carrier_id_num`, `carrier_town`, `carrier_address`) merren nga
njësia dhe kompania juaj kur nuk dërgohen. `startDateTime` dhe `destinDateTime` marrin kohën e
lëshimit kur mungojnë.

## Pas lëshimit

Përgjigja mban `id`, `number`, `iic`, `fic`, `fiscalStatus`, `verifyURL` dhe `print`. Ruani
`id`-në dhe `iic`-në. Kur CIS-i nuk arrihet, fleta ruhet e pafiskalizuar, me
`fic: null` dhe `fiscalStatus: UNFISCALIZED`; fiskalizimi kryhet më vonë nga paneli i
fature.al, dhe gjendjen e lexoni te `fiscal.status` me `GET /invoice/wtn/{id}/details`. Kur
CIS-i e refuzon fletën, ajo nuk ruhet dhe përgjigja është `500` me arsyen te `message`.

Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
`429`. Vendi lirohet sapo kthehet përgjigja, ose pas 30 sekondash nëse kërkesa u ndërpre.

**Tags:** Fletët shoqëruese

**Request body content types:** application/json

**Responses:**

- `200` - Kur CIS-i nuk arrihet, fleta ruhet e pafiskalizuar: përgjigja mban `invoice` me `fic: null` dhe `fiscalStatus: UNFISCALIZED`, dhe fiskalizimi kryhet më vonë.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server, ose CIS-i e refuzoi fletën; arsyeja është te `message`. Fleta nuk u ruajt.

---

### GET /invoice/wtn/print/{id}

**Summary:** Merr fletën shoqëruese për printim

Kthen të dhënat e fletës si JSON të gatshëm për dokument, jo si PDF: kompaninë me logon,
transportuesin, nisjen dhe mbërritjen, dhe te `invoice` numrin, kodet fiskale, rreshtat,
`amounts` dhe `verifyUrl`.

Përdoreni kur e formatoni vetë dokumentin, në sistemin tuaj të printimit. Adresa e këtij
endpoint-i vjen te fusha `print` e listës dhe e detajeve.

**Tags:** Fletët shoqëruese

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e fletës shoqëruese në fature.al. |

**Responses:**

- `200` - Dokumenti i fletës në JSON, gati për ta formatuar vetë: kompania me logon, transportuesi, nisja, mbërritja dhe `invoice` me rreshtat dhe kodet fiskale.
- `401`
- `404` - Fleta nuk u gjet, ose nuk i përket kompanisë suaj.

---

### GET /invoice/wtn/{id}/details

**Summary:** Merr një fletë shoqëruese sipas id

Kthen fletën e plotë sipas `id`-së së saj në fature.al: automjetin, pikën e nisjes dhe të
mbërritjes, transportuesin, kodet fiskale dhe rreshtat e mallit. Është i njëjti objekt që kthen
lista.

**Tags:** Fletët shoqëruese

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e fletës shoqëruese në fature.al. |

**Responses:**

- `200` - Fleta e plotë te `invoice`: pikat e nisjes dhe të mbërritjes, transportuesi, kodet fiskale dhe rreshtat e mallit.
- `401`
- `404` - Fleta nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server.

---

### GET /invoice/{id}/details

**Summary:** Merr një faturë sipas id

Kthen faturën e plotë sipas `id`-së së saj në fature.al: blerësin, shumat, pagesën, kodet
fiskale dhe rreshtat.

Kur fatura nuk gjendet, ose nuk i përket kompanisë suaj, `data.invoice` është `null` me
statusin `200`. Për ta gjetur me numrin tuaj përdorni `GET /invoice/details/{internalId}`.

**Tags:** Faturat

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e faturës në fature.al. |

**Responses:**

- `200` - Fatura e plotë te `data.invoice`, ose `null` kur nuk gjendet.
- `401`
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### POST /on-boarding/bank-account

**Summary:** Krijo një llogari bankare

Ruan një llogari bankare të kompanisë. Llogaria shkruhet në faturat jo-cash dhe në e-faturat
si vendi ku pritet pagesa, prandaj duhet para faturës së parë jo-cash.

- `iban` dhe `currency` (kodi i monedhës, p.sh. `ALL`) janë ato që përcaktojnë llogarinë;
  `name`, `holder`, `swift` dhe `notes` janë përshkruese.
- Hapësirat në `iban` hiqen dhe shkronjat bëhen të mëdha para ruajtjes.
- Një IBAN që kompania e ka tashmë nuk krijon llogari të dytë: kthehet ajo ekzistuese.
- Një monedhë që nuk njihet refuzohet me `200` dhe `status: false`.

Ruani `id`-në që kthehet: me të, ose me IBAN-in, zgjidhet llogaria në faturat jo-cash dhe në
e-faturat.

**Tags:** Regjistrimi i kompanive

**Request body content types:** application/json

**Responses:**

- `200` - Kur monedha nuk njihet, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

---

### POST /on-boarding/branch

**Summary:** Krijo një njësi biznesi

Krijon një njësi biznesi të re për kompaninë. Përdoret kur kompania ka më shumë se një pikë
shitjeje: njësinë e parë e krijon vetë `POST /register`, dhe asaj i vendosni vetëm kodin me
`POST /on-boarding/branch/{id}`.

- `name`, `type`, `administrator` dhe `address` janë të detyrueshme.
- `type` është `main` për selinë qendrore ose `secondary` për një njësi dytësore. Kompania ka
  një seli të vetme, prandaj `main` refuzohet me `409` kur ajo ekziston tashmë.
- Numri i njësive varet nga abonimi; kur kufiri është arritur, kërkesa refuzohet me `403`.
- `businessUnitCode` mund të dërgohet tani ose më vonë me `POST /on-boarding/branch/{id}`, por
  pa të njësia nuk lëshon fatura.

Ruani `id`-në që kthehet: me të lidhen përdoruesit dhe pajisjet fiskale të njësisë.

**Tags:** Regjistrimi i kompanive

**Request body content types:** application/json

**Responses:**

- `200` - Kur ruajtja dështon për një arsye tjetër, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Kompania ka tashmë një seli qendrore.

---

### POST /on-boarding/branch/{id}

**Summary:** Përditëso një njësi biznesi

Vendos ose ndryshon emrin, adresën, administratorin dhe kodin e një njësie biznesi. Hapi i
zakonshëm është `businessUnitCode`, kodi i njësisë që merret nga self-care: pa të njësia nuk
lëshon fatura.

- `name`, `businessUnitCode`, `administrator` dhe `address` janë të gjitha opsionale; fusha
  që nuk dërgohet mbetet siç është.
- Body nuk validohet veçmas, prandaj nuk ka përgjigje `422`.

Një njësi që nuk gjendet, ose nuk i përket kompanisë suaj, kthehet me `200` dhe
`status: false`.

**Tags:** Regjistrimi i kompanive

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e njësisë së biznesit. |

**Request body content types:** application/json

**Responses:**

- `200` - Kur njësia nuk gjendet, nuk i përket kompanisë suaj, ose ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`

---

### POST /on-boarding/certificate

**Summary:** Ngarko certifikatën elektronike

Ngarkon certifikatën elektronike të kompanisë (`.p12` ose `.pfx`) bashkë me fjalëkalimin e saj.
Me të nënshkruhet çdo dokument që shkon te CIS-i, prandaj është hapi i parë pas regjistrimit.

- `certificate_file` është skedari i certifikatës dhe `password` fjalëkalimi i saj.
- Fjalëkalimi duhet ta hapë certifikatën.
- NIPT-i brenda certifikatës duhet të përputhet me NIPT-in e kompanisë.

Përgjigja kthen `expiresAt`, datën e skadimit të certifikatës. Ruajeni: pas asaj date
fiskalizimi ndalon derisa të ngarkohet një certifikatë e re.

Në sandbox pranohet çdo certifikatë dhe çdo fjalëkalim, dhe `expiresAt` është një vit nga sot.

**Tags:** Regjistrimi i kompanive

**Request body content types:** multipart/form-data

**Responses:**

- `200` - Kur fjalëkalimi është i gabuar, kur NIPT-i i certifikatës nuk përputhet me kompaninë, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

---

### POST /on-boarding/fiscal-device

**Summary:** Regjistro një pajisje fiskale

Regjistron një pajisje fiskale (TCR) te CIS-i për një njësi biznesi dhe kthen kodin e saj.
Duhet vetëm për fatura cash; faturat jo-cash dhe e-faturat nuk kanë TCR.

- Bëhet pasi certifikata është ngarkuar dhe njësia ka `businessUnitCode`; pa to CIS-i e
  refuzon regjistrimin.
- `branchId`, `name` dhe `fromDate` (`YYYY-MM-DD`) janë të detyrueshme. `toDate` mbyll
  pajisjen në atë datë; pa të pajisja mbetet aktive pa afat.
- Kur njësia ka arritur numrin e pajisjeve aktive që i lejohet, kërkesa refuzohet me `403`.

Ruani `fiscalTcrCode` dhe vendoseni te përdoruesi që do të lëshojë fatura cash, me
`POST /on-boarding/user/{id}`.

Kur CIS-i e refuzon regjistrimin, pajisja nuk ruhet dhe përgjigja kthehet me `200` dhe
`status: false`. Kur CIS-i nuk arrihet, pajisja gjithashtu nuk ruhet, por përgjigja kthehet
me `status: true` dhe `fiscalTcrCode: null`: kontrolloni vlerën, jo vetëm `status`, dhe
riprovoni më vonë.

**Tags:** Regjistrimi i kompanive

**Request body content types:** application/json

**Responses:**

- `200` - Kur CIS-i e refuzon regjistrimin, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`. Kur CIS-i nuk arrihet, `status` është `true` dhe `fiscalTcrCode` është `null`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.

---

### POST /on-boarding/user

**Summary:** Krijo një përdorues

Krijon një përdorues operator të kompanisë dhe kthen token-in e tij. Çdo person që lëshon
fatura ka përdoruesin e vet, sepse kodi i operatorit dhe pajisja fiskale janë të përdoruesit.

- `email` është i detyrueshëm dhe unik në gjithë fature.al, jo vetëm brenda kompanisë.
- `branchId` duhet të jetë njësi e kompanisë suaj.
- `operatorCode` merret nga self-care. Për fatura cash dërgoni edhe `fiscalTcrCode`, kodin që
  ktheu `POST /on-boarding/fiscal-device`; një kod që nuk gjendet e lë përdoruesin pa pajisje,
  pa gabim.
- `name` dhe `phone` janë opsionale.
- Body nuk validohet veçmas, prandaj çdo refuzim vjen me `200` dhe `status: false`.

Ruani `token`-in: kthehet vetëm një herë dhe është ai me të cilin ky përdorues thërret API-në.

**Tags:** Regjistrimi i kompanive

**Request body content types:** application/json

**Responses:**

- `200` - Kur `email` mungon ose është në përdorim, kur njësia nuk gjendet, ose kur ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`

---

### POST /on-boarding/user/{id}

**Summary:** Përditëso një përdorues

Vendos emrin, njësinë, kodin e operatorit dhe pajisjen fiskale të një përdoruesi. Këtu lidhet
përdoruesi i parë, ai që krijoi `POST /register`, me `operatorCode` dhe, për fatura cash, me
`fiscalTcrCode`.

- `operatorCode` është kodi i operatorit që merret nga self-care; pa të përdoruesi nuk lëshon
  fatura.
- `fiscalTcrCode` është kodi që ktheu `POST /on-boarding/fiscal-device` dhe duhet dërguar në
  çdo thirrje: pa të, ose me një kod që nuk gjendet mes pajisjeve të kompanisë, përdoruesi
  mbetet pa pajisje fiskale, pa gabim.
- `branchId` duhet të jetë njësi e kompanisë suaj; ndryshe kërkesa refuzohet me `200` dhe
  `status: false`.
- `name`, `branchId` dhe `operatorCode` që nuk dërgohen mbeten siç janë.
- Body nuk validohet veçmas, prandaj nuk ka përgjigje `422`.

**Tags:** Regjistrimi i kompanive

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e përdoruesit. |

**Request body content types:** application/json

**Responses:**

- `200` - Kur përdoruesi ose njësia nuk gjendet, ose ruajtja dështon, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message` ose te `errors`.
- `401`

---

### GET /ping

**Summary:** Provo lidhjen

Kthen kohën e serverit dhe adresat IP me të cilat kërkesa mbërriti. Nuk lexon dhe nuk ndryshon
asgjë në llogari.

Përdoreni për të provuar adresën bazë dhe token-in para thirrjes së parë të vërtetë, dhe për
të parë me cilën IP mbërrini kur konfiguroni një listë IP-sh të lejuara. Për të parë me cilin
biznes punon token-i thirrni `GET /account`.

- `pong` është Unix timestamp në sekonda.
- `ip` është lista e adresave IP të kërkesës, siç i sheh serveri.

Një `401` do të thotë që token-i nuk po arrin: kontrolloni header-in `Authorization`.

**Tags:** Ping

**Responses:**

- `200` - Koha e serverit te `pong` dhe adresat IP të kërkesës te `ip`.
- `401`

---

### GET /product/categories

**Summary:** Listo kategoritë e produkteve

Kthen të gjitha kategoritë e produkteve të kompanisë në një përgjigje të vetme, pa pagination,
secila me `id`, `name` dhe `color`.

Përdoreni për të marrë `id`-në që dërgoni si `id_category` kur filtroni `GET /products` ose
kur krijoni një produkt. Lista ndryshon rrallë, ndaj mbajeni në cache.

Ky endpoint nuk kthen `429` as `500`. Një kërkesë e dytë nga i njëjti token, ndërsa e para
nuk ka mbaruar, si dhe çdo gabim i papritur, kthehen me HTTP 200 dhe `status: false`; arsyeja
është te `message`. Lexoni `status`, jo vetëm kodin HTTP.

**Tags:** Produktet

**Responses:**

- `200` - Kategoritë e kompanisë te `data`, bosh kur nuk ka; ose `status: false` me arsyen te `message`.
- `401`

---

### GET /products

**Summary:** Listo produktet

Kthen produktet dhe shërbimet e kompanisë që janë për shitje, sipas `id` në rritje, me filtrim
sipas tekstit, kategorisë dhe llojit. Produktet e fshira dhe ato që nuk shiten nuk dalin.

Përdoreni për të ndërtuar një arkë ose një katalog, ose për të gjetur `id`-në e një produkti.
Çdo produkt vjen me kodin, emrin, njësinë, çmimet, normën e TVSH-së dhe `id_category`; për
objektin e kategorisë dhe për `service` thirrni `GET /products/{id}/details`.

- `query` kërkon me përputhje të pjesshme në emër, kod dhe përshkrim.
- `id_category` mban vetëm produktet e një kategorie; `service` `true` vetëm shërbimet,
  `false` vetëm artikujt e inventarit.
- Pagination me `limit` dhe `offset`. `limit` kufizohet në `500`; një vlerë më e madhe ulet pa
  gabim. Pa `limit` kthehet i gjithë katalogu, `pagination.limit` është `null` dhe `offset`
  nuk merret parasysh.
- `pagination` kthen `total`, ndaj vazhdoni me `offset += limit` derisa `offset` të arrijë
  `total`.

Ndryshe nga listat e tjera, `data` është vetë lista e produkteve dhe `pagination` qëndron
pranë saj, jo brenda saj.

Ky endpoint nuk kthen `429` as `500`. Një kërkesë e dytë nga i njëjti token, ndërsa e para
nuk ka mbaruar, si dhe çdo gabim i papritur, kthehen me HTTP 200 dhe `status: false`; arsyeja
është te `message`. Lexoni `status`, jo vetëm kodin HTTP.

**Tags:** Produktet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `query` | query | no | Kërkim në emrin, kodin ose përshkrimin e produktit. |
| `id_category` | query | no | Vetëm produktet e kësaj kategorie, sipas `id` nga `GET /product/categories`. |
| `limit` | query | no | Sa produkte të kthehen në një faqe, deri në 500. Pa të kthehet i gjithë katalogu. |
| `offset` | query | no | Nga cili produkt të fillohet, duke numëruar nga 0. Zbatohet vetëm bashkë me `limit`. |
| `service` | query | no | `true` kthen vetëm shërbimet, `false` vetëm artikujt e inventarit. Pa të kthehen të dyja. |

**Responses:**

- `200` - Produktet e faqes te `data`, me `pagination` pranë saj; ose `status: false` me arsyen te `message`.
- `401`

---

### POST /products

**Summary:** Krijo një produkt

Krijon një produkt ose shërbim të ri në katalogun e kompanisë dhe kthen `id`-në e tij.

Përdoreni kur mbani katalogun në sistemin tuaj dhe doni që produkti të dalë edhe në fature.al.

- `name` është unik brenda kompanisë; një produkt i dytë me të njëjtin emër refuzohet me
  `409`.
- `code` gjenerohet vetë kur nuk e dërgoni; ruani atë që ju kthehet.
- `unit` nuk dërgohet: njësia derivohet nga `unit_code`, kodi që mban dokumenti fiskal.
- `vat_rate` pranon `0`, `6`, `10` ose `20`; për një produkt të përjashtuar dërgoni edhe
  `vat_exempt_type`.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

Produkti del menjëherë në `GET /products`. Ruani `id`-në e kthyer për detajet dhe
përditësimin.

**Tags:** Produktet

**Request body content types:** application/json

**Responses:**

- `200` - Produkti i sapokrijuar te `product`, me `id`-në dhe kodin e tij.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `409` - Ekziston tashmë një produkt me këtë emër.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### PUT /products/{id}

**Summary:** Përditëso një produkt

Përditëson një produkt ekzistues dhe kthen të dhënat e tij pas ndryshimit.

Body i kërkesës ka të njëjtin format dhe të njëjtat fusha të detyrueshme si `POST /products`,
me të njëjtat rregulla për `unit_code` dhe `vat_rate`.

- Emri ose kodi i ri nuk mund të përkojë me atë të një produkti tjetër; refuzohet me `409`.
- Ndryshimi i çmimit nuk prek faturat e lëshuara: ato mbajnë çmimin me të cilin u shitën.
- Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me
  `429`.

**Tags:** Produktet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e produktit në fature.al. |

**Request body content types:** application/json

**Responses:**

- `200` - Produkti pas ndryshimit te `product`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
- `404` - Produkti nuk u gjet, ose nuk i përket kompanisë suaj.
- `409` - Ekziston tashmë një produkt tjetër me këtë emër ose me këtë kod.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### GET /products/{id}/details

**Summary:** Merr një produkt sipas id

Kthen një produkt të vetëm me të gjitha fushat: kodin, emrin, njësinë me kodin e saj fiskal,
çmimet, normën e TVSH-së me llojin e përjashtimit, `service` dhe kategorinë si objekt.

Përdoreni kur keni `id`-në nga lista ose nga krijimi dhe ju duhen fushat që lista nuk i
mban.

**Tags:** Produktet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e produktit në fature.al. |

**Responses:**

- `200` - Produkti i kërkuar te `product`, me të gjitha fushat.
- `401`
- `404` - Produkti nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server.

---

### GET /purchase-invoices

**Summary:** Listo faturat e blerjes

Kthen faturat që furnitorët i kanë lëshuar kompanisë suaj, të lexuara nga CIS-i. Furnitori nuk
ju dërgon gjë: dokumentet merren nga sistemi qendror i fiskalizimit, secila me të dhënat e
plota, shitësin, blerësin, artikujt, TVSH-në dhe mënyrat e pagesës.

Përdoreni për rakordimin e blerjeve dhe të TVSH-së së zbritshme pa asnjë hap manual.

- Pagination me `page`, që fillon nga `1`, jo me `limit` dhe `offset`, sepse lista vjen nga
  CIS-i dhe jo nga fature.al. Përsëritni me `page + 1` sa kohë `pagination.hasMore` është `true`.
- Mos u ndalni te një `items` bosh. Një dokument që nuk arrihet për detaje hiqet nga `items` pa
  gabim, prandaj një faqe mund të vijë bosh edhe kur pas saj ka të tjera.
- Periudha përfshin të dyja ditët, nga ora 00:00:00 e `fromDate` deri në 23:59:59 të `toDate`,
  sipas orës së Shqipërisë.
- Data që mungon merr ditën e sotme, prandaj pa asnjërën lexohet vetëm sot. Për një periudhë të
  kaluar dërgoni të dyja: vetëm një `toDate` e kaluar e nis periudhën sot, pas mbarimit të saj,
  dhe nuk kthen faturat e asaj periudhe.
- `fic` kërkon brenda periudhës, jo në gjithë historinë. Dërgojeni bashkë me një `fromDate` dhe
  `toDate` që përfshijnë datën e faturës, ndryshe kërkohet vetëm te faturat e sotme.
- Një faqe kushton një thirrje te CIS-i për listën dhe një për çdo faturë në të. Detajet e çdo
  fature ruhen në cache për një orë, dhe endpoint-i ka kufirin fiskal të kërkesave.

Ruani `iic` dhe `fic`: me to fatura gjendet përsëri, dhe `fic` shërben edhe si filtër këtu.

**Tags:** Faturat e blerjes

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `page` | query | no | Faqja e listës nga CIS-i, duke filluar nga 1. Një vlerë më e vogël se 1 ose jo numër lexohet si 1. Përsëritni me `page + 1` sa kohë `pagination.hasMore` është `true`. |
| `fromDate` | query | no | Data e fillimit, `YYYY-MM-DD`, e përfshirë. Pa të merret dita e sotme. |
| `toDate` | query | no | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. Pa të merret dita e sotme. |
| `fic` | query | no | Kthe vetëm faturën me këtë FIC, nëse është brenda periudhës. |

**Responses:**

- `200` - Faturat e blerjes të faqes te `items`, secila e plotë, me `pagination`.
- `401` - Token-i mungon ose nuk është i vlefshëm, ose përdoruesi nuk ka të drejtën e faturave të blerjes.
- `422` - Datat nuk janë në formatin `YYYY-MM-DD`.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.
- `502` - CIS-i u përgjigj me një gabim; arsyeja është te `message`.
- `503` - Shërbimi i fiskalizimit nuk u arrit. Riprovoni më vonë. `message` vjen bosh; arsyeja është te `errors`.

---

### GET /register

**Summary:** Kontrollo aksesin në regjistrim

Kthen `pong` kur llogaria e token-it lejohet të regjistrojë kompani. Thirreni para hapit të
parë, që të dini nëse grupi është hapur për ju.

Grupi është i mbyllur si parazgjedhje dhe hapet me kërkesë, ose për token-in e një operatori
të vetëm, ose për të gjithë operatorët e kompanisë suaj.

**Tags:** Regjistrimi i kompanive

**Responses:**

- `200` - Kur llogaria juaj nuk është e autorizuar për regjistrim, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`

---

### POST /register

**Summary:** Regjistro një kompani

Krijon një kompani të re në fature.al, me përdoruesin e parë, njësinë e parë të biznesit,
klientin e rastit, monedhat dhe një abonim aktiv. Është hapi i parë i regjistrimit; hapat e
tjerë thirren me token-in që kthen.

Përdoreni vetëm për biznese që nuk janë ende në fature.al. Për një kompani ekzistuese
përdorni drejtpërdrejt endpoint-et `POST /on-boarding/*` me token-in e saj.

- Llogaria e token-it duhet të jetë e autorizuar për regjistrim; ndryshe kërkesa refuzohet
  me `200` dhe `status: false`.
- `nuis` duhet të jetë një NIPT i paregjistruar në fature.al dhe i njohur nga administrata
  tatimore. Shkronjat e vogla pranohen dhe kthehen në të mëdha.
- `email` bëhet email-i dhe emri i përdoruesit të parë, ndaj duhet të jetë i papërdorur në
  fature.al.
- `lastNonCashEInvoiceNumber` vendos numrin nga i cili vazhdon numërimi i faturave jo-cash
  dhe i e-faturave për vitin aktual.

Përgjigja mban `user.token`, token-in API të përdoruesit të parë, dhe `branch.id`, id-në e
njësisë së biznesit. Ruajini të dyja: token-i shfaqet vetëm këtu dhe përdoret për të gjithë
hapat e tjerë, kurse id-ja e njësisë duhet te `POST /on-boarding/branch/{id}`,
`POST /on-boarding/user` dhe `POST /on-boarding/fiscal-device`.

## Sandbox

Në sandbox, NIPT-i `L62221018T` kalon në një rrjedhë prove: nuk krijohet kompani e re, por
një përdorues dhe një njësi biznesi nën kompaninë sandbox, dhe `user.token` është një token
real për hapat e tjerë. Email-it i shtohet prapashtesa `+sandbox-XXXXXXXX`, kështu që të
njëjtin email mund ta dërgoni sa herë të doni. Në live ky NIPT trajtohet si çdo NIPT tjetër.

**Tags:** Regjistrimi i kompanive

**Request body content types:** application/json

**Responses:**

- `200` - Kur llogaria nuk është e autorizuar për regjistrim, kur NIPT-i është i regjistruar tashmë ose nuk gjendet te administrata tatimore, ose kur email-i është në përdorim, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
- `401`
- `422` - Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

---

### GET /reports/by-operator

**Summary:** Merr shitjet sipas operatorit

Sa fatura lëshoi dhe sa vlerë bëri secili operator në periudhë, me `operator_code` përbri
emrit.

Përdoreni për krahasim mes turneve ose për shpërblime sipas shitjes.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |

**Responses:**

- `200` - Operatorët e periudhës te `items`, nga vlera bruto më e madhe; `items` është bosh kur periudha nuk ka shitje.
- `401`
- `422` - `from` ose `to` mungon, ose nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/by-tcr

**Summary:** Merr shitjet sipas pajisjes fiskale

Sa fatura lëshoi dhe sa vlerë bëri secila pajisje fiskale (TCR) në periudhë.

Një biznes me disa njësi e përdor për të ndarë shitjet sipas pikës së shitjes, sepse çdo TCR i
përket një njësie të vetme.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |

**Responses:**

- `200` - Pajisjet fiskale të periudhës te `items`, nga vlera bruto më e madhe; `items` është bosh kur periudha nuk ka fatura cash.
- `401`
- `422` - `from` ose `to` mungon, ose nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/cash-register

**Summary:** Merr gjendjen e arkës për një ditë

Gjendja e arkës fiskale të përdoruesit për një ditë të vetme: hapja, mbyllja dhe mbyllja e
pritur, bashkë me shitjet sipas mënyrës së pagesës dhe lëvizjet e parave.

Mbyllja e pritur, `expected_closing`, është ajo që duhet të ketë arka po të jetë regjistruar
gjithçka. Diferenca me mbylljen reale është pikërisht ajo që kërkohet në rakordim.

- Pa `date` merret dita e sotme. Formati është `YYYY-MM-DD`.
- Raporti i përket pajisjes fiskale të përdoruesit të token-it. Pa pajisje fiskale, ose kur
  monedha ALL nuk është e konfiguruar, arka nuk është e disponueshme dhe përgjigja kthehet me
  `200` dhe `status: false`.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `date` | query | no | Dita e raportit, `YYYY-MM-DD`. Pa të merret sot. |

**Responses:**

- `200` - Gjendja e arkës së ditës te `data`, me `sales_by_method` dhe `movements`; pa pajisje fiskale, ose kur monedha ALL nuk është e konfiguruar, përgjigja kthehet me HTTP 200 dhe `status: false`, me arsyen te `errors`.
- `401`
- `422` - `date` nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### GET /reports/cash-register/closing

**Summary:** Merr raportin e mbylljes së arkës

Raporti i fundit i ditës, ai që printohet kur mbyllet turni: totalet e shitjeve, produktet e
shitura dhe lëvizjet e parave, me `opened_at` dhe `closed_at` të turnit.

Ndryshimi nga gjendja e arkës është fokusi: ky raport i përket turnit që u mbyll, jo ditës si
periudhë.

- Pa `date` merret dita e sotme. Formati është `YYYY-MM-DD`.
- Raporti i përket pajisjes fiskale të përdoruesit të token-it. Pa pajisje fiskale, ose kur
  monedha ALL nuk është e konfiguruar, arka nuk është e disponueshme dhe përgjigja kthehet me
  `200` dhe `status: false`.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `date` | query | no | Dita e raportit, `YYYY-MM-DD`. Pa të merret sot. |

**Responses:**

- `200` - Raporti i mbylljes së turnit te `data`, me `sales`, `sales_by_method`, `products_sold` dhe `movements`; pa pajisje fiskale, ose kur monedha ALL nuk është e konfiguruar, përgjigja kthehet me HTTP 200 dhe `status: false`, me arsyen te `errors`.
- `401`
- `422` - `date` nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
- `500` - Gabim i papritur në server.

---

### GET /reports/daily-trend

**Summary:** Merr ecurinë ditore

Një pikë për çdo ditë të periudhës, gati për një grafik.

| `metric` | Çfarë mat pika |
| --- | --- |
| `gross` | Vlera bruto e shitjeve, parazgjedhja |
| `count` | Numri i faturave |

Ditët pa shitje kthehen me vlerë `0` dhe nuk hiqen nga seria, kështu që grafiku nuk
shtrembërohet. Çdo pikë mban `date`, `count` dhe `gross`, dhe `metric` kthehet e konfirmuar.

Me `categories`, si listë id-sh ose `1,2`, raporti mbledh vetëm rreshtat e produkteve të atyre
kategorive dhe një faturë numërohet kur ka të paktën një rresht prej tyre; `0` merr produktet pa
kategori.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |
| `metric` | query | no | Çfarë mat seria: `gross` vlerën bruto, `count` numrin e faturave. Pa të merret `gross`. |
| `categories[]` | query | no |  |

**Responses:**

- `200` - Një pikë për çdo ditë të periudhës te `series`, në rend kronologjik, me `0` për ditët pa shitje; `metric` kthehet e konfirmuar.
- `401`
- `422` - `from` ose `to` mungon ose nuk është në formatin `YYYY-MM-DD`, ose `metric` nuk është `gross` as `count`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/reversals

**Summary:** Listo faturat e anuluara

Faturat e anuluara në periudhë, secila me `original_invoice_id`, faturën origjinale që
korrigjon, dhe `reversed_at`. `totals` mban numrin dhe vlerën e tyre.

- `limit` pranon nga `1` deri në `500`, me `100` si parazgjedhje.
- Përdoreni për të parë sa dhe pse anulohet: një numër i lartë anulimesh është zakonisht
  shenjë e një problemi në procesin e shitjes.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |
| `limit` | query | no | Sa rreshta të kthehen, nga 1 deri në 500. |

**Responses:**

- `200` - Faturat e anuluara të periudhës te `items`, nga anulimi më i fundit, deri në `limit`, me `totals` mbi të gjitha anulimet; `items` është bosh kur nuk ka anulime.
- `401`
- `422` - `from` ose `to` mungon ose nuk është në formatin `YYYY-MM-DD`, ose `limit` është jashtë `1` deri në `500`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/sales-summary

**Summary:** Merr përmbledhjen e shitjeve

Totalet e shitjeve për një periudhë: numri i faturave, bruto, neto, TVSH-ja dhe vlera mesatare
e faturës, të ndara njëherësh sipas mënyrës së pagesës, tipit të faturës, shkallës së TVSH-së
dhe ditës.

Përdoreni për rakordim periodik ose për një panel shitjesh. Për një ditë të vetme të arkës
përdorni `GET /reports/cash-register`.

Totalet mbajnë vetëm faturat e paanuluara. `cancelled` mban numrin dhe vlerën e faturave të
anuluara në periudhë, kështu që nuk ju duhet një thirrje e dytë për t'i kontrolluar.

Me `categories`, si listë id-sh ose `1,2`, raporti mbledh vetëm rreshtat e produkteve të atyre
kategorive dhe një faturë numërohet kur ka të paktën një rresht prej tyre; `0` merr produktet pa
kategori.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |
| `categories[]` | query | no |  |

**Responses:**

- `200` - Përmbledhja e shitjeve të periudhës te `data`: `totals`, ndarjet sipas mënyrës së pagesës, tipit të faturës, shkallës së TVSH-së dhe ditës, dhe `cancelled`; ndarjet janë bosh kur periudha nuk ka shitje.
- `401`
- `422` - `from` ose `to` mungon, ose nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/top-clients

**Summary:** Listo klientët kryesorë

Klientët e periudhës të renditur sipas vlerës së faturuar, me numrin e faturave dhe bruton për
secilin.

- `limit` pranon nga `1` deri në `500`, me `20` si parazgjedhje.
- Klienti i rastit, pra faturat pa blerës të emëruar, nuk hyn në renditje.

Me `categories`, si listë id-sh ose `1,2`, raporti mbledh vetëm rreshtat e produkteve të atyre
kategorive dhe një faturë numërohet kur ka të paktën një rresht prej tyre; `0` merr produktet pa
kategori.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |
| `limit` | query | no | Sa rreshta të kthehen, nga 1 deri në 500. |
| `categories[]` | query | no |  |

**Responses:**

- `200` - Klientët e periudhës te `items`, nga vlera bruto më e madhe, deri në `limit`; `items` është bosh kur periudha nuk ka shitje.
- `401`
- `422` - `from` ose `to` mungon ose nuk është në formatin `YYYY-MM-DD`, ose `limit` është jashtë `1` deri në `500`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/top-products

**Summary:** Listo produktet më të shitura

Produktet e periudhës të renditura sipas të ardhurave ose sipas sasisë së shitur, me `quantity`
dhe `revenue` për secilin.

| Parametri | Vlerat | Parazgjedhja |
| --- | --- | --- |
| `sort` | `revenue`, `quantity` | `revenue` |
| `limit` | `1` deri në `200` | `20` |

`sort` dhe `limit` kthehen të konfirmuara bashkë me `period`.

Me `categories`, si listë id-sh ose `1,2`, raporti mbledh vetëm rreshtat e produkteve të atyre
kategorive; `0` merr produktet pa kategori.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |
| `limit` | query | no | Sa produkte të kthehen, nga 1 deri në 200. |
| `sort` | query | no | Renditja: `revenue` sipas të ardhurave, `quantity` sipas sasisë. Pa të merret `revenue`. |
| `categories[]` | query | no |  |

**Responses:**

- `200` - Produktet e periudhës te `items`, nga më i shituri sipas `sort`, deri në `limit`; `items` është bosh kur periudha nuk ka shitje.
- `401`
- `422` - `from` ose `to` mungon ose nuk është në formatin `YYYY-MM-DD`, ose `limit` dhe `sort` janë jashtë vlerave të lejuara. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/vat

**Summary:** Merr raportin e TVSH-së

TVSH-ja e mbledhur nga shitjet përballë asaj të paguar në blerje për periudhën, me diferencën
që rezulton te `summary.vat_due`.

Rreshtat ndahen në dy grupe, si për shitjet ashtu edhe për blerjet te `purchases`:

- `taxable`, sipas shkallës: `0`, `6`, `10`, `20`;
- `exempt`, sipas llojit të përjashtimit.

Blerjet vijnë nga faturat e blerjes që ka regjistruar CIS-i, prandaj raporti mbulon të dyja
anët pa ju kërkuar të importoni gjë.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |

**Responses:**

- `200` - Raporti i TVSH-së te `data`: shitjet te `totals`, `taxable` dhe `exempt`, blerjet te `purchases`, dhe diferenca te `summary.vat_due`.
- `401`
- `422` - `from` ose `to` mungon, ose nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

### GET /reports/wtn

**Summary:** Merr raportin e fletëve shoqëruese

Fletët shoqëruese (WTN) të periudhës, të grupuara sipas gjendjes fiskale te `by_status`, bashkë
me destinacionet e përdorura dhe vlerën e mallit që ka lëvizur.

Një fletë e pafiskalizuar këtu kërkon vëmendje: malli ka lëvizur pa dokumentin që ligji
kërkon.

**Tags:** Raportet

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `from` | query | yes | Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. |
| `to` | query | yes | Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend. |

**Responses:**

- `200` - Fletët shoqëruese të periudhës te `data`: `totals`, ndarja sipas gjendjes fiskale te `by_status` dhe qytetet e destinacionit te `destinations`; `by_status` dhe `destinations` janë bosh kur periudha nuk ka fletë.
- `401`
- `422` - `from` ose `to` mungon, ose nuk është në formatin `YYYY-MM-DD`. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
- `403` - Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.
- `429` - Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.

---

## Full OpenAPI specification

For complete schemas, examples and request/response bodies, fetch the JSON spec:

```
https://fature.al/docs/api.json
```
