Listo klientët (v1): fature.al API

GET /api/v1/clients Requires authentication Rate limited by the `api-global` limiter v1

Send a bearer token, plus the X-Client-Id and X-Client-Secret headers in the Authorization header.

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

URL-ja e plotë: https://fature.al/api/v1/clients

Query parameters

Name	Tipi	E detyrueshme	Përshkrimi
limit	integer	no	Sa klientë të kthehen në një faqe, deri në 100. Defaults to `20`.
offset	integer	no	Nga cili klient të fillohet, duke numëruar nga 0. Defaults to `0`.
query	string	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.

Përgjigjet

200 Klientët e faqes te `items`, me `pagination`; `items` është bosh kur asnjë klient nuk përputhet.

Field	Tipi	Përshkrimi
status	boolean
data	object
data.items	array
data.items[].id	integer	Id-ja e klientit në fature.al
data.items[].name	string	Emri i plotë: emri i kompanisë te një kompani, emri dhe mbiemri te një person
data.items[].client_type	string, nullable	`COMPANY` ose `PERSON`
data.items[].company_name	string, nullable	Emri i kompanisë; bosh ose null te një person
data.items[].company_type	string, nullable	Kategoria e kompanisë: `BUSINESS`, `BANK` ose `EXCHANGE`. Gjithmonë null te një person
data.items[].nipt	string, nullable	NIPT-i i kompanisë, ose numri VAT/TAX i një biznesi të huaj; null kur nuk ka
data.items[].first_name	string, nullable	Emri i personit; gjithmonë null te një kompani
data.items[].surname	string, nullable	Mbiemri i personit; gjithmonë null te një kompani
data.items[].birthday	string, nullable	Data e lindjes, `YYYY-MM-DD`; null kur nuk është dhënë
data.items[].id_type	string, nullable	Lloji i dokumentit të identifikimit: `NUIS`, `ID`, `PASS`, `VAT`, `TAX` ose `SOC`; null kur nuk është regjistruar
data.items[].id_num	string, nullable	Numri i dokumentit: NIPT-i te një kompani, numri i dokumentit personal te një person
data.items[].nationality_code	string, nullable	Shteti i klientit, kod ISO 3166-1 alpha-3
data.items[].nationality_id	integer, nullable	Id-ja e shtetit në fature.al, çifti i `nationality_code`
data.items[].telephone	string, nullable	Telefoni
data.items[].email	string, nullable	Email-i
data.items[].address	string, nullable	Adresa
data.items[].city	string, nullable	Qyteti
data.items[].customer_number	string, nullable	Numri i klientit në sistemin tuaj. Kur nuk e keni dhënë, fature.al vë numrin rendor të klientit brenda kompanisë
data.items[].created_at	string, nullable	Data dhe ora e krijimit, ISO 8601
data.pagination	object
data.pagination.records	integer	Sa klientë mban `items` në këtë përgjigje
data.pagination.total	integer	Sa klientë përputhen gjithsej me kërkimin, në të gjitha faqet
data.pagination.limit	integer	Kufiri që u zbatua: ai që dërguat, i ulur në `100` kur ishte më i madh; `20` kur nuk dërguat
data.pagination.offset	integer	Nga cili klient filloi kjo faqe, duke numëruar nga 0

401 Unauthenticated

Field	Tipi	Përshkrimi
message	string

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.

Field	Tipi	Përshkrimi
status	boolean	Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data`
message	string	Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin
errors	array	Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message`

500 Gabim i papritur në server.

Field	Tipi	Përshkrimi
status	boolean	Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data`
message	string	Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin
errors	array	Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message`

Shembull kërkese

cURL

curl -X GET 'https://fature.al/api/v1/clients' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Client-Id: YOUR_CLIENT_ID' \
  -H 'X-Client-Secret: YOUR_CLIENT_SECRET' \
  -H 'Accept: application/json'

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_TOKEN',
    'X-Client-Id' => 'YOUR_CLIENT_ID',
    'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
    'Accept' => 'application/json',
])->get('https://fature.al/api/v1/clients');

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('GET', 'https://fature.al/api/v1/clients', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'X-Client-Id' => 'YOUR_CLIENT_ID',
        'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode((string) $response->getBody(), true);

JavaScript

const response = await fetch('https://fature.al/api/v1/clients', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Client-Id': 'YOUR_CLIENT_ID',
    'X-Client-Secret': 'YOUR_CLIENT_SECRET',
    'Accept': 'application/json'
  }
});

const data = await response.json();

Shembull përgjigjeje

200

{
    "status": true,
    "data": {
        "items": [
            {
                "id": 42,
                "name": "Alpha SHPK",
                "client_type": "COMPANY",
                "company_name": "Alpha SHPK",
                "company_type": "BUSINESS",
                "nipt": "L91806031A",
                "first_name": "Agon",
                "surname": "Hoxha",
                "birthday": "1990-01-15",
                "id_type": "NUIS",
                "id_num": "L91806031A",
                "nationality_code": "ALB",
                "nationality_id": 3,
                "telephone": "+355691234567",
                "email": "[email protected]",
                "address": "Rruga e Kavajës 12",
                "city": "Tiranë",
                "customer_number": "CLI-001",
                "created_at": "2026-09-13T10:15:00+02:00"
            }
        ],
        "pagination": {
            "records": 20,
            "total": 137,
            "limit": 20,
            "offset": 0
        }
    }
}

401

{
    "message": "Unauthenticated."
}

429

{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}

500

{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}