_Version: 1.0_

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

# fature.al API

API per integrimin me fature.al - sistemi i fiskalizimit dhe faturimit per bizneset ne Shqiperi.

## Identifikimi

Te gjitha kerkesat kerkojne nje Bearer token ne header-in Authorization:

```
Authorization: Bearer {api_token}
```

Token-in e gjeneroni nga **Konfigurime > API Tokens** ne panelin e fature.al, ose e merrni nga pergjigja e endpoint-it Register Company.

## Serverat

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

## Seksionet kryesore

- **On Boarding** - regjistrimi i kompanise, certifikata elektronike, njesite e biznesit, perdoruesit, pajisjet fiskale (TCR), llogarite bankare
- **Invoice** - krijimi i faturave Cash, NonCash, E-Invoice, Order, Summary. Listimi, detajet, anullimi, printimi PDF
- **Arka Fiskale** - hapja dhe mbyllja e arkes per shitje me para ne dore
- **Klienti** - kerkimi i kompanive ne regjistrin fiskal sipas NIPT

## Rrjedha e integrimit (ne rastet kur behet onboarding e klienteve me api)

1. **Regjistro kompaninë** (`POST /register`) - merr token + branch ID
2. **Ngarko certifikaten** (`POST /on-boarding/certificate`)
3. **Konfiguro njesine e biznesit** (`POST /on-boarding/branch/{id}`) - vendos businessUnitCode
4. **Krijo pajisje fiskale** (`POST /on-boarding/fiscal-device`) - merr kodin TCR
5. **Konfiguro perdoruesin** (`POST /on-boarding/user/{id}`) - vendos operatorCode + fiscalTcrCode
6. **Fillo leshimin e faturave** - perdor endpoint-et e Invoice

## Formati i pergjigjes

Te gjitha pergjigjjet kane formatin:
```json
{"success": true, "data": { ... }}
```

Ne rast gabimi:
```json
{"success": false, "errors": ["Mesazhi i gabimit"]}
```

## Limitet (Rate limiting)

API ka limit kerkesash per te mbrojtur sherbimin dhe per te garantuar performance per te gjithe perdoruesit. Kur arrihet limiti, server-i kthen statusin **HTTP 429 Too Many Requests** se bashku me header-in `Retry-After` (sekonda) qe tregon kohen e nevojshme per te ritestuar.

Limitet jane **per perdorues** (te lidhura me API token-in tuaj), me perjashtim te limitit te pergjithshem qe eshte per IP.

| Kategoria | Endpoint-et | Limit |
|-----------|-------------|-------|
| **I pergjithshem (per IP)** | te gjitha kerkesat e nivelit te API-t | 120/minute |
| **Default (per perdorues)** | te gjitha endpoint-et e mbrojtura me identifikim | 240/minute |
| **Fatura fiskale** | `POST /invoice/cash`, `/invoice/noncash`, `/invoice/e-invoice`, `/invoice/order`, `/invoice/summary`, `/invoice/cancel/*`, `/invoice/wtn` | 30/minute, 600/ore |
| **Bulk** | `POST /invoice/bulk-noncash` | 3/minute, 30/ore |
| **Printim PDF** | `GET /invoice/print/{id}`, `/invoice/print-eic/{eic}`, `/invoice/wtn/print/{id}` | 30/minute |
| **Kerkim klientesh** | `GET /client/search` | 90/minute |
| **Onboarding** | `POST /register`, `POST /on-boarding/*` | 30/minute, 600/ore (per perdorues) |

Kur perdorimi juaj eshte i larte ne menyre te qendrueshme dhe limitet bllokojne integrimin, na kontaktoni.

### Pergjigja kur arrihet limiti

```json
{
    "message": "Too Many Attempts."
}
```

Header-at e kthyer:
- `Retry-After: 30` - numri i sekondave para se te ritestoni
- `X-RateLimit-Limit` - limiti maksimal per dritaren aktuale
- `X-RateLimit-Remaining` - kerkesat e mbetura ne kete dritare

## Servers

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

## Endpoints

### GET /account

**Summary:** Te dhenat e llogarise

Kthen te dhenat e perdoruesit te autentifikuar: emri, email, kodi fiskal dhe kompania.

**Tags:** Account

**Responses:**

- `200`
- `401`

---

### GET /bank-accounts

**Summary:** Lista e llogarive bankare

