_Version: 2.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 v2

Versioni 2 mban dy grupe: **faturat** dhe **klientët**. Vetëm këto ndryshojnë formë nga v1, prandaj
vetëm këto kanë adresë të dytë. Gjithçka tjetër, fletët shoqëruese, faturat e blerjes, produktet,
arka fiskale, raportet dhe regjistrimi, mbetet te `v1` dhe thirret prej andej edhe nga një integrim
që faturat i dërgon me `v2`.

Të dy versionet ndajnë token-in, kredencialet e aplikacionit, formatin e përgjigjes dhe kufijtë e
kërkesave. Konceptet, identifikimi dhe rregullat e përbashkëta janë te dokumentacioni i v1, te
[`/docs/api`](/docs/api). Nëse nuk e keni lexuar, filloni prej andej.

## Serverat

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

## Çfarë ndryshon nga v1

### Pagesa e faturës është gjithmonë listë

Fatura e dërgon pagesën si `payment_methods`, me një element për çdo mënyrë. Një faturë e paguar me
një mënyrë të vetme dërgon një listë me një element, kështu që ka një formë të vetme për t'u mësuar.

```json
"payment_methods": [
  {"type": "BANKNOTE", "amount": 1200},
  {"type": "CARD", "amount": 800}
]
```

| Rregulli | Kufiri |
| --- | --- |
| Sa mënyra mban një faturë | 10 |
| Vlera e një `amount` | Çdo numër që pranon CIS-i, edhe 0 dhe negative |
| E njëjta mënyrë dy herë | Nuk lejohet |
| Shuma e `amount` | Sa totali i faturës, me zbritjen tashmë të zbatuar |

Fushat `payment_method`, `company_card` dhe `vouchers` mbi faturën nuk pranohen: karta e kompanisë
shkon te `payment_methods[].company_card` dhe tollonat te `payment_methods[].vouchers`, brenda
elementit që i kërkon. Faturat që kthehen nga listat dhe detajet e mbajnë po atë listë, ndaj
rakordimi i pagesave lexon gjithmonë një formë të vetme.

Fatura porosi nuk mban pagesë fare: ajo hap tavolinën, dhe përmbledhësja e paguan.

### Klienti ndahet në objekte

- **Objekte në vend të fushave të sheshta.** Të dhënat vijnë në `company`, `person`, `address` dhe
  `contact`, dhe fusha `type` (`company` ose `person`) thotë cili nga dy të parët është i plotësuar.
- **Identifikuesi është objekt.** `id` me `type` (`nuis`, `vat`, `tax` për kompani; `id`,
  `passport`, `social` për persona) dhe `value`, në vend të `nipt` ose `document_number`.
- **Vlerat janë me shkronja të vogla.** `company` në vend të `COMPANY`, `nuis` në vend të `NUIS`.
- **Përditësimi bëhet me `PATCH`**, jo me `PUT`, dhe `type` nuk ndryshon: një `type` i ndryshëm nga
  ai ekzistues refuzohet me `422`.

`GET /clients` e v2 kthen ende formatin e sheshtë të v1, sepse aplikacioni celular u ndërtua mbi të.
Detajet, krijimi dhe përditësimi janë në formatin e ri, dhe një klient i krijuar me `v1` lexohet me
`v2` pa asnjë hap tjetër.

## Servers

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

## Endpoints

### 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, NIPT-in,
  numrin e dokumentit, email-in, telefonin dhe numrin e klientit.
- 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, NIPT-in, numrin e dokumentit, 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 në formatin e v2. Body ndahet sipas fushës `type`, që pranon `company` ose
`person`, dhe plotësohet vetëm objekti që i përket llojit.

| `type` | Objekti | Fushat e detyrueshme |
| --- | --- | --- |
| `company` | `company` | `name`, `id` |
| `person` | `person` | `first_name`, `last_name`, `id` |

## Identifikuesi

Jepet gjithmonë si objekt `id` me `type` dhe `value`, dhe vlerat e lejuara varen nga lloji:

- kompani: `nuis`, `vat`, `tax`;
- person: `id`, `passport`, `social`.

## Objektet e përbashkëta

`address` (`line`, `city`, `country` me tre shkronja) dhe `contact` (`phone`, `email`) janë
opsionale dhe vlejnë për të dy llojet. `company.category` pranon `business`, `bank` ose
`exchange`.

Ruani `id`-në që kthehet: me të klienti gjendet dhe përditësohet përsëri. 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

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

**Responses:**

- `200` - Klienti i krijuar te `data.client`, me `id`-në e tij në fature.al; ruajeni për faturat dhe për përditësimet.
- `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 të njëjtat të dhëna.
- `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}

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

Kthen klientin në formatin e v2: `company` ose `person` sipas `type`, plus `address`,
`contact`, `customer_number` dhe `verified`.

Është i njëjti klient që kthen edhe `v1`, vetëm i strukturuar ndryshe. Një klient i krijuar me
`v1` lexohet këtu pa asnjë hap tjetër.

**Tags:** Klientët

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | Id-ja e klientit. |

**Responses:**

- `200` - Klienti te `data.client`, me `company` ose `person` të mbushur sipas llojit të tij.
- `401`
- `404` - Klienti nuk u gjet, ose nuk i përket kompanisë suaj.
- `500` - Gabim i papritur në server.

---

### PATCH /clients/{id}

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

Përditëson një klient me `PATCH` dhe me të njëjtin body si krijimi, me një kufizim: `type`
nuk ndryshon. Një kompani nuk bëhet person dhe as e kundërta; një `type` i ndryshëm nga ai
ekzistues refuzohet me `422`.

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. |

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

**Responses:**

