fature.al është platforma e faturimit dhe fiskalizimit për bizneset në Shqipëri. Hap një llogari
Skip to content
fature.al API Menu

Krijo një klient

POST /api/v2/clients Requires authentication Rate limited by the `api-global` limiter v2

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

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.

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

Ndryshuar që nga v1:

What changed v1 v2
body client_type string, one of PERSON, COMPANY, required —
body company_name string, maxLength 255, nullable, required —
body nipt string, maxLength 20, nullable, required —
body address string, maxLength 255, nullable object, nullable
body city string, maxLength 50, nullable, required —
body company_type string, one of BUSINESS, BANK, EXCHANGE, nullable, optional —
body name string, maxLength 255, nullable, required —
body surname string, maxLength 255, nullable, required —
body document_type string, one of NUIS, ID, PASS, VAT, TAX, SOC, nullable, required —
body document_number string, maxLength 255, nullable, required —
body nationality_code string, minLength 3, maxLength 3, nullable, optional —
body nationality_id integer, nullable, optional —
body telephone string, maxLength 255, nullable, optional —
body email string<email>, maxLength 255, nullable, optional —
body gender string, maxLength 10, nullable, optional —
body birthday string<date-time>, nullable, optional —
body type — string, one of company, person, required
body company — object, required
body person — object, required
200 data.client.name string —
200 data.client.client_type string, nullable —
200 data.client.company_name string, nullable —
200 data.client.company_type string, nullable —
200 data.client.nipt string, nullable —
200 data.client.first_name string, nullable —
200 data.client.surname string, nullable —
200 data.client.birthday string, nullable —
200 data.client.id_type string, nullable —
200 data.client.id_num string, nullable —
200 data.client.nationality_code string, nullable —
200 data.client.nationality_id integer, nullable —
200 data.client.telephone string, nullable —
200 data.client.email string, nullable —
200 data.client.address string, nullable object
200 data.client.city string, nullable —
body address required optional
body contact — object, nullable, optional
200 data.client.address nullable never null
200 data.client.type — string
200 data.client.company — object, nullable
200 data.client.company.name — string, nullable
200 data.client.company.category — string, nullable
200 data.client.company.id — object
200 data.client.company.id.type — any
200 data.client.company.id.value — any
200 data.client.person — object, nullable
200 data.client.person.first_name — string, nullable
200 data.client.person.last_name — string, nullable
200 data.client.person.birthday — string, nullable
200 data.client.person.id — object
200 data.client.person.id.type — any
200 data.client.person.id.value — any
200 data.client.address.line — string, nullable
200 data.client.address.city — string, nullable
200 data.client.address.country — string, nullable
200 data.client.contact — object
200 data.client.contact.phone — string, nullable
200 data.client.contact.email — string, nullable
200 data.client.verified — boolean
200 data.client.updated_at — string, nullable

Body parameters