Merr listen e llogarive bankare aktive te kompanise me faqosje dhe filtrim me tekst.

**Tags:** BankAccount

**Responses:**

- `200`
- `401`

---

### GET /cash-register/actions

**Summary:** Lista e veprimeve me arken

Merrni listen e veprimeve me arken fiskale (hyrje, dalje, hapje/mbyllje dite) me filtrim dhe faqosje.

**Tags:** CashRegister

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `type` | query | no |  |
| `fromDate` | query | no |  |
| `toDate` | query | no |  |

**Responses:**

- `200`
- `401`

---

### GET /cash-register/balance

**Summary:** Balanca e arkes fiskale

Merrni balancen aktuale ne ALL te arkes fiskale (TCR) te perdoruesit. Nese [toDate] nuk jepet, kthehet balanca e fundit.

**Tags:** CashRegister

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `toDate` | query | no |  |

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Mbyll balancen e arkes

Mbyllni balancen e arkes fiskale ne fund te dites. Nese arka nuk eshte e hapur, hapet automatikisht me balance 0.

**Tags:** CashRegister

**Responses:**

- `200`
- `401`

---

### POST /cash-register/deposit

**Summary:** Hyrje ne arke (Deposit)

Bej nje hyrje parash ne arken fiskale (MONEY_IN). Kerkon qe perdoruesi te kete pajisje fiskale (TCR) te lidhur.

**Tags:** CashRegister

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Hap balancen e arkes

Hapni balancen e arkes fiskale per te filluar shitjet me para ne dore. Perdoruesi duhet te kete pajisje fiskale (TCR) te lidhur.

**Tags:** CashRegister

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

**Responses:**

- `200`
- `401`

---

### POST /cash-register/withdraw

**Summary:** Dalje nga arka (Withdraw)

Bej nje dalje parash nga arka fiskale (MONEY_OUT). Kerkon qe perdoruesi te kete pajisje fiskale (TCR) te lidhur.

**Tags:** CashRegister

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

**Responses:**

- `200`
- `401`
- `422`

---

### GET /client/search

**Summary:** Kerko klient sipas NIPT

Kerkoni nje kompani ne regjistrin fiskal duke perdorur NIPT/NUIS. Kthen te dhenat e kompanise nese gjendet.

**Tags:** Client

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `nuis` | query | no |  |

**Responses:**

- `200`
- `401`

---

### GET /clients

**Summary:** Lista e klienteve

Merr listen e klienteve te kompanise me faqosje dhe filtrim me tekst.

**Tags:** Client

**Responses:**

- `200`
- `401`

---

### POST /clients

**Summary:** Krijo klient

**Tags:** Client

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

**Responses:**

- `200`
- `401`
- `422`

---

### PUT /clients/{id}

**Summary:** Perditeso klient

Perditeson nje klient ekzistues. Trupi i kerkeses ka te njejtin format si POST /clients.

**Tags:** Client

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Detajet e klientit sipas ID

**Tags:** Client

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### GET /currencies

**Summary:** Lista e monedhave

Kthen monedhat e konfiguruara për kompaninë,
me ALL gjithmonë në fillim.

**Tags:** Currencies

**Responses:**

- `200`
- `401`

---

### GET /exchange-rates

**Summary:** Kursi i këmbimit

Kthen kursin e shitjes së ditës për çdo monedhë, sipas burimit të
zgjedhur. Të dhënat vijnë nga `https://api.kursi.al/api/rates` dhe
ruhen ne cache per 1h në server; klienti mund të mbajë snapshot-in e fundit
lokalisht për përdorim offline.

Burimet e mbështetura (vlera `source` në kërkesë):
  - `BOA`      → Banka e Shqipërisë (kursi zyrtar)
  - `BKT`      → Banka Kombëtare Tregtare
  - `Iliria98` → Këmbim Valutor "Iliria '98"
  - `ADON`     → Këmbim Valutor "Adon"

Burim i pa percaktuar kthehet automatikisht në `BOA`. Fusha `source` në
përgjigje është gjithmonë vlera e normalizuar.

**Tags:** Currencies

**Responses:**

- `200`
- `401`

---

### GET /invoice

**Summary:** Lista e faturave

Merrni listen e faturave me filtrim dhe faqosje.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `type` | query | no |  |
| `fromDate` | query | no |  |
| `toDate` | query | no |  |
| `query` | query | no |  |