- `200` - Klienti i përditësuar te `data.client`, i plotë, jo vetëm fushat e dërguara.
- `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 një `type` i ndryshëm nga ai ekzistues kthehet me formatin standard të gabimit.
- `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 me të njëjtat të dhëna.
- `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 /invoice

**Summary:** Listo faturat

E njëjta listë si te `v1`, ku çdo faturë mban `payment_methods` në vend të `payment_method`.
Filtrat dhe pagination janë ata të [`GET /api/v1/invoice`](/docs/api).

**Tags:** Faturat

**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`

---

### POST /invoice/bulk-noncash

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

I njëjti bulk si te `v1`, ku çdo faturë e `invoices` mban pagesën e vet si listë
`payment_methods`. 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 dhe
riprovoni vetëm ato që dështuan.

**Tags:** Faturat

**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`
- `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.

---

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

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

I njëjti anulim si te `v1`, duke e gjetur faturën me `internalId`-në që dërguat kur e lëshuat:
pa body anulohet e gjithë fatura, me `lines` vetëm një pjesë e saj, e mundur **vetëm për
faturat cash**. Rregullat e plota janë te
[`POST /api/v1/invoice/cancel-by-internal-id/{internalId}`](/docs/api).

Përgjigja është dokumenti korrigjues, me `iic` dhe `fic` të vetat dhe me `payment_methods`
bashkë me të. 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

I njëjti anulim si te `v1`: pa body anulohet e gjithë fatura, me `lines` vetëm një pjesë e
saj, e mundur **vetëm për faturat cash**. Rregullat e plota janë te
[`POST /api/v1/invoice/cancel/{id}`](/docs/api).

Përgjigja është dokumenti korrigjues, me `iic` dhe `fic` të vetat dhe me `payment_methods`
bashkë me të. 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

E njëjta faturë si te `v1`, me pagesën si listë. Për blerësin, rreshtat, zbritjet dhe
vetëfaturimin vlejnë rregullat e [`POST /api/v1/invoice/cash`](/docs/api).

## Pagesa

`payment_methods` mban një element për çdo mënyrë dhe është i detyrueshëm edhe kur fatura
paguhet e gjitha me një mënyrë.

```json
"payment_methods": [
  {"type": "BANKNOTE", "amount": 1200},
  {"type": "CARD", "amount": 800}
]
```

| Rregulli | Kufiri |
| --- | --- |
| Sa mënyra mban një faturë | 10 |
| E njëjta mënyrë dy herë | Nuk lejohet |
| Shuma e `amount` | Sa totali i faturës, me zbritjen tashmë të zbatuar |

Elementi `COMPANY` mban vetë `company_card`, dhe elementi `SVOUCHER` mban vetë `vouchers`.
Një listë që nuk e mbledh totalin refuzohet me `400`, sepse shuma kontrollohet vetëm pasi
zbritja mbi faturën është zbatuar.

Vetëfaturimi paguhet nga arka, si te `v1`: kur arka nuk mbulon totalin, fatura nuk ruhet dhe
përgjigja vjen me HTTP 200 dhe `status: false`.

**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 `POST /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/details/{internalId}

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

I njëjti rezultat lëshimi si te `v1`, me `payment_methods` bashkë me të. Përdoreni për të lexuar
gjendjen pas një timeout-i ose pas një `409`.

**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, me `payment_methods`.
- `401`

---

### POST /invoice/e-invoice

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

E njëjta e-faturë si te `v1`, me pagesën si listë `payment_methods`. Për blerësin, llojin e
dokumentit (`doc_type` dhe `process`) dhe notat e korrigjimit vlejnë rregullat e
[`POST /api/v1/invoice/e-invoice`](/docs/api).

**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 `POST /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

E njëjta faturë si te `v1`, me pagesën si listë `payment_methods`. Për blerësin, llogarinë
bankare, notat e korrigjimit dhe zbritjet vlejnë rregullat e
[`POST /api/v1/invoice/noncash`](/docs/api).

Mënyrat e lejuara janë `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER`
dhe `WAIVER`; asnjëra nuk mban kartë kompanie ose tollona. Kur mënyra që paguan pjesën më të
madhe është `ACCOUNT`, fatura kërkon llogarinë bankare, si te `v1`.

**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 `POST /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

E njëjta porosi si te `v1`. Porosia hap tavolinën dhe nuk paguan asgjë, ndaj nuk mban as
`payment_method` dhe as `payment_methods`: pagesa vjen më vonë, me faturën përmbledhëse që e
mbyll tavolinën. Rregullat janë ato të [`POST /api/v1/invoice/order`](/docs/api).

**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` - 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 `POST /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.

Kontrolloni `Content-Type` para se ta ruani si PDF: një EIC që nuk gjendet kthen tekstin
`Document not found.` me statusin `200` dhe `text/html`, jo një PDF.

**Tags:** Faturat

**Parameters:**

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

**Responses:**

- `200` - PDF-ja e e-faturës. Kontrolloni `Content-Type` para se ta ruani: një EIC që nuk gjendet kthehet po me statusin 200, por si `text/html`.
- `401`

---

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

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

- `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.

---

### 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, si te `v1`, me
pagesën si listë `payment_methods`. Një tavolinë e paguar gjysmë me para në dorë dhe gjysmë me
kartë dërgon një listë me dy elemente; e paguar e gjitha me kartë, një listë me një element.
Lejohen vetëm `BANKNOTE` dhe `CARD`. Rregullat për `order_invoices` dhe zbritjen janë ato të
[`POST /api/v1/invoice/summary`](/docs/api).

**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 `POST /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/{id}/details

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

Të njëjtat detaje si te `v1`, ku pagesa vjen si listë `payment_methods`. Kur fatura nuk gjendet,
`data.invoice` është `null` me statusin `200`.

**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`

---

## Full OpenAPI specification

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

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