Name Tipi E detyrueshme Përshkrimi
type string, one of company, person yes Lloji i klientit: `company` ose `person`. I detyrueshëm; vendos cili objekt plotësohet. Në përditësim nuk ndryshohet: një `type` i ndryshëm nga ai ekzistues refuzohet me `422`.
company object yes Të dhënat e kompanisë. Të detyrueshme kur `type` është `company`. Required depending on type.
company.name string, maxLength 255, nullable yes Emri i kompanisë. I detyrueshëm për `company`. Required depending on type.
company.category string, one of business, bank, exchange, nullable no Kategoria e kompanisë: `business`, `bank` ose `exchange`.
company.id object yes Identifikuesi i kompanisë, si objekt me `type` dhe `value`. I detyrueshëm për `company`. Required depending on type.
company.id.type string, one of nuis, vat, tax yes Lloji i identifikuesit: `nuis` për një biznes shqiptar, `vat` ose `tax` për një biznes të huaj. Required when company.id is present.
company.id.value string, maxLength 20 yes Vlera e identifikuesit, p.sh. NIPT-i kur `type` është `nuis`. Deri në 20 karaktere. Required when company.id is present.
person object yes Të dhënat e personit. Të detyrueshme kur `type` është `person`. Required depending on type.
person.first_name string, maxLength 255, nullable yes Emri. I detyrueshëm për `person`. Required depending on type.
person.last_name string, maxLength 255, nullable yes Mbiemri. I detyrueshëm për `person`. Required depending on type.
person.birthday string<date-time>, nullable no Data e lindjes, `YYYY-MM-DD`.
person.id object yes Dokumenti i identifikimit, si objekt me `type` dhe `value`. I detyrueshëm për `person`. Required depending on type.
person.id.type string, one of id, passport, social yes Lloji i dokumentit: `id` kartë identiteti, `passport` pasaportë, `social` numër i sigurimeve shoqërore. Required when person.id is present.
person.id.value string, maxLength 255 yes Numri i dokumentit. Required when person.id is present.
address object, nullable no Adresa e klientit. Opsionale, e njëjta për të dy llojet.
address.line string, maxLength 255, nullable no Rruga dhe numri.
address.city string, maxLength 50, nullable no Qyteti.
address.country string, minLength 3, maxLength 3, nullable no Shteti, kod ISO 3166-1 alpha-3. Pa të merret `ALB`.
contact object, nullable no Kontaktet e klientit. Opsionale.
contact.phone string, maxLength 255, nullable no Telefoni.
contact.email string<email>, maxLength 255, nullable no Email-i.
customer_number string, maxLength 30, nullable no Numri i klientit në sistemin tuaj, nëse mbani një të tillë.

Përgjigjet

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.

Field Tipi Përshkrimi
status boolean
data object
data.client object
data.client.id integer Id-ja e klientit në fature.al
data.client.type string `company` ose `person`
data.client.company object, nullable I plotësuar kur `type` është `company`, përndryshe null
data.client.company.name string, nullable Emri i kompanisë
data.client.company.category string, nullable `business`, `bank` ose `exchange`; null kur kompania nuk është klasifikuar
data.client.company.id object Identifikuesi fiskal i kompanisë, zakonisht NIPT-i
data.client.company.id.type any `nuis`, `vat` ose `tax` te një kompani; `id`, `passport` ose `social` te një person
data.client.company.id.value any Vetë identifikuesi; null kur klienti nuk ka asnjë të regjistruar
data.client.person object, nullable I plotësuar kur `type` është `person`, përndryshe null
data.client.person.first_name string, nullable Emri
data.client.person.last_name string, nullable Mbiemri
data.client.person.birthday string, nullable Datëlindja, `YYYY-MM-DD`
data.client.person.id object Dokumenti i identifikimit të personit
data.client.person.id.type any `nuis`, `vat` ose `tax` te një kompani; `id`, `passport` ose `social` te një person
data.client.person.id.value any Vetë identifikuesi; null kur klienti nuk ka asnjë të regjistruar
data.client.address object Adresa e klientit
data.client.address.line string, nullable Rruga dhe numri
data.client.address.city string, nullable Qyteti
data.client.address.country string, nullable Kodi i shtetit, ISO 3166-1 alpha-3
data.client.contact object Telefoni dhe email-i i klientit
data.client.contact.phone string, nullable Numri i telefonit
data.client.contact.email string, nullable Adresa e email-it
data.client.customer_number string, nullable Referenca juaj për këtë klient, kur e keni dhënë
data.client.verified boolean true kur identifikuesi i klientit është konfirmuar te administrata tatimore
data.client.created_at string, nullable Data dhe ora e krijimit, ISO 8601
data.client.updated_at string, nullable Data dhe ora e ndryshimit të fundit, 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 të njëjtat të dhëna.

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
curl -X POST 'https://fature.al/api/v2/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 '{
    "type": "company",
    "company": {
        "name": "Jane Doe",
        "category": "business",
        "id": {
            "type": "nuis",
            "value": "value"
        }
    },
    "person": {
        "first_name": "Jane",
        "last_name": "Doe",
        "birthday": "2026-01-15T09:30:00Z",
        "id": {
            "type": "id",
            "value": "value"
        }
    },
    "address": {
        "line": "line",
        "city": "Berlin",
        "country": "USx"
    },
    "contact": {
        "phone": "+15551234567",
        "email": "[email protected]"
    },
    "customer_number": "CL-00412"
}'
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',
    'Content-Type' => 'application/json',
])->post('https://fature.al/api/v2/clients', [
    'type' => 'company',
    'company' => [
        'name' => 'Jane Doe',
        'category' => 'business',
        'id' => [
            'type' => 'nuis',
            'value' => 'value',
        ],
    ],
    'person' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'birthday' => '2026-01-15T09:30:00Z',
        'id' => [
            'type' => 'id',
            'value' => 'value',
        ],
    ],
    'address' => [
        'line' => 'line',
        'city' => 'Berlin',
        'country' => 'USx',
    ],
    'contact' => [
        'phone' => '+15551234567',
        'email' => '[email protected]',
    ],
    'customer_number' => 'CL-00412',
]);

