_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 i API-t. Per momentin mbulon vetem klientet.

Gjithcka tjeter eshte e njejte me v1: i njejti token, te njejtat kredenciale te aplikacionit, i
njejti zarf pergjigjeje dhe te njejtat limite kerkesash. Per identifikimin, limitet dhe udhezimet e
implementimit shihni dokumentacionin e v1 te [`/docs/api`](/docs/api).

## Serverat

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

## Cfare ndryshon nga v1

- **Klienti ndahet ne objekte.** Ne vend te nje liste te sheshte fushash, te dhenat vijne ne
  `company`, `person`, `address` dhe `contact`, dhe fusha `type` (`company` ose `person`) thote cili
  prej dy te paret eshte i plotesuar.
- **Identifikuesi eshte objekt.** `id` me `type` (`nuis`, `vat`, `tax` per kompani; `id`,
  `passport`, `social` per persona) dhe `value`, ne vend te `nipt` ose `document_number`.
- **Vokabulari eshte me shkronja te vogla.** `company` ne vend te `COMPANY`, `nuis` ne vend te
  `NUIS`.
- **Editimi behet me `PATCH`**, jo me `PUT`, dhe `type` nuk mund te ndryshohet: nje `type` i
  ndryshem nga ai ekzistues refuzohet me 422.

## Servers

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

## Endpoints

### GET /clients

**Summary:** Lista e klienteve

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

**Tags:** Klienti

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Numri i klienteve per faqe (max 100). |
| `offset` | query | no | Nga cili klient te fillohet. |
| `query` | query | no | Kerkim ne emer, mbiemer, NIPT, dokument, email ose telefon. |

**Responses:**

- `200`
- `401`
- `429` - Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.
- `500` - Gabim i papritur ne server.

---

### POST /clients

**Summary:** Krijo klient (v2)

Trupi i kerkeses eshte nje bashkim i diskriminuar nga fusha `type` (company|person).
Objekti `company` plotesohet kur `type=company`, ndersa `person` kur `type=person`.
Identifikuesi jepet si objekt `id` me `type` (nuis|vat|tax per kompani, id|passport|social per person) dhe `value`.

**Tags:** Client v2

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

**Responses:**

- `200`
- `401`
- `422` - Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.
- `409` - Ekziston tashme nje regjistrim me te njejtat te dhena.
- `429` - Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.
- `500` - Gabim i papritur ne server.

---

### GET /clients/{id}

**Summary:** Detajet e klientit (v2)

Kthen klientin ne formatin e ri me objekte te ndara (company/person/address/contact).

**Tags:** Client v2

**Parameters:**

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

**Responses:**

- `200`
- `401`
- `404` - Klienti nuk u gjet, ose nuk i perket kompanise suaj.
- `500` - Gabim i papritur ne server.

---

### PATCH /clients/{id}

**Summary:** Perditeso klient (v2)

I njejti trup si POST. Lloji (`type`) eshte i pandryshueshem ne editim: nese dergohet nje
`type` i ndryshem nga ai ekzistues, kerkesa refuzohet me 422.

**Tags:** Client v2

**Parameters:**

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

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

**Responses:**

- `200`
- `401`
- `422` - Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. Perfshin edhe rastin kur `type` ndryshon nga ai ekzistues.
- `403` - Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.
- `404` - Klienti nuk u gjet, ose nuk i perket kompanise suaj.
- `409` - Ekziston tashme nje klient me te njejtat te dhena.
- `429` - Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.
- `500` - Gabim i papritur ne server.

---

## Full OpenAPI specification

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

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