/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.
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ë.
URL-ja e plotë: https://fature.al/api/v1/clients
Body parameters
| Name | Tipi | E detyrueshme | Përshkrimi |
|---|---|---|---|
| client_type | string, one of PERSON, COMPANY | yes | Lloji i klientit: `COMPANY` ose `PERSON`. I detyrueshëm; vendos cilat fusha më poshtë janë të detyrueshme. |
| company_name | string, maxLength 255, nullable | yes | Emri i kompanisë. I detyrueshëm për `COMPANY`. Required depending on client_type. |
| nipt | string, maxLength 20, nullable | yes | NIPT-i i kompanisë, ose numri VAT/TAX i një biznesi të huaj. I detyrueshëm për `COMPANY`. Required depending on client_type. |
| address | string, maxLength 255, nullable | yes | Adresa e kompanisë. E detyrueshme për `COMPANY`. Required depending on client_type. |
| city | string, maxLength 50, nullable | yes | Qyteti i kompanisë. I detyrueshëm për `COMPANY`. Required depending on client_type. |
| company_type | string, one of BUSINESS, BANK, EXCHANGE, nullable | no | Kategoria e kompanisë: `BUSINESS`, `BANK` ose `EXCHANGE`. |
| name | string, maxLength 255, nullable | yes | Emri i personit. I detyrueshëm për `PERSON`. Required depending on client_type. |
| surname | string, maxLength 255, nullable | yes | Mbiemri i personit. I detyrueshëm për `PERSON`. Required depending on client_type. |
| document_type | string, one of NUIS, ID, PASS, VAT, TAX, SOC, nullable | yes | Lloji i dokumentit të identifikimit: `NUIS`, `ID`, `PASS`, `VAT`, `TAX` ose `SOC`. I detyrueshëm për `PERSON`. Required depending on client_type. |
| document_number | string, maxLength 255, nullable | yes | Numri i dokumentit të identifikimit. I detyrueshëm për `PERSON`. Required depending on client_type. |
| nationality_code | string, minLength 3, maxLength 3, nullable | no | Shteti i klientit, kod ISO 3166-1 alpha-3. Pa të merret `ALB`. |
| nationality_id | integer, nullable | no | Id-ja e shtetit në fature.al. Plotësohet vetë nga `nationality_code`; nuk ka nevojë ta dërgoni. |
| telephone | string, maxLength 255, nullable | no | Telefoni. |
| string<email>, maxLength 255, nullable | no | Email-i. | |
| customer_number | string, maxLength 30, nullable | no | Numri i klientit në sistemin tuaj. |
| gender | string, maxLength 10, nullable | no | Gjinia, vetëm për `PERSON`. |
| birthday | string<date-time>, nullable | no | Data e lindjes, `YYYY-MM-DD`, vetëm për `PERSON`. |
Përgjigjet
200 Klienti i sapokrijuar te `client`, me `id`-në e tij.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | |
| data | object | |
| data.client | object | |
| data.client.id | integer | Id-ja e klientit në fature.al |
| data.client.name | string | Emri i plotë: emri i kompanisë te një kompani, emri dhe mbiemri te një person |
| data.client.client_type | string, nullable | `COMPANY` ose `PERSON` |
| data.client.company_name | string, nullable | Emri i kompanisë; bosh ose null te një person |
| data.client.company_type | string, nullable | Kategoria e kompanisë: `BUSINESS`, `BANK` ose `EXCHANGE`. Gjithmonë null te një person |
| data.client.nipt | string, nullable | NIPT-i i kompanisë, ose numri VAT/TAX i një biznesi të huaj; null kur nuk ka |
| data.client.first_name | string, nullable | Emri i personit; gjithmonë null te një kompani |
| data.client.surname | string, nullable | Mbiemri i personit; gjithmonë null te një kompani |
| data.client.birthday | string, nullable | Data e lindjes, `YYYY-MM-DD`; null kur nuk është dhënë |
| data.client.id_type | string, nullable | Lloji i dokumentit të identifikimit: `NUIS`, `ID`, `PASS`, `VAT`, `TAX` ose `SOC`; null kur nuk është regjistruar |
| data.client.id_num | string, nullable | Numri i dokumentit: NIPT-i te një kompani, numri i dokumentit personal te një person |
| data.client.nationality_code | string, nullable | Shteti i klientit, kod ISO 3166-1 alpha-3 |
| data.client.nationality_id | integer, nullable | Id-ja e shtetit në fature.al, çifti i `nationality_code` |
| data.client.telephone | string, nullable | Telefoni |
| data.client.email | string, nullable | Email-i |
| data.client.address | string, nullable | Adresa |
| data.client.city | string, nullable | Qyteti |
| data.client.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.client.created_at | string, nullable | Data dhe ora e krijimit, ISO 8601 |
401 Unauthenticated
| Field | Tipi | Përshkrimi |
|---|---|---|
| message | string |
403 Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
| 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` |
409 Ekziston tashmë një klient me këtë NIPT.
| 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` |
422 Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.
| Field | Tipi | Përshkrimi |
|---|---|---|
| success | boolean | Gjithmonë false |
| message | string | Një rresht përmbledhës, i njëjtë për çdo dështim validimi |
| errors | object | Fushat që nuk kaluan validimin, secila me mesazhet e veta. Çelësat me pikë tregojnë brenda objekteve dhe elementëve të array-ve, p.sh. `lines.0.quantity` |
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 -X POST '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' \
-H 'Content-Type: application/json' \
-d '{
"client_type": "COMPANY",
"company_name": "Alpha SHPK",
"nipt": "L91806031A",
"address": "Rruga X",
"city": "Tirane",
"company_type": "BUSINESS",
"name": "Agon",
"surname": "Hoxha",
"document_type": "ID",
"document_number": "I12345678A",
"nationality_code": "ALB",
"nationality_id": 1,
"telephone": "+355691234567",
"email": "[email protected]",
"customer_number": "CLI-001",
"gender": "M",
"birthday": "1990-01-15"
}'
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',
'Content-Type' => 'application/json',
])->post('https://fature.al/api/v1/clients', [
'client_type' => 'COMPANY',
'company_name' => 'Alpha SHPK',
'nipt' => 'L91806031A',
'address' => 'Rruga X',
'city' => 'Tirane',
'company_type' => 'BUSINESS',
'name' => 'Agon',
'surname' => 'Hoxha',
'document_type' => 'ID',
'document_number' => 'I12345678A',
'nationality_code' => 'ALB',
'nationality_id' => 1,
'telephone' => '+355691234567',
'email' => '[email protected]',
'customer_number' => 'CLI-001',
'gender' => 'M',
'birthday' => '1990-01-15',
]);
$data = $response->json();
use GuzzleHttp\Client;
$client = new Client();
$response = $client->request('POST', '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',
'Content-Type' => 'application/json',
],
'json' => [
'client_type' => 'COMPANY',
'company_name' => 'Alpha SHPK',
'nipt' => 'L91806031A',
'address' => 'Rruga X',
'city' => 'Tirane',
'company_type' => 'BUSINESS',
'name' => 'Agon',
'surname' => 'Hoxha',
'document_type' => 'ID',
'document_number' => 'I12345678A',
'nationality_code' => 'ALB',
'nationality_id' => 1,
'telephone' => '+355691234567',
'email' => '[email protected]',
'customer_number' => 'CLI-001',
'gender' => 'M',
'birthday' => '1990-01-15',
],
]);
$data = json_decode((string) $response->getBody(), true);
const response = await fetch('https://fature.al/api/v1/clients', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'X-Client-Id': 'YOUR_CLIENT_ID',
'X-Client-Secret': 'YOUR_CLIENT_SECRET',
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"client_type": "COMPANY",
"company_name": "Alpha SHPK",
"nipt": "L91806031A",
"address": "Rruga X",
"city": "Tirane",
"company_type": "BUSINESS",
"name": "Agon",
"surname": "Hoxha",
"document_type": "ID",
"document_number": "I12345678A",
"nationality_code": "ALB",
"nationality_id": 1,
"telephone": "+355691234567",
"email": "[email protected]",
"customer_number": "CLI-001",
"gender": "M",
"birthday": "1990-01-15"
})
});
const data = await response.json();
Shembull përgjigjeje
{
"status": true,
"data": {
"client": {
"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"
}
}
}
{
"message": "Unauthenticated."
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"success": false,
"message": "Te dhena jo te sakta",
"errors": []
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}