**Responses:**

- `200`
- `401`

---

### POST /invoice/bulk-noncash

**Summary:** Krijo fatura pa para ne dore ne bllok (Bulk NonCash)

**Tags:** Invoice

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

**Responses:**

- `200`
- `401`

---

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

**Summary:** Anullo fature sipas Internal ID

Anullon faturen duke perdorur ID-ne tuaj interne qe keni derguar kur keni krijuar faturen.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `internalId` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### POST /invoice/cancel/{invoiceId}

**Summary:** Anullo fature sipas ID

Anullon faturen dhe krijon regjistrim fiskal anullimi ne sistemin e tatimeve. Nuk kerkohet body.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `invoiceId` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### POST /invoice/cash

**Summary:** Krijo fature me para ne dore (Cash)

**Tags:** Invoice

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

**Responses:**

- `200`
- `401`
- `422`

---

### POST /invoice/details/{internalId}

**Summary:** Detajet e fatures sipas Internal ID

Merr detajet e nje fature duke perdorur ID-ne tuaj interne.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `internalId` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### POST /invoice/e-invoice

**Summary:** Krijo fature elektronike (E-Invoice)

Fatura dergohet automatikisht ne sistemin qendror te e-faturave. Klienti identifikohet me NIPT.

**Tags:** Invoice

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

**Responses:**

- `200`
- `401`
- `422`

---

### POST /invoice/noncash

**Summary:** Krijo fature pa para ne dore (NonCash)

Perdoret per transaksione me transferte bankare, cek, etj.

**Tags:** Invoice

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

**Responses:**

- `200`
- `401`
- `422`

---

### POST /invoice/order

**Summary:** Krijo fature porosi (Order)

Fatura regjistrohet por pagesa nuk perfundon - perdoret me summary invoice.
payment_method vendoset automatikisht ne ORDER.

**Tags:** Invoice

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Shkarko PDF te fatures sipas EIC

Kthen skedarin PDF te fatures duke perdorur kodin EIC (UUID).

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `eic` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### GET /invoice/print/{invoiceId}

**Summary:** Shkarko PDF te fatures sipas ID

Kthen skedarin PDF te fatures.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `invoiceId` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### POST /invoice/summary

**Summary:** Krijo fature permbledhese (Summary)

Perfundon pagesen e nje ose me shume faturave Order. Duhet te specifikoni IIC-te e faturave order ne fushen order_invoices.

**Tags:** Invoice

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

**Responses:**

- `500`
- `200`
- `503`
- `400`
- `409`
- `422`
- `403`
- `429`
- `401`

---

### GET /invoice/wtn

**Summary:** Lista e faturave shoqeruese (WTN)

Merr listen e faturave shoqeruese me faqosje dhe filtrim sipas datave.

**Tags:** WtnInvoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `fromDate` | query | no |  |
| `toDate` | query | no |  |

**Responses:**

- `500`
- `422`
- `200`
- `429`
- `401`

---

### POST /invoice/wtn

**Summary:** Krijo fature shoqeruese (WTN)

**Tags:** WtnInvoice

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

**Responses:**

- `500`
- `503`
- `200`
- `403`
- `429`
- `401`
- `422`

---

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

**Summary:** Te dhenat e fatures shoqeruese ne format printimi (JSON)

Kthen nje strukture JSON me te gjitha te dhenat per nje "print view".

**Tags:** WtnInvoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `invoiceId` | path | yes |  |

**Responses:**

- `200`
- `404`
- `401`

---

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

**Summary:** Detajet e fatures shoqeruese sipas ID

**Tags:** WtnInvoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

**Responses:**

- `500`
- `200`
- `404`
- `401`

---

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

**Summary:** Detajet e fatures sipas ID

Merrni detajet e plota te nje fature sipas ID-se ne sistem.

**Tags:** Invoice

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

**Responses:**

- `200`
- `401`

---

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

**Summary:** Krijo llogari bankare

Krijoni nje llogari bankare per kompaninë. Llogaria bankare shfaqet ne faturat elektronike dhe jo-cash si informacion pagese per klientin.

**Tags:** On Boarding

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Perditeso njesine e biznesit (Branch)

Perditesoni emrin, adresen, administratorin dhe kodin e biznesit per nje njesi biznesi ekzistuese. Kodi i biznesit (businessUnitCode) eshte i domosdshem per leshimin e faturave.