$data = $response->json();
PHP (Guzzle)
use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://fature.al/api/v2/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' => [
        'type' => 'company',
        'company' => [
            'name' => 'Jane Doe',
            'category' => 'business',
            'id' => [
                'type' => 'nuis',
                'value' => 'value',
            ],
        ],
        'person' => [
            'first_name' => 'Jane',
            'last_name' => 'Doe',
            'birthday' => '2026-01-15T09:30:00Z',
            'id' => [
                'type' => 'id',
                'value' => 'value',
            ],
        ],
        'address' => [
            'line' => 'line',
            'city' => 'Berlin',
            'country' => 'USx',
        ],
        'contact' => [
            'phone' => '+15551234567',
            'email' => '[email protected]',
        ],
        'customer_number' => 'CL-00412',
    ],
]);

$data = json_decode((string) $response->getBody(), true);
JavaScript
const response = await fetch('https://fature.al/api/v2/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({
      "type": "company",
      "company": {
          "name": "Jane Doe",
          "category": "business",
          "id": {
              "type": "nuis",
              "value": "value"
          }
      },
      "person": {
          "first_name": "Jane",
          "last_name": "Doe",
          "birthday": "2026-01-15T09:30:00Z",
          "id": {
              "type": "id",
              "value": "value"
          }
      },
      "address": {
          "line": "line",
          "city": "Berlin",
          "country": "USx"
      },
      "contact": {
          "phone": "+15551234567",
          "email": "[email protected]"
      },
      "customer_number": "CL-00412"
  })
});

const data = await response.json();

Shembull përgjigjeje

200
{
    "status": true,
    "data": {
        "client": {
            "id": 8123,
            "type": "company",
            "company": {
                "name": "Alba Trade shpk",
                "category": "business",
                "id": {
                    "type": "nuis",
                    "value": "K91807012A"
                }
            },
            "person": {
                "first_name": "Arben",
                "last_name": "Hoxha",
                "birthday": "1985-04-21",
                "id": {
                    "type": "nuis",
                    "value": "K91807012A"
                }
            },
            "address": {
                "line": "Rruga e Kavajës 12",
                "city": "Tiranë",
                "country": "ALB"
            },
            "contact": {
                "phone": "+355 69 234 5678",
                "email": "[email protected]"
            },
            "customer_number": "CL-0042",
            "verified": true,
            "created_at": "2026-03-02T09:30:00+01:00",
            "updated_at": "2026-09-10T16:45:00+02:00"
        }
    }
}
401
{
    "message": "Unauthenticated."
}
403
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}
409
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}
422
{
    "success": false,
    "message": "Te dhena jo te sakta",
    "errors": []
}
429
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}
500
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}

Regjistrimi është falas.

Regjistrohu në fature.al

This page as Markdown, or the whole API as OpenAPI.