**Tags:** On Boarding

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

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

**Responses:**

- `200`
- `401`

---

### POST /on-boarding/certificate

**Summary:** Ngarko certifikaten elektronike

Ngarkoni certifikaten elektronike (.p12 ose .pfx) per kompaninë. Fjalekalimi duhet te jete i sakte dhe NIPT-i ne certifikate duhet te perputhet me NIPT-in e kompanise.

**Sandbox (DEMO):** ne instancen DEMO ky endpoint kthen `success` per cdo certifikate dhe cdo fjalekalim. `expiresAt` qe kthehet eshte +1 vit nga sot.

**Tags:** On Boarding

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Krijo pajisje fiskale (TCR)

Regjistron nje pajisje fiskale te re ne sistemin e tatimeve dhe kthen kodin TCR. Ky kod perdoret per faturat me para ne dore dhe duhet te lidhet me perdoruesin perkates.

**Tags:** On Boarding

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

**Responses:**

- `200`
- `401`
- `422`

---

### POST /on-boarding/user

**Summary:** Krijo perdorues te ri

Krijoni nje perdorues te ri per kompaninë me kodin e operatorit dhe pajisjen fiskale. Kthen token API per kete perdorues.

**Tags:** On Boarding

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

**Responses:**

- `200`
- `401`

---

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

**Summary:** Perditeso perdoruesin

Perditesoni emrin, kodin e operatorit, pajisjen fiskale dhe njesine e biznesit per nje perdorues ekzistues. Kodi i operatorit eshte i domosdshem per leshimin e faturave.

**Tags:** On Boarding

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

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

**Responses:**

- `200`
- `401`

---

### GET /ping

**Summary:** Ping

Kontrollo nese API eshte aktiv. Kthen timestamp dhe IP.

**Tags:** Ping

**Responses:**

- `200`
- `401`

---

### GET /product/categories

**Summary:** Lista e kategorive

Merrni listen e kategorive te produkteve per kompaninë tuaj.

**Tags:** Products

**Responses:**

- `200`
- `401`

---

### GET /products

**Summary:** Lista e produkteve

Merrni listen e produkteve per kompaninë tuaj. Kthen id, kodin, emrin, njesine, cmimin e fundit, shkallen e TVSH, llojin e perjashtimit nga TVSH dhe kategorinë.

**Tags:** Products

**Responses:**

- `200`
- `401`

---

### POST /products

**Summary:** Krijo produkt

Krijon nje produkt te ri per kompaninë tuaj. Kodi gjenerohet automatikisht nese nuk jepet. Njesia matese derivohet nga unit_code.

**Tags:** Products

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

**Responses:**

- `200`
- `401`
- `422`

---

### PUT /products/{id}

**Summary:** Perditeso produkt

Perditeson nje produkt ekzistues. Trupi i kerkeses ka te njejtin format si POST /products.

**Tags:** Products

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

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

**Responses:**

- `200`
- `401`
- `422`

---

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

**Summary:** Detajet e produktit sipas ID

Merrni detajet e nje produkti sipas id-se per kompaninë tuaj.

**Tags:** Products

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes |  |

**Responses:**

- `200`
- `401`

---

### GET /register

**Summary:** Ping (Register)

Kontrollo nese API eshte aktiv per regjistrimin e kompanive.

**Tags:** On Boarding

**Responses:**

- `200`
- `401`

---

### POST /register

**Summary:** Regjistro kompani te re

Regjistron nje kompani te re ne fature.al. Kerkon token special te autorizuar nga fature.al. Kthen token API per perdoruesin e krijuar dhe ID e njesise se biznesit.

**Sandbox (DEMO):** ne instancen DEMO, dergimi i NIPT-it `L62221018T` aktivizon rrjedhen sandbox: nuk krijohet kompani e re, por krijohet nje perdorues + njesi biznesi nen kompanine ekzistuese sandbox dhe ju kthehet nje `api_token` real qe e perdorni per hapat e tjere te onboarding-ut. Email-i shtohet me sufiks `+sandbox-XXXXXXXX` qe te lejojme thirrje te perseritura me te njejtin email. Ne `PRODUCTION` ky NIPT trajtohet normalisht.

**Tags:** On Boarding

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

**Responses:**

- `200`
- `401`
- `422`

---

## Full OpenAPI specification

